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 section of the dashboard or via the API.

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.

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:

{
  "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

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": []
      }
    ]
  }'