# Read a guide

`GET https://app.booksbyinstant.com/api/integrator/v1/docs/guide.md`

The guide to this API, or to the customer API with api=customer, as Instant serves it now: what the reference does not say, such as the conventions, authentication, errors and limits. It is GitHub Flavored Markdown, sent as `text/markdown; charset=utf-8; variant=GFM`. A fetch is a use of the credential, authenticated like any other request. Check at most once an hour, with If-None-Match.

operationId `readGuide`; tag Docs.

## Example request

cURL:

```bash
curl -X GET 'https://app.booksbyinstant.com/api/integrator/v1/docs/guide.md' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL"
```

JavaScript:

```javascript
// Node 18 or later, in an ES module (.mjs), which allows the top-level await.
const res = await fetch("https://app.booksbyinstant.com/api/integrator/v1/docs/guide.md", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
  },
});
const text = await res.text();
```

Python:

```python
import os
import requests

res = requests.get(
    "https://app.booksbyinstant.com/api/integrator/v1/docs/guide.md",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
)
text = res.text
```

## Authorization

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

## Query parameters

- `api` (string; default `integrator`; one of `integrator`, `customer`): Whose docs: integrator (the default), or customer for the customer API's, fetched with the same integrator credential.

## Headers

- `If-None-Match` (string): The ETag of the copy you have. While it is current, the answer is 304, without a body.

## Responses

### 200

The guide.

Headers:

- `Cache-Control` (string): private, no-cache: keep the copy, and ask again with If-None-Match before you use it.
- `ETag` (string): The SHA-256 of the file, in hex and in double quotes: the version of these docs. It changes when the file changes, and only then.
- `X-Content-Type-Options` (string): nosniff

`text/markdown`: string

The guide, in GitHub Flavored Markdown.

### 304

The copy with that ETag is current.

Headers:

- `Cache-Control` (string): private, no-cache: keep the copy, and ask again with If-None-Match before you use it.
- `ETag` (string): The SHA-256 of the file, in hex and in double quotes: the version of these docs. It changes when the file changes, and only then.
- `X-Content-Type-Options` (string): nosniff

No body.

### 400

A query parameter is unknown or invalid.

`application/json`: object; `Error`

Every answer that is not a success.

- `error` (string; required): Instant's sentence for people. A 4xx keeps the refusal's own sentence; a 5xx always says "Instant is temporarily unavailable. Please try again shortly."
- `code` (string; required): Stable, and what a caller branches on: VALIDATION_ERROR (400), UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), LIMIT_EXCEEDED (413), UNSUPPORTED_MEDIA_TYPE (415), UNREADABLE_FILE (422), RATE_LIMITED (429) and UNAVAILABLE (5xx). More codes may be added; treat one you do not know by its status.
- `retryAfter` (integer; at least `1`): Seconds to wait before retrying, also sent as the `Retry-After` header. Present only when there is a wait, as on a 429.
- `existingId` (string · uuid): On a 409 that names the object already there, such as a customer with that reference: its id.

Example, built from the schema:

```json
{
  "error": "string",
  "code": "VALIDATION_ERROR",
  "retryAfter": 1,
  "existingId": "01900000-0000-7000-8000-000000000000"
}
```

### 401

The credential is missing, malformed, unknown, revoked or rotated, or its integrator is disabled. All of these answer the same way.

Headers:

- `WWW-Authenticate` (string): Bearer realm="instant-integrator-api"

`application/json`: the `Error` object, as in 400.

### 5XX

Instant is temporarily unavailable. Retry later, with backoff.

`application/json`: the `Error` object, as in 400.

---

Page: https://booksbyinstant.com/docs/read-guide/ · Overview: https://booksbyinstant.com/docs/index.md