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

# API overview

> Authentication, base URL, request format, and error codes for the AgentVista API.

The AgentVista API lets you ingest telemetry from your AI agents and infrastructure, and query that data from your own tooling or dashboards.

**Base URL**

```
https://api.agentvista.dev/api/v1
```

All responses are JSON.

## Authentication

Pass your API key as a Bearer token in every request:

```
Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

API keys start with `av_`. You can create and revoke keys from the [API Keys](/api/api-keys) section of the dashboard or via the API.

<Note>
  Dashboard read endpoints (`/dashboard/*`) also accept session cookies and JWTs issued by the browser login flow. For programmatic access from outside a browser, use an API key.
</Note>

## Endpoint categories

### Ingestion endpoints

These endpoints accept telemetry data. They require an API key with the `write` scope.

| Method | Path               | Description                           |
| ------ | ------------------ | ------------------------------------- |
| `POST` | `/traces/batch`    | Ingest a batch of traces from the SDK |
| `POST` | `/otlp/v1/traces`  | Ingest OTLP/HTTP JSON traces          |
| `POST` | `/otlp/v1/metrics` | Ingest OTLP/HTTP JSON metrics         |
| `POST` | `/otlp/v1/logs`    | Ingest OTLP/HTTP JSON logs            |

### Dashboard endpoints

These endpoints serve the AgentVista dashboard and accept session auth, JWTs, or API keys.

| Prefix                     | Description                                   |
| -------------------------- | --------------------------------------------- |
| `/agents`                  | List and inspect agents                       |
| `/dashboard/traces`        | Query trace data and compare agents           |
| `/dashboard/metrics`       | List metric streams and query data points     |
| `/dashboard/logs`          | Search log records                            |
| `/dashboard/prompts`       | Manage prompt versions and analytics          |
| `/alerts`                  | Manage alert configurations                   |
| `/me/api-keys`             | Create and revoke API keys                    |
| `/org/{org_slug}/webhooks` | Manage webhook endpoints and delivery history |

## Rate limiting and event limits

AgentVista enforces a monthly event (span) limit per account. When your limit is exceeded, ingestion endpoints return HTTP `429`. Dashboard read endpoints are not affected by the event limit.

The response body for a `429` is:

```json theme={null}
{
  "detail": "Monthly event limit exceeded."
}
```

## Error codes

| Code  | Meaning                                                                |
| ----- | ---------------------------------------------------------------------- |
| `400` | Bad request — malformed JSON, missing required field, or invalid value |
| `401` | Unauthorized — missing or invalid API key                              |
| `403` | Forbidden — API key does not have the required scope                   |
| `404` | Not found — resource does not exist or belongs to another user         |
| `429` | Event limit exceeded — monthly span quota has been reached             |

## Example request

```bash theme={null}
curl -X POST https://api.agentvista.dev/api/v1/traces/batch \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "traces": [
      {
        "trace": {
          "trace_id": "550e8400-e29b-41d4-a716-446655440000",
          "agent": "lead-qualifier",
          "status": "completed",
          "started_at": "2024-01-15T10:00:00Z",
          "ended_at": "2024-01-15T10:00:02Z",
          "duration_ms": 2000,
          "success": true,
          "outcome": "qualified"
        },
        "spans": []
      }
    ]
  }'
```