API conventions

https://api.rizamo.com/v1

JSON in, JSON out, with your API key as a bearer token (Authentication). openapi.json describes every endpoint, with its errors and an example of each call, and names the objects it returns (Post, Account, Error...) so an SDK generator makes one type of each.

IdsCopy Anchor Link

Every id starts with its type. Treat the rest as an opaque string.

A custom field is named by its key, and a post's place on a network by networkId.

Dates and time zonesCopy Anchor Link

• Times are ISO 8601 strings, answered in UTC: 2026-11-03T09:00:00.000Z.
• Send them in UTC or with an offset. A post's scheduledAt may also be a local time (Publishing).
• Days, such as analytics days, are dates like 2026-11-03. Each answer or field says which time zone its days are in.
• A time zone is a name such as Europe/Lisbon. An offset such as +01:00 is not one: it ignores summer time.

PagesCopy Anchor Link

• cursor: pass the answer's nextCursor as cursor, with the same filters and order, for the next page. nextCursor is null on the last page.
• offset: the next page starts at offset plus limit; total is how many there are in all.
• One page: the whole list in one answer.
• A thread's messages: GET /inbox/threads/{id} answers every message, or with limit the newest ones and a nextCursor: pass it as before for the ones before them.

Every list answers its items in items.

RetriesCopy Anchor Link

Send an Idempotency-Key header on every POST, a new one for each request (a UUID). For 24 hours, the same request with the same key gets the first answer, with Idempotent-Replayed: true, instead of running again. Errors has every rule. Over MCP, tools that change something take it as an idempotencyKey argument.

Rate limitsCopy Anchor Link

Each team makes up to 600 calls a minute, 120 of them writes, through the API and MCP together. Limits says which calls count as writes. Over a limit, the answer is 429 with a Retry-After header and a RateLimit-Policy header; no header says how many calls are left.

VersionsCopy Anchor Link

• The version is in the path: /v1.
• A breaking change, such as a field removed or renamed or a new required field, ships only in a new version, after a deprecation with a date and at least 90 days' notice, unless a network, the law or a security issue forces a shorter period (Terms, section 6).
• Within v1, Rizamo adds endpoints, fields, values and event types. Ignore those your code does not know.
• The names of the objects in openapi.json stay as they are within v1, and every change to it is checked against the last one for breaking changes before it ships.
• The changelog lists every change, and marks the ones you must act on.

ErrorsCopy Anchor Link

Every error answers a matching HTTP status and the same shape: { "error": { "code": "...", "message": "..." }, "requestId": "req_..." }. Branch on code, show message to people. Errors lists the codes.

Status and supportCopy Anchor Link

• Status page: incidents and maintenance.
• hi@rizamo.com: questions. Send the requestId of a call that failed.