# AlmondTill/G3N API

One API for everything in your business — the same operations your Office, your registers and your storefront use, open to your own code and to the tools you connect. This is its reference: what every operation means and does, in plain words, with a request and a response you can copy.

## What you need

- An account and an organization on the platform.
- An API key, minted by an owner of your organization group. Its scope is fixed when it is minted and it expires within 12 months; the secret is shown once.
- The secret exchanges for a session token that lasts 24 hours; every call after the exchange carries the token.

## Your first call

Five minutes, three steps. Every call is a POST to `https://api.almondtill.com/` with a JSON body of `query`, `variables` and `extensions`. A change names the API version it was written against under `extensions.at.version`; a read may leave it out.

### Step 1 — mint a key

An owner of your organization group mints an API key in the office, under API keys, choosing exactly what the key may do — or does the same from their own code with [mintApiKey](/reference/system-and-integration-setup/mintApiKey/). The secret is shown once: copy it into your integration's secret store then and there.

### Step 2 — exchange the secret for a session

No token yet — the secret is the credential. Call [exchangeApiKey](/reference/open-doors/exchangeApiKey/) naming the organization the session will act in:

```json
{
  "query": "mutation ExampleExchangeApiKey($input: ExchangeApiKeyInput!) {\n  exchangeApiKey(input: $input) {\n    token\n    expiresAt\n  }\n}",
  "variables": {
    "input": {
      "secret": "<your key secret>",
      "orgId": "01900000-0000-7000-8000-b0cf4f3c0000"
    }
  },
  "extensions": {
    "at": {
      "version": {
        "name": "genesis",
        "number": 0
      }
    }
  }
}
```

The answer carries the session token and the moment it expires (24 hours on; use does not extend it):

```json
{
  "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
        }
      }
    }
  }
}
```

### Step 3 — read your first page

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

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

The answer is a page:

```json
{
  "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
        }
      }
    }
  }
}
```

Every answer carries `extensions.at` — the call id to quote when something needs a look, the version that served you, and the stat of the call. Every id in the examples is made up and resolves nowhere.

## The map

- [Reference](/reference/) — 1018 operations in 149 families, one page each.
- [Types](/types/) — the 1111 types they take and answer.
- [Errors](/errors/) — the 12 classes, every code, and the retry rule.
- [Guides](/guides/) — 10 short walks: authentication, your first call, paging, versions, errors, rate limits, dry runs, webhooks, the agent channel.
- [Use cases](/use-cases/) — 78 things people do with the platform, each walked step by step with the operations behind it.
- For machines: [index.json](/index.json), [llms.txt](/llms.txt) and the full [schema.graphql](/schema.graphql); every page has a Markdown twin at the same address plus `index.md`.