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

> Create, list, and revoke API keys for authenticating with the AgentVista API.

API keys authenticate requests to AgentVista ingestion and management endpoints. Every key starts with `av_` and carries one or more scopes that control what it can access.

<Warning>
  When you create a key, AgentVista returns the full key value exactly once. Copy it immediately — it is never shown again. Only a short prefix (e.g. `av_a1b2c3d4`) is stored and returned in subsequent list responses.
</Warning>

## Scopes

| Scope   | Description                                                          |
| ------- | -------------------------------------------------------------------- |
| `write` | Required for all ingestion endpoints (`/traces/batch`, `/otlp/v1/*`) |
| `read`  | Required to verify a key with the ping endpoint                      |

***

## List API keys

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/me/api-keys/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /me/api-keys/`

Returns a paginated list of API keys for the authenticated user. The raw key value is never included in list responses.

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number (1-indexed).
</ParamField>

<ParamField query="page_size" type="number" default="20">
  Number of keys per page.
</ParamField>

### Response

<ResponseField name="results" type="object[]">
  Array of API key objects.

  <Expandable title="key object fields">
    <ResponseField name="id" type="string">
      UUID of the key.
    </ResponseField>

    <ResponseField name="name" type="string">
      Human-readable label for this key.
    </ResponseField>

    <ResponseField name="scopes" type="string[]">
      List of scopes granted to this key, e.g. `["write"]`.
    </ResponseField>

    <ResponseField name="prefix" type="string">
      The first characters of the key used for identification in list views (e.g. `av_a1b2c3d4`). Not the full key.
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Whether the key can authenticate requests. Revoked keys have `is_active: false`.
    </ResponseField>

    <ResponseField name="org_slug" type="string | null">
      Organization slug the key is scoped to, or `null` for personal keys.
    </ResponseField>

    <ResponseField name="last_used_at" type="string | null">
      ISO 8601 timestamp of the last successful authenticated request, or `null` if never used.
    </ResponseField>

    <ResponseField name="usage_count" type="number">
      Total number of authenticated requests made with this key.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the key was created.
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Create an API key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.agentvista.dev/api/v1/me/api-keys/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "production-ingest",
      "scopes": ["write"]
    }'
  ```
</CodeGroup>

`POST /me/api-keys/`

Creates a new API key and returns the full raw key value. Store it immediately.

### Request body

<ParamField body="name" type="string">
  A human-readable label to identify this key (e.g. `production-ingest`). Optional but recommended.
</ParamField>

<ParamField body="scopes" type="string[]" required>
  List of scopes to grant. Must contain at least one valid scope. Use `["write"]` for ingestion.
</ParamField>

<ParamField body="org_slug" type="string">
  Organization slug to scope this key to. If omitted, the key is a personal key tied to your user account.
</ParamField>

### Response — 201

<ResponseField name="id" type="string">
  UUID of the new key.
</ResponseField>

<ResponseField name="name" type="string">
  Label you provided.
</ResponseField>

<ResponseField name="scopes" type="string[]">
  Scopes granted to this key.
</ResponseField>

<ResponseField name="prefix" type="string">
  Short prefix for identification in list views.
</ResponseField>

<ResponseField name="is_active" type="boolean">
  Always `true` on creation.
</ResponseField>

<ResponseField name="org_slug" type="string | null">
  Organization slug or `null`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

<ResponseField name="key" type="string">
  The full raw API key. **Copy this now — it is never returned again.**
</ResponseField>

```json Example response theme={null}
{
  "id": "3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a",
  "name": "production-ingest",
  "scopes": ["write"],
  "prefix": "av_a1b2c3",
  "is_active": true,
  "org_slug": null,
  "created_at": "2024-01-15T10:00:00Z",
  "key": "av_a1b2c3d4e5f6..."
}
```

***

## Verify a key

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.agentvista.dev/api/v1/me/api-keys/ping/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`GET /me/api-keys/ping/`

Verifies that an API key is valid and has `read` scope. Useful for checking a key works before deploying.

### Response — 200

<ResponseField name="status" type="string">
  Always `"ok"` when the key is valid and has `read` scope.
</ResponseField>

```json theme={null}
{ "status": "ok" }
```

***

## Revoke an API key

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.agentvista.dev/api/v1/me/api-keys/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/ \
    -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</CodeGroup>

`DELETE /me/api-keys/{key_id}/`

Immediately revokes the key. Any subsequent requests using the revoked key receive `401`.

### Path parameters

<ParamField path="key_id" type="string" required>
  UUID of the key to revoke.
</ParamField>

### Response — 204

No body. The key has been revoked.