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. Three exceptions: the OAuth token and device endpoints use application/x-www-form-urlencoded per the OAuth spec, the PDF extract and document upload endpoints take multipart/form-data, and the filled-form download returns binary application/pdf.
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.
`402 Payment Required`	The workspace hit its plan cap (see Plan limits).
`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 (see Rate limiting).

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.

Plan limits

Each workspace is on a plan, visible on GET /org/me as plan. On the free plan, a workspace can create 5 sessions per calendar month. When the cap is used up, POST /org/sessions returns 402 Payment Required with a detail explaining the limit. Everything else keeps working: existing sessions can still be answered, filled, downloaded, and submitted. Upgrading the workspace in Bindly lifts the cap.

Treat 402 as a signal to a human, not something to retry: the request will keep failing until the month rolls over or the workspace upgrades.

Rate limiting

Endpoints that do heavy work (intake answering, PDF extraction, form filling, risk analysis) are rate limited per workspace. When you exceed the limit the API returns 429 Too Many Requests with a Retry-After header giving the number of seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 12

Honor Retry-After and retry once it elapses; a simple wait-and-retry loop is enough. Requests that are spaced out normally, including a full intake lifecycle run end to end, stay well under the limits.

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.