Skip to content

Conventions

Every Elaichi API endpoint follows the same patterns. When you have used one resource, you can predict the others.

URL patterns

Pattern Shape Examples
Standard CRUD GET and POST /resource, then GET, PATCH, and DELETE /resource/:id /role, /toolbox, /connection
Actions POST /resource/:id/<verb> verify, reconnect, execute, test
Nested collections /resource/:id/<collection> and /resource/:id/<collection>/:childId members, share

To change a field, send PATCH /resource/:id with only the fields that changed. Actions are for things that do something, such as verifying a domain or reconnecting a connection. They are not for editing a field.

Paths have no version prefix. Use /connection, not /v1/connection.

Pagination

Every endpoint that returns a list answers with one page and cursors:

{
  "result": [],
  "next_cursor": "opaque-string-or-null",
  "prev_cursor": "opaque-string-or-null"
}
Parameter Behavior
limit Page size. The default is 50. The maximum is 200. A larger number is reduced to 200. Zero, a negative number, or a value that is not a number returns 400.
cursor Pass back the next_cursor you received. An empty value means the first page.
q Free-text search on endpoints that document it. At most 200 characters. A longer value returns 400.

Rules for lists:

  • Treat cursors as opaque. Pass back exactly what you received.
  • Keep requesting pages until next_cursor is null. A short or empty page does not mean the list ended.
  • Send search and filters to the server with q. Do not search, filter, or count in your own code over the pages you fetched. You would see only those pages.
  • When you change q or a filter, drop the cursor and ask for page one.

Rate limits

The API allows 600 requests per 60 seconds for each API token. When you go over the limit, the API answers 429 with the code rate_limited and a Retry-After header. The header gives the number of seconds to wait. Wait that long, then retry.

Errors

Errors use standard HTTP status codes and one body format:

{
  "error": {
    "message": "human readable explanation",
    "code": "machine_code"
  }
}

Branch on code. Show message when you need to tell a person.

Status Code Usually means
400 bad_request The request was malformed.
400 validation_error A field failed validation.
400 missing_organization_header The request needs X-Organization-Id. API tokens do not need it.
401 unauthorized The token is missing, wrong, or revoked.
403 permission_required The token is valid, but its owner lacks a permission. details.required_permissions lists it.
403 forbidden The action is not allowed, for example because it needs a person in a browser.
403 subscription_required The organization has no active plan.
403 feature_not_available The organization’s plan does not include this feature.
404 not_found The resource does not exist, or you cannot see it.
409 conflict The request clashes with the current state.
413 payload_too_large The request body is too large.
429 rate_limited Too many requests. Wait for Retry-After, then retry.
500 internal_error Something went wrong on the Elaichi side.

Some endpoints return more specific codes in the same format. Treat any code that you do not know by its status.

OpenAPI

A machine-readable description is available at GET /schema/openapi.yml and GET /schema/openapi.json. Use it to generate clients or to import the API into API tools.