Conventions

Requests and responses

Send and read JSON. A request that creates a row answers 201. A request with an invalid body answers 400.

Errors

An error has an HTTP status and a JSON body. Read the status first.

Status	Meaning
`400`	A field is missing or wrong.
`401`	The token is missing, wrong, expired or revoked.
`403`	The token’s member may not do this.
`404`	There is no such row, or the member cannot see it.
`429`	You sent too many requests. Wait, then try again.

Most errors have a detail with a sentence for a person:

{"detail": "You are not a member of that workspace."}

A 400 for a bad body names each field with what to fix:

{"sort": "Sort by one of: name, updated."}

A rate limit error also has code and retry_after. Read Rate limits. Do not parse the sentence in detail. It can change. Use the status and, where it exists, code.

Pages

A route that lists rows for a table returns one page:

{"results": [], "count": 0, "page": 1, "page_size": 20, "pages": 1}

These query parameters work on such a route:

Parameter	Meaning
`page`	The page number, from 1. A number past the last page gives the last page.
`page_size`	Rows on a page, from 1 to 100. The default is 20.
`q`	Search words. Each word must match.
`sort`	A column the route lists. A column it does not list gives `400`.
`order`	`asc` or `desc`.
`<filter>`	A filter the route lists, for example `status`.

Some feed routes read newest first and use a cursor, not a page number. A timeline or a list of deliveries takes before with a time, and returns next for the following request. The list of conversations takes offset. The API reference shows the parameters of each route.

Ids

An id is a UUID in text form, such as 3f2b8c1e-5a4d-4e6f-9b7a-1c2d3e4f5a6b. Send it in the path. Apps use their own slug in the path.

Time

ImpelLabs stores time in UTC. A time in a response is an ISO 8601 text. Show times to a person in their own zone.

Deleting

Rows are not erased. A delete marks the row as archived and removes it from lists. Some archived rows come back with a restore route, for example a record of an app or a knowledge group. The reference names these routes.

Rate limits

The MCP endpoint takes a set number of requests a minute for each token. The limits are in MCP limits. Over the limit, the answer is 429:

{"detail": "Too many requests with this token. Wait a minute, then try again.",
 "code": "rate_limited", "retry_after": 42}

retry_after is in seconds. The response has a Retry-After header with the same value. Wait that long, then send the request again. An outgoing webhook endpoint has its own rate in deliveries a minute. A delivery over the rate waits and is sent later. See Webhooks.

Retries

A request has no idempotency key. If a request that creates a row times out, list the rows before you send it again. Routes that read are safe to repeat.

Live and test

The API has no separate test mode. Use a separate workspace for tests. A webhook endpoint can be live or staging. A staging endpoint takes test events and replays only.

Get started

Resources

Events

Build

API reference