Skip to content

The REST API

Everything the app does goes through the same API you can call: sources, destinations, pipelines, their tables, runs, alerts, usage and notifications. A program calls it with an API key.

Every operation’s path starts /v1, at https://app.reyansh.ai/v1. Only https: a /v1 request over plain http is refused (400 https_required), never redirected, because whatever it carried has already crossed the network unencrypted.

Send an API key in the Authorization header: Authorization: Bearer <key>. Keys are made by an owner, either read only or full. API keys has how to create one, how to call with it, and the errors a key meets.

Changing something: the Idempotency-Key header

Section titled “Changing something: the Idempotency-Key header”

Every POST, PUT, PATCH and DELETE (other than signing in, under /v1/auth/) needs an Idempotency-Key header, a value of your own that is new for each change you intend (a UUID does). Without one the request is refused (400 idempotency_key_required) and nothing is done.

  • A key belongs to one method and path. Sent again to the same path with the same key and the same body, the request is not done twice: the first answer is given again, with the header Idempotent-Replay: true. So a retry after a timeout is safe.
  • The same key on the same path with a different body is refused (422 idempotency_key_reuse).
  • The same key on a different path is a different key, and that request runs. Never reuse a key across paths: two deletes of two pipelines with one key delete both.
  • While the first request is still being processed, a repeat is answered 409 idempotency_key_in_flight: retry after a moment. A 429 is not kept, so its retry runs.
  • Keys are kept for at least 24 hours, per account.

A list answers { "data": [...], "next_cursor": ... }. Ask for the next page by sending that next_cursor back as the cursor query parameter; it is null on the last page. limit sets the page size: 50 when left out, and at most 200 (a larger one is read as 200).

Every error has the same shape:

{
"error": {
"code": "unknown_field",
"message": "...",
"fault": "customer",
"request_id": "...",
"retry_after": null,
"docs": "https://docs.reyansh.ai/api/errors/unknown_field"
}
}
  • code is what to act on: each code has its own page, the one docs links to. See all error codes.
  • message is English for your logs; it may change, so never match on it.
  • fault says whose side the cause is on: customer (the request or something on your side needs to change), upstream (a system outside this service, such as a provider, refused or was unavailable), ours, or undetermined (the evidence could not tell, and a person is looking).
  • request_id names this request. Every answer, an error or not, also carries it in the X-Request-Id header: quote it when you ask about a request.
  • retry_after is how many seconds to wait when the answer says to wait, and null otherwise. Over a rate limit the answer is 429 with a Retry-After header; see API keys for the limits.
  • Some errors carry a details object with the specifics of the case.

A field or operation that is being retired is answered with a Deprecation header and a Sunset header naming the date it goes (RFC 9745 and RFC 8594).

  • Webhooks are signed, so you can tell a delivery came from us: see Verifying a delivery.
  • Sources, destinations and pipelines can be managed as code: see Terraform.