# Instant integrator API

What an integrator's servers call to run their customers in Instant: the customers, their members and the members' tokens, the webhook Instant posts to, and the return URL. Every request carries the integrator's credential as `Authorization: Bearer <credential>`. Ids are UUIDs, matched in any case and answered in lower case; a path id that is not a UUID is the same 404 as an unknown one, and so is another integrator's object. Bodies are strict: a field a route does not take is 400. A route that takes a query is strict about it too; a route that takes none ignores one. Every answer but the docs' is `Cache-Control: no-store`; the docs answer `private, no-cache` with an ETag. A field may be added to an answer at any time, so ignore fields you do not know.

- Base URL: `https://app.booksbyinstant.com`
- Version: 1
- Spec: https://booksbyinstant.com/docs/openapi.json (OpenAPI 3.1.0)
- Guide: [Instant integrator API guide](https://booksbyinstant.com/docs/guide/), as markdown at https://booksbyinstant.com/docs/guide/index.md

Every page below is also markdown, at its address plus `index.md`.

## Authentication

- Bearer token `live_<100 hex>`: `Authorization: Bearer <secret>`. A 401 answers `WWW-Authenticate: Bearer realm="instant-integrator-api"`.

## Integrator

Which integrator a credential belongs to.

- [Read the integrator](https://booksbyinstant.com/docs/integrator-me/): `GET /api/integrator/v1/me`

## Customers

The integrator's customers: each is a company in Instant, created with its first member, who owns it.

- [List customers](https://booksbyinstant.com/docs/list-customers/): `GET /api/integrator/v1/customers`
- [Create a customer](https://booksbyinstant.com/docs/create-customer/): `POST /api/integrator/v1/customers`
- [Read a customer](https://booksbyinstant.com/docs/read-customer/): `GET /api/integrator/v1/customers/{id}`
- [Pause, resume or hand over a customer](https://booksbyinstant.com/docs/update-customer/): `PATCH /api/integrator/v1/customers/{id}`
- [List a customer's entities](https://booksbyinstant.com/docs/list-entities/): `GET /api/integrator/v1/customers/{id}/entities`

## Members

The people of a customer, each with a role and entity access.

- [List a customer's members](https://booksbyinstant.com/docs/list-members/): `GET /api/integrator/v1/customers/{id}/members`
- [Add a member](https://booksbyinstant.com/docs/create-member/): `POST /api/integrator/v1/customers/{id}/members`
- [Read a member](https://booksbyinstant.com/docs/read-member/): `GET /api/integrator/v1/customers/{id}/members/{memberId}`
- [Change, deactivate or reactivate a member](https://booksbyinstant.com/docs/update-member/): `PATCH /api/integrator/v1/customers/{id}/members/{memberId}`

## Member tokens

The secrets a member's requests to the customer API carry. The integrator issues them.

- [List a member's tokens](https://booksbyinstant.com/docs/list-member-tokens/): `GET /api/integrator/v1/customers/{id}/members/{memberId}/tokens`
- [Issue a member token](https://booksbyinstant.com/docs/issue-member-token/): `POST /api/integrator/v1/customers/{id}/members/{memberId}/tokens`
- [Revoke a member token](https://booksbyinstant.com/docs/revoke-member-token/): `DELETE /api/integrator/v1/customers/{id}/members/{memberId}/tokens/{tokenId}`

## Webhook

Where Instant posts what happens in the integrator's customers and when the docs change, and the deliveries it made.

- [Read the webhook](https://booksbyinstant.com/docs/read-webhook/): `GET /api/integrator/v1/webhook`
- [Set the webhook](https://booksbyinstant.com/docs/set-webhook/): `PUT /api/integrator/v1/webhook`
- [Remove the webhook](https://booksbyinstant.com/docs/clear-webhook/): `DELETE /api/integrator/v1/webhook`
- [List webhook deliveries](https://booksbyinstant.com/docs/list-deliveries/): `GET /api/integrator/v1/webhook/deliveries`

## Return URL

Where a member's browser comes back after connecting a mailbox, a calendar or a bank.

- [Read the return origins](https://booksbyinstant.com/docs/read-return-origins/): `GET /api/integrator/v1/return-origins`
- [Set the return origins](https://booksbyinstant.com/docs/set-return-origins/): `PUT /api/integrator/v1/return-origins`
- [Read the return URL](https://booksbyinstant.com/docs/read-return-url/): `GET /api/integrator/v1/return-url`
- [Set the return URL](https://booksbyinstant.com/docs/set-return-url/): `PUT /api/integrator/v1/return-url`
- [Clear the return URL](https://booksbyinstant.com/docs/clear-return-url/): `DELETE /api/integrator/v1/return-url`

## Docs

This API's reference and guide, and the customer API's, as Instant serves them now.

- [Read a guide](https://booksbyinstant.com/docs/read-guide/): `GET /api/integrator/v1/docs/guide.md`
- [Read an OpenAPI reference](https://booksbyinstant.com/docs/read-open-api/): `GET /api/integrator/v1/docs/openapi.json`

## Webhooks

- [`approval.due`](https://booksbyinstant.com/docs/webhooks/#approval-due): A member's turn to approve
- [`browser.takeover_needed`](https://booksbyinstant.com/docs/webhooks/#browser-takeover_needed): Reserved: not sent yet
- [`connection.expired`](https://booksbyinstant.com/docs/webhooks/#connection-expired): A bank consent ran out
- [`connection.synced`](https://booksbyinstant.com/docs/webhooks/#connection-synced): A bank backfill or asked read ended
- [`customer.paused`](https://booksbyinstant.com/docs/webhooks/#customer-paused): A customer was paused
- [`customer.resumed`](https://booksbyinstant.com/docs/webhooks/#customer-resumed): A customer was resumed
- [`docs.updated`](https://booksbyinstant.com/docs/webhooks/#docs-updated): The docs changed
- [`link.finished`](https://booksbyinstant.com/docs/webhooks/#link-finished): A bank link ended
- [`ping.raised`](https://booksbyinstant.com/docs/webhooks/#ping-raised): A notice to a member
- [`reply.ready`](https://booksbyinstant.com/docs/webhooks/#reply-ready): A chat reply is ready
- [`run.finished`](https://booksbyinstant.com/docs/webhooks/#run-finished): Background work finished
- [`task.input_needed`](https://booksbyinstant.com/docs/webhooks/#task-input_needed): A task needs its owner

## For agents and tools

- [llms.txt](https://booksbyinstant.com/docs/llms.txt): an index of every page's markdown
- [llms-full.txt](https://booksbyinstant.com/docs/llms-full.txt): the guide, every operation and the webhooks in one file
- [openapi.json](https://booksbyinstant.com/docs/openapi.json): the OpenAPI document
- [search-index.json](https://booksbyinstant.com/docs/search-index.json): what the search box searches

## Versions

- openapi.json: SHA-256 `2254e14395856652b73a0371ff5256341991186a93ca59ff8a6f9e26f5318b09`
- guide/index.md: SHA-256 `77ab80d3a775f01d0a8f7712734b5cdd2ce13549408f00464e886c6ab5a9961d`