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.
The address
Section titled “The address”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.
Signing in
Section titled “Signing in”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. A429is not kept, so its retry runs. - Keys are kept for at least 24 hours, per account.
Lists come in pages
Section titled “Lists come in pages”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).
Errors
Section titled “Errors”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" }}codeis what to act on: each code has its own page, the onedocslinks to. See all error codes.messageis English for your logs; it may change, so never match on it.faultsays 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, orundetermined(the evidence could not tell, and a person is looking).request_idnames this request. Every answer, an error or not, also carries it in theX-Request-Idheader: quote it when you ask about a request.retry_afteris how many seconds to wait when the answer says to wait, andnullotherwise. Over a rate limit the answer is429with aRetry-Afterheader; see API keys for the limits.- Some errors carry a
detailsobject with the specifics of the case.
When something is on its way out
Section titled “When something is on its way out”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).
Notifications and Terraform
Section titled “Notifications and Terraform”- 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.