HTTP API overview

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

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 with your client credentials	Everything the install’s 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	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

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.

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:

{
  "_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 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 instead.

Overview

Install

Blocks

References

Replies, streams and notifications

Invocations

Search and memories

Deploy

Tooling

Base URL

Credentials

Reach

The app as author

Errors

Retries and idempotency

Compatibility

Member API

​Base URL

​Credentials

​Reach

​The app as author

​Errors

​Retries and idempotency

​Compatibility

​Member API

Base URL

Credentials

Reach

The app as author

Errors

Retries and idempotency

Compatibility

Member API