Your first call

Five minutes from a key to your first page of records. Every request and answer below is a real example, copied as the reference pages show it. Every id in the examples is made up and resolves nowhere.

The shape of a call

Every call is a POST to https://api.almondtill.com/ with a JSON body of three parts: query — the operation, written in GraphQL; variables — its arguments; and extensions — the envelope. There is one address for all 1018 operations, and one answer shape: data holds the result under the operation's name, errors appears only when something was refused, and extensions.at is the envelope that comes back on every answer (Versions and the envelope).

Step 1 — mint a key

An owner of your organization group mints an API key in the office, under API keys, choosing what the key may do. The secret is shown once; copy it into your integration's secret store then and there. The whole life of a key is in Authentication and key hygiene.

Step 2 — exchange the secret for a session

The key's secret never rides on your calls. Exchange it once for a session token with exchangeApiKey — no token yet, the secret is the credential — naming the organization the session will act in:

Example request

mutation ExampleExchangeApiKey($input: ExchangeApiKeyInput!) {
  exchangeApiKey(input: $input) {
    token
    expiresAt
  }
}

Variables:

{
  "input": {
    "secret": "<your key secret>",
    "orgId": "01900000-0000-7000-8000-b0cf4f3c0000"
  }
}

Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.

Example response

{
  "data": {
    "exchangeApiKey": {
      "token": "<your session token>",
      "expiresAt": "2027-01-31T00:00:00.000Z"
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": {
          "name": "genesis",
          "number": 0
        },
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

The token lasts 24 hours. Send it on every call after this one as an authorization: Bearer <your session token> header.

Step 3 — read your first page

Ask for a small page of one listing — your brands, say — with the token in the header:

Send it with the token as authorization: Bearer <your session token>:

{
  "query": "query FirstBrands($limit: Int) { brands(limit: $limit) { items { sysId caption status } nextToken } }",
  "variables": {
    "limit": 3
  }
}

The answer is a page:

{
  "data": {
    "brands": {
      "items": [
        {
          "sysId": "BR-EXMP-0000-000F",
          "caption": "Blue jeans",
          "status": "active"
        }
      ],
      "nextToken": null
    }
  },
  "extensions": {
    "at": {
      "callId": "01EXAMPLE-CALL-ID",
      "version": {
        "requested": null,
        "serviced": {
          "name": "genesis",
          "number": 0
        }
      }
    }
  }
}

items holds the records; nextToken is null because this small page is complete — a longer listing answers a cursor there, and Paging and the cursor grammar walks it.

What you have now

A working session and a page of your own records. From here: every operation has a page in the reference with a request and a response to copy; a change names its version in the envelope (Versions and the envelope); a refusal is a structured error with a retry verdict (Errors and retries); and the use cases walk whole jobs step by step, each step with its operations.