API Reference

All error responses follow this shape:

{
  "error": {
    "code": "validation_error",
    "message": "The 'name' field is required.",
    "param": "name"
  }
}

HTTP status codes

Resources

Create a resource

POST /v1/resources

Request body

Example request

curl -X POST https://api.yourdomain.com/v1/resources \
  -H "Authorization: Bearer $YOUR_PRODUCT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My resource",
    "description": "Created via the API.",
    "metadata": { "internal_id": "abc123" }
  }'

Example response

{
  "id": "res_xxxxxxxxxxxx",
  "object": "resource",
  "name": "My resource",
  "description": "Created via the API.",
  "status": "active",
  "metadata": { "internal_id": "abc123" },
  "createdAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

Retrieve a resource

GET /v1/resources/{id}

Path parameters

Example request

curl https://api.yourdomain.com/v1/resources/res_xxxxxxxxxxxx \
  -H "Authorization: Bearer $YOUR_PRODUCT_API_KEY"

List resources

GET /v1/resources

Query parameters

Example response

{
  "object": "list",
  "data": [
    { "id": "res_xxxxxxxxxxxx", "name": "My resource", "status": "active", ... }
  ],
  "hasMore": false,
  "nextCursor": null
}

The API uses cursor-based pagination. If hasMore is true, pass the nextCursor value as the cursor parameter in your next request.

Update a resource

PATCH /v1/resources/{id}

Only include the fields you want to change. Omitted fields are left unchanged.

Request body

Delete a resource

DELETE /v1/resources/{id}

Returns 204 No Content on success. Deletion is permanent and cannot be undone.

Jobs

Long-running operations return a job_id instead of the result directly. Use the Jobs endpoint to check progress.

Retrieve a job

GET /v1/jobs/{id}

Example response

{
  "id": "job_xxxxxxxxxxxx",
  "object": "job",
  "status": "completed",
  "result": { ... },
  "error": null,
  "createdAt": "2025-01-01T00:00:00.000Z",
  "completedAt": "2025-01-01T00:00:05.000Z"
}

Job statuses

Pagination

All list endpoints use cursor-based pagination. To iterate through all results:

let cursor: string | null = null

do {
  const response = await client.resources.list({ limit: 100, cursor })
  process(response.data)
  cursor = response.nextCursor
} while (response.hasMore)

Do not attempt to paginate using offset — it is not supported.

Idempotency

Supply an Idempotency-Key header on any POST request to safely retry without creating duplicates. See Core Concepts for details.