Requests and responses

How calls are shaped: addresses, inputs, headers and the formats used for dates, money and ids.

Addresses

Every endpoint starts with your workspace’s address, then the app’s path:

Address

https://api.olamma.sh/v1/w/{workspace}/tables/{tableId}/records

Words in braces are values you fill in: ids you got from an earlier call, like a table id from List bases.

Inputs

Reads (GET) take their options in the query string, like ?limit=50.
Writes (POST, PATCH, DELETE) take a JSON body. A write with a query string is refused, so nothing you send is silently ignored.
Unknown fields are refused with invalid, so a typo shows up straight away instead of being dropped.

Headers

Header	In	Meaning
`Authorization`	Request	Bearer oak_… on every call.
`Content-Type`	Request	application/json whenever you send a body.
`Idempotency-Key`	Request	On writes, so a retry never writes twice. See Retries.
`x-request-id`	Response	A unique id for the call. Quote it if you contact us.
`Idempotent-Replayed`	Response	true when the answer is the first outcome of a repeated Idempotency-Key.
`Retry-After`	Response	Seconds to wait after a 429.

Formats

Times	ISO 8601 in UTC, like `2026-12-01T09:30:00Z`.
Dates	`YYYY-MM-DD`, like `2026-12-15`.
Money	Whole minor units: `125000` is ₦1,250.00 in kobo. Never decimals.
Empty values	Send `null` to clear a value. Empty values are left out of answers.

Ids

Ids are opaque text with a prefix that tells you what they are. Store them as text and don’t build them yourself.

Prefix	Object
`tb_`	Base
`tt_`	Table
`tf_`	Field
`tv_`	View
`tr_`	Record
`tcm_`	Comment
`ap_`	Approval
`oak_`	API key (secret)

Answers

Single objects come under their name, like {"table": {…}}; lists come as a named list with a cursor, like {"records": […], "nextCursor": "…"}. Answers can gain new fields at any time, so ignore fields you don’t know. See Pagination and Untrusted text.