Conventions

A few rules hold across every endpoint. Learn them once and the rest of the API is predictable.

Requests

JSON over HTTPS. Request and response bodies are JSON. Send Content-Type: application/json on requests with a body. The one exception is the OAuth token and device endpoints, which use application/x-www-form-urlencoded per the OAuth spec.
Bearer auth. Every request carries a short-lived OAuth 2.1 bearer token:
```
Authorization: Bearer <token>
```
There are no static API keys. See Authentication.
Base URL. All endpoints live under https://api.hedgespecialty.com/api/v1.

Status codes

The API uses standard HTTP status codes. In general, 2xx means success, 4xx means the request was wrong or not allowed, and 5xx means something failed on our side.

Code	Meaning
`200 OK`	The request succeeded.
`201 Created`	A resource was created (for example, a submission).
`400 Bad Request`	The request was malformed.
`401 Unauthorized`	The token is missing, expired, or invalid.
`403 Forbidden`	The token is valid but lacks the scope for this action.
`404 Not Found`	The resource does not exist, or it belongs to another brokerage (see Data scoping).
`409 Conflict`	The request conflicts with the current state of the resource.
`422 Unprocessable Content`	Validation failed on one or more fields.
`429 Too Many Requests`	You are being rate limited. Back off and retry.

Errors

Errors return a JSON body with a detail field describing what went wrong:

{
  "detail": "Not authorized to act on this account."
}

Read detail for a human-readable explanation, and use the HTTP status code to decide how to react programmatically.

Scopes

Write access is gated by scope. Read endpoints accept a token with the broker_mcp scope; endpoints that create or change anything require the broker_submit scope. A request with a valid token but the wrong scope returns 403 Forbidden.

Scope	Grants
`broker_mcp`	Read: submissions, policies, payments, appetite.
`broker_submit`	Write: create submissions, upload documents, answer quote questions, finalize.

Data scoping

Every token is bound to exactly one brokerage, and all data is scoped to that brokerage. The brokerage comes from the authenticated broker, never from the request body, so you cannot read or write another brokerage’s data.