API docs

Reference / Docs

Read an OpenAPI reference

GEThttps://app.booksbyinstant.com/api/integrator/v1/docs/openapi.json

This API's OpenAPI 3.1 reference, or the customer API's with api=customer, exactly as Instant serves it now. A fetch is a use of the credential, authenticated like any other request. Check at most once an hour, with If-None-Match.

readOpenApi · This page as markdown

Example request

cURL

curl -X GET 'https://app.booksbyinstant.com/api/integrator/v1/docs/openapi.json' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL"

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/openapi.json", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
  },
});
const data = await res.json();

Python

import os
import requests

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

Authorization

Bearer token live_<100 hex>

Authorization: Bearer <secret>. A 401 answers WWW-Authenticate: Bearer realm="instant-integrator-api".

Query parameters

  • api string

    Whose docs: integrator (the default), or customer for the customer API's, fetched with the same integrator credential.

    default integrator

    One of integrator customer

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

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

Body application/json

object

An OpenAPI 3.1 document.

  • openapi string required

    always 3.1.0

  • info object required

    • title string required

    • version string required

    • description string required

  • Any other field any

    The rest of the OpenAPI document: paths, webhooks and components.

Example, built from the schema

{
  "openapi": "3.1.0",
  "info": {
    "title": "string",
    "version": "string",
    "description": "string"
  }
}

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.

Body 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

    Seconds to wait before retrying, also sent as the Retry-After header. Present only when there is a wait, as on a 429.

    at least 1

  • 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

{
  "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"

Body application/json

The Error object, as in 400.

5XX

Instant is temporarily unavailable. Retry later, with backoff.

Body application/json

The Error object, as in 400.