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.
Authenticated. Every /org request carries either a workspace API key or a short-lived OAuth 2.1 bearer token:
```
Authorization: Bearer bsk_live_xxx
```
A workspace API key may also be sent as X-API-Key. See Authentication.
Base URL. All endpoints live under https://engine.bindly.insure, with the workspace API at the /org prefix.

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, including creating a session.
`400 Bad Request`	The request was malformed, or the session cannot do this yet.
`401 Unauthorized`	The API key or token is missing, expired, or invalid.
`404 Not Found`	The session does not exist, or it belongs to another workspace (see Data scoping).
`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": "Session not found"
}

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

Data scoping

Every credential is bound to exactly one workspace, and all data is scoped to that workspace. The workspace identity comes from the verified API key or token, never from the request body, so you cannot read or write another workspace’s data.