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

# Gradient API overview and authentication

> Authenticate to the Gradient API with a key or a session cookie, page through list endpoints, and read the error shape every route returns.

# API Overview

Base URL: `https://app.trygradient.ai`

All API endpoints are served from the same domain as the admin portal. Requests must include valid authentication.

## Authentication

Gradient supports two authentication methods:

<Tabs>
  <Tab title="API Key (recommended)">
    Include your API key in the `Authorization` header:

    ```bash theme={null}
    Authorization: Bearer gai_abc123...
    ```

    API keys are scoped to your organization. Create and manage them via the [API Keys endpoints](/docs/api-reference/api-keys) or the Settings page in the admin portal.

    A key is shown one time and stored only as a hash. See [Managing API keys](/docs/guides/managing-api-keys#security) for how keys are stored, scoped, limited, and revoked.
  </Tab>

  <Tab title="Session Cookie">
    Admin users authenticated via the web portal automatically have a session cookie (`stytch_session`) that works with all API endpoints. This is the default when using the API from the browser.
  </Tab>
</Tabs>

## Pagination

List endpoints accept optional pagination parameters:

<ParamField query="limit" type="integer" default="20">
  Results per page (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of results to skip
</ParamField>

Paginated responses include metadata:

```json theme={null}
{
  "data": [...],
  "total": 42,
  "limit": 20,
  "offset": 0
}
```

## Error Responses

All errors follow a consistent format:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Assessment not found"
  }
}
```

`code` is stable. Branch on it. `message` is written for people, carries live
values, and can change at any time, so do not match on its text.

| HTTP Status | Error Code | Meaning |
| - | - | - |
| `400` | `validation` | Invalid request body or missing required fields |
| `401` | `unauthorized` | Missing or invalid authentication |
| `403` | `forbidden` | Authenticated but lacking permission |
| `404` | `not_found` | Resource doesn't exist or doesn't belong to your org |
| `409` | `conflict` | Action conflicts with current resource state |
| `410` | `gone` | Resource existed but has expired |
| `429` | `rate_limited` | Too many requests on this API key. See [Rate limits](/docs/guides/managing-api-keys#rate-limits) |
| `500` | `internal` | Unexpected server error |
| `502` | `upstream_error` | A service we depend on failed. Safe to retry |
| `503` | `unavailable` | Temporarily offline for maintenance. Honour `Retry-After` |

A few responses add fields beside `error`, never inside it. For example a
missing deliverable returns `expected: true` so a viewer can show an empty
state instead of an error.

Some endpoints return a more specific `code` than the table gives, when one
status covers several different failures. The calibration endpoints are the
main case: `wrong_channel`, `no_anchors`, `no_grades`, `no_disagreement` and
`llm_error` are all `400`. Treat an unknown code as its status class.

<Note>
  The ATS partner endpoints under `/api/ats/` do not use this format. Greenhouse
  and Ashby set the request and response shapes for those endpoints, so they
  follow each vendor's partner specification. See
  [ATS Integrations](/docs/api-reference/integrations).
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.