> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Every v2 endpoint on its own page — parameters, responses, and a live playground to test with your own credentials.

Each endpoint in this reference has its own page with every parameter, every
response field, and an interactive playground on the right — you can call the
real API from your browser without writing a line of code.

Base URL: `https://api.agentcard.sh`

There is no separate sandbox host: whether a call runs in **sandbox** or
**production** is decided by the credential you use, never by the URL.

## Authentication

Every endpoint is called from your backend with a **platform access token** in
the `Authorization` header:

```
Authorization: Bearer <access_token>
```

You mint that token by exchanging your `client_id` + `client_secret` on
[Create an access token](/companies/api/reference/create-access-token). Get
your credentials in the dashboard under **Organization → Developer →
Credentials** — a sandbox client mints sandbox tokens; a production client
mints production tokens.

## Two tokens, two jobs

The OAuth flow hands you two different tokens — don't mix them up:

| Token                     | Where you get it                                                                                                | What it does                                                                                                                                                 |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Platform access token** | [Create an access token](/companies/api/reference/create-access-token), from your `client_id` + `client_secret` | Authenticates **your platform**. Goes in the `Authorization` header of every endpoint in this reference.                                                     |
| **Connection token**      | [Verify the code](/companies/api/reference/connect-verify), after the user completes the one-time code          | Acts **on behalf of that user**. Send it as the bearer token to the [MCP server](/companies/mcp/overview) to create cards, check balances, and shop as them. |

The connection token belongs to the user, not your platform — it never goes in
the `Authorization` header of these endpoints (they name the user with
`user_id` instead), and it only sees what **your app** created for **that
user**. Keep it fresh with
[Refresh the connection](/companies/api/reference/connect-refresh).

## Test endpoints from this reference

<Steps>
  <Step title="Mint a token">
    Open [Create an access token](/companies/api/reference/create-access-token),
    paste your `client_id` and `client_secret` into the playground, and hit
    **Send**. Use a sandbox client so nothing touches production.
  </Step>

  <Step title="Authorize the playground">
    Copy the `access_token` from the response and paste it into the
    **Authorization** field on any endpoint page. It's remembered as you move
    between pages, and is only kept in your browser.
  </Step>

  <Step title="Call the API">
    Fill in the parameters and hit **Send** — you're hitting the live API.
    Tokens expire after one hour; mint a new one when calls start returning
    `401`.
  </Step>
</Steps>

<Note>
  In sandbox, the connect code is always `111111`, so you can run the whole
  [Connect flow](/companies/api/reference/connect-start) — start → verify →
  consent → refresh — end to end from these pages.
</Note>

## Errors

Every v2 error uses the same envelope:

```json theme={null}
{
  "error": {
    "code": "invalid_code",
    "message": "That code is invalid or expired.",
    "docs": "https://docs.agentcard.sh/companies/api/overview"
  }
}
```

* `code` — a stable, machine-readable string (snake\_case). Branch on this.
* `message` — a human-readable explanation, safe to log.
* `docs` — a link back to the reference.

Each endpoint page lists the codes it can return. Prefer Postman? The
[ready-made collection](/companies/api/postman) runs both flows end to end.