Conventions

Conventions that hold across both API surfaces.

Identifiers

Prefixed, so an id is self-describing in a log line:

Treat identifiers as opaque strings. The formats above are stable enough to recognise in a log and not stable enough to parse — a memory serial, for instance, is sequential today and that is an implementation detail, not a contract.

Memory hostnames

Each memory has its own host, derived from its serial:

https://{slug}-{serial}.api.uni-flow.ai

Use it with a per-memory key when you want a credential that reaches one memory.

Requests

Content-Type: application/json on anything with a body, except file uploads, which are multipart/form-data.

Timestamps

ISO 8601, UTC, always:

{ "created_at": "2026-07-30T14:22:05.184Z" }

Pagination

List endpoints accept limit and return newest-first. Where an endpoint paginates, it returns a cursor:

{
  "events": [],
  "next_cursor": "eyJ0cyI6MTc1..."
}

Pass it back as cursor. A missing or null next_cursor means the end. Do not construct cursors — they are opaque and their encoding will change.

Idempotency

Operations with a natural key are idempotent by construction: replaying a credit grant or a metering event is a no-op rather than a double-charge.

For your own retries, be idempotent on the receiving side too — especially for webhooks, where redelivery is normal rather than exceptional.

Rate limits

Applied per credential at the gateway. See Rate limits.

Versioning

Every public route sits under /api/v1/. Responses carry an API version header.

Additive changes — a new optional field, a new endpoint — happen within v1. Parse defensively: ignore fields you do not recognise rather than rejecting the response, or a purely additive change becomes a breaking one on your side.