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

# HTTP API overview

> Base URL, credentials, reach, errors and compatibility rules for the endpoints apps and their tooling call.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

Apps call the Reintersect API to insert and update blocks, push reference fields, send
notifications, post replies, and add search objects and memories. The CLI and the GitHub Action call
the tooling endpoints to sync manifests, upload versions and manage environment variables. The SDK
wraps the app endpoints with types derived from your app; use plain HTTP when you work in another
language.

## Base URL

```text theme={null}
https://api.reintersect.com
```

App endpoints live under `/v0`. Requests and responses are JSON unless a page says otherwise.

## Credentials

Send a credential in the `authorization` header. Each endpoint's page says which credential it takes:

| Credential | Format | Where it comes from | Used for |
| - | - | - | - |
| Install token | `reiapp_…`, a one-hour JWT | The `installToken` of a delivery, or [minted](/api-reference/install/access-tokens) with your client credentials | Everything the install's [scopes](/reference/scopes) allow, in that workspace |
| Interaction token | `reiint_…`, valid 15 minutes | The `interactionToken` of a `block.action` delivery | Reading and updating the one block the action ran on |
| Client credentials | HTTP Basic, `client_id:client_secret` | **Settings → Developer → Apps → your app** | Minting install tokens |
| Member API key | Bearer | `reintersect login`, or **Settings → Developer → API keys** | Tooling endpoints, as the app's owner or a workspace admin |
| Deploy token | `reidep_…`, valid 15 minutes | [GitHub OIDC exchange](/api-reference/deploy/oidc-token) | Tooling endpoints for one app, from CI |
| Agent builder token | Brokered by Reintersect | Issued to the agent builder's sandbox for one turn | Tooling endpoints for apps the member owns, previews only |

```bash theme={null}
curl https://api.reintersect.com/v0/blocks/blk_01J9Z5 \
  -H "authorization: Bearer $INSTALL_TOKEN"
```

Hosted apps never handle install tokens: the hosted runtime adds them to requests your code makes to
the Reintersect API.

## Reach

Writes follow the same rule as events. An install can insert blocks and post replies in public
circles and in private circles the app was invited to, and never in connected circles. A development
install can only write in circles its developer belongs to. A target outside that reach answers
`ReintersectApiConversationNotFoundError` or `ReintersectApiReplyNotFoundError`, exactly as if it didn't
exist. Block updates only touch blocks the same install created. See
[Install and consent](/concepts/install-and-consent#reach).

## The app as author

Replies, blocks and notifications your app creates are attributed to your app in that workspace,
with its name and icon.

## Errors

An error response is JSON with a `_tag` naming the failure, a `message`, the `path` of the field that
caused it (often empty) and the error's own fields:

```json theme={null}
{
  "_tag": "ReintersectAppBlockVersionConflictError",
  "message": "The block changed since version 7.",
  "path": ["expectedVersion"],
  "blockId": "blk_01J9Z5",
  "expectedVersion": 7,
  "currentVersion": 8
}
```

Every endpoint can return these:

| `_tag` | Status | Meaning |
| - | - | - |
| `ReintersectApiInvalidRequestError` | 400 | The request doesn't match the schema. `issues` lists each problem with its `path`. |
| `ReintersectAppTokenMissingError` | 401 | No credential. |
| `ReintersectAppTokenInvalidError` | 401 | The credential is invalid or expired. |
| `ReintersectAppInteractionExpiredError` | 401 | The interaction token expired. Use an install token. |
| `ReintersectAppInstallRevokedError` | 403 | The install was uninstalled or suspended. |
| `ReintersectApiRateLimitExceededError` | 429 | Slow down. |
| `ReintersectApiInternalServerError` | 500 | Something failed on Reintersect's side. |
| `ReintersectApiServiceUnavailableError` | 503 | Try again shortly. |

Each endpoint's page lists its own errors; [Errors](/api-reference/errors) lists them all.

## Retries and idempotency

The API has no idempotency keys. Retry reads freely on `503` and network errors, with backoff. For
writes, use the guard each endpoint offers instead of blind retries: `expectedVersion` on block
updates, `version` on reference pushes, `updatedAt` on search objects.

## Compatibility

* Requests are strict: the API rejects unknown fields, so a typo fails the request instead of being
  ignored.
* Responses may gain new fields at any time. Ignore fields you don't recognize.
* String values documented as a closed list, such as a status, may gain new values. Handle an unknown
  value as the most neutral option you have.
* Breaking changes go to a new version prefix.

## Member API

The API also serves the member API that existed before apps, for circles, conversations, replies and
files, to member API keys. The `@reintersect/sdk` README documents it. Apps post replies through
[`POST /v0/replies`](/api-reference/replies/create) instead.


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