Requests and responses

The REST API uses JSON over HTTPS with the base URL https://api.subdomain.to/v1.

JSON format

Send Content-Type: application/json. A resource is wrapped in data:

{"data":{"id":"01J00000000000000000000000"}}

A collection also includes pagination metadata:

{"data":[],"meta":{"has_more":false,"next_cursor":null}}

Idempotency

Creating a destination, domain, webhook endpoint, or widget session requires Idempotency-Key, limited to 128 characters. Reusing the same key for the same operation returns the original response with Idempotent-Replayed: true.

Choose a stable business key such as customer-42-domain-1 and keep it across network retries. Official SDKs never retry implicitly.

Pagination

List operations accept limit from 1 to 100, defaulting to 25, and an optional cursor. The current version returns one page with has_more: false and next_cursor: null.

Errors

{
  "error": {
    "code": "bad_request",
    "message": "A valid Idempotency-Key header is required.",
    "request_id": "req_01J..."
  }
}

HTTP	Code	Recommended action
`400`	`bad_request`	Fix JSON, parameters, or the idempotency key
`401`	`unauthorized`	Provide a valid Bearer key
`403`	`forbidden`	Add the required scope
`404`	`not_found`	Check the identifier and organization
`409`	`conflict`	Resolve the uniqueness or state conflict
`422`	`validation_failed`	Correct the business data
`500`	`internal_error`	Retry, then send the request ID to support

Do not branch on the message text. Use code and the HTTP status.