> ## Documentation Index
> Fetch the complete documentation index at: https://docs.impellabs.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Conventions

> How the API shows errors, pages, ids, time and limits.

## 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:

```json theme={null}
{"detail": "You are not a member of that workspace."}
```

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

```json theme={null}
{"sort": "Sort by one of: name, updated."}
```

A rate limit error also has `code` and `retry_after`. Read [Rate limits](#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:

```json theme={null}
{"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](https://docs.impellabs.tech/connect/limits.md). Over the limit, the answer is `429`:

```json theme={null}
{"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](https://docs.impellabs.tech/api/webhooks.md).

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.