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

# API Reference

> Programmatically manage Maitai resources using the REST API.

The Maitai Platform API gives you programmatic access to the main product resources available in the [Portal](https://portal.trymaitai.com), applications, intents, agents, workflows, datasets, test sets, finetune runs, sentinels, analytics, and more.

For details on covered and intentionally excluded surfaces, see [API Coverage](/api-reference/coverage).

## Base URL

All endpoints are served from:

```
https://api.trymaitai.ai/api/v1
```

## Authentication

Every request must include your Maitai API key in the `X-Maitai-Api-Key` header.

```bash theme={null}
curl https://api.trymaitai.ai/api/v1/applications \
  -H "X-Maitai-Api-Key: YOUR_MAITAI_API_KEY"
```

You can create API keys in the Portal under **Settings > API Keys**.

## Response format

Most `/api/v1` responses follow a consistent envelope:

<CodeGroup>
  ```json Success theme={null}
  {
    "data": { ... }
  }
  ```

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

  ```json Error theme={null}
  {
    "error": {
      "status": 401,
      "message": "Missing company_id"
    }
  }
  ```
</CodeGroup>

Some specialized endpoints share backend handlers with the Portal and may return a resource-specific response shape. Check the endpoint reference for the exact schema.

## Pagination

Paginated endpoints accept `offset` and `limit` query parameters:

| Parameter | Default | Max  | Description             |
| --------- | ------- | ---- | ----------------------- |
| `offset`  | 0       | none | Number of items to skip |
| `limit`   | 25      | 100  | Max items to return     |

## Resources

Use the sidebar to navigate to specific endpoints. Each resource section lists all available operations.

<CardGroup cols={3}>
  <Card title="Applications" icon="grid-2">
    Manage applications and their configuration.
  </Card>

  <Card title="Intents" icon="bullseye">
    Application actions nested under applications.
  </Card>

  <Card title="Intent Groups" icon="layer-group">
    Cross-application intent grouping.
  </Card>

  <Card title="Agents" icon="robot">
    Agents, actions, sub-agents, versions, releases, and routing.
  </Card>

  <Card title="Workflows" icon="diagram-project">
    Workflow definitions, versions, releases, artifacts, runs, and workflow test runs.
  </Card>

  <Card title="Sentinels" icon="shield-check">
    Evaluation watchers for monitoring model output quality.
  </Card>

  <Card title="Sessions" icon="comments">
    Classic (non-agent) chat sessions.
  </Card>

  <Card title="Requests" icon="arrow-right-arrow-left">
    Individual request/response pairs.
  </Card>

  <Card title="Datasets" icon="database">
    Curated request sets for model training.
  </Card>

  <Card title="Test Sets" icon="vial">
    Curated request sets for model evaluation.
  </Card>

  <Card title="Test Runs" icon="play">
    Test set execution and results.
  </Card>

  <Card title="Finetune Runs" icon="microchip">
    Model finetuning jobs.
  </Card>

  <Card title="Evaluations" icon="chart-bar">
    Evaluation runs and results.
  </Card>

  <Card title="Models" icon="cube">
    Available and finetuned models.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Request volume, fault-rate analytics, reports, drift, and continuous learning.
  </Card>
</CardGroup>