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

# API Overview

> Authentication, pagination, and error handling for the Gradient API

# 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](/api-reference/api-keys) or the Settings page in the admin portal.
  </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"
  }
}
```

| 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         |
| `500`       | `internal`     | Unexpected server error                              |