Skip to main content
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.
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.

​
Scopes

ScopeDescription
writeRequired for all ingestion endpoints (/traces/batch, /otlp/v1/*)
readRequired to verify a key with the ping endpoint

​
List API keys

curl https://api.agentvista.dev/api/v1/me/api-keys/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
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

​
page
number
default:"1"
Page number (1-indexed).
​
page_size
number
default:"20"
Number of keys per page.

​
Response

​
results
object[]
Array of API key objects.

​
Create an API key

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"]
  }'
POST /me/api-keys/ Creates a new API key and returns the full raw key value. Store it immediately.

​
Request body

​
name
string
A human-readable label to identify this key (e.g. production-ingest). Optional but recommended.
​
scopes
string[]
required
List of scopes to grant. Must contain at least one valid scope. Use ["write"] for ingestion.
​
org_slug
string
Organization slug to scope this key to. If omitted, the key is a personal key tied to your user account.

​
Response — 201

​
id
string
UUID of the new key.
​
name
string
Label you provided.
​
scopes
string[]
Scopes granted to this key.
​
prefix
string
Short prefix for identification in list views.
​
is_active
boolean
Always true on creation.
​
org_slug
string | null
Organization slug or null.
​
created_at
string
ISO 8601 creation timestamp.
​
key
string
The full raw API key. Copy this now — it is never returned again.
Example response
{
  "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

curl https://api.agentvista.dev/api/v1/me/api-keys/ping/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
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

​
status
string
Always "ok" when the key is valid and has read scope.
{ "status": "ok" }

​
Revoke an API key

curl -X DELETE https://api.agentvista.dev/api/v1/me/api-keys/3a7f8c2d-1e4b-4a9d-b8e2-5f6c7d8e9f0a/ \
  -H "Authorization: Bearer av_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
DELETE /me/api-keys/{key_id}/ Immediately revokes the key. Any subsequent requests using the revoked key receive 401.

​
Path parameters

​
key_id
string
required
UUID of the key to revoke.

​
Response — 204

No body. The key has been revoked.