Authentication

​

Creating an API key

1. Open the AgentMark Dashboard
2. Switch to the app you want to scope the key to (shown in the breadcrumb)
3. Navigate to the app’s Settings → API keys page (app-level, not org-level)
4. Click Create API key
5. Select a role (SDK, Read-Only, or Full Access) or choose Custom to toggle individual permissions
6. Copy the key. It’s only shown once

​

API key environment scope

• This environment (the default) pins the key to the environment selected in the breadcrumb. Its traces always land in that one environment, and the key can’t reach any other.
• Environment kinds scopes the key to one or more kinds (Development, Preview, and Production) instead of pinning it. A kind-scoped key has no environment pin. Each request names the target environment (by environment name, or by the pull request number whose preview environment it targets), and the gateway authorizes that environment against the key’s allowed kinds before stamping it. The gateway rejects a selection that resolves to a kind the key can’t write to, so those traces stamp no environment rather than crossing kinds.

​

Endpoint permissions

​

Traces and spans

​

Sessions

​

Scores

​

Metrics, datasets, experiments, prompts

​

Annotation queues

​

Unauthenticated

​

Making requests

curl https://api.agentmark.co/v1/traces \
  -H "Authorization: Bearer sk_agentmark_your_key_here" \
  -H "X-Agentmark-App-Id: a1b2c3d4-5678-90ab-cdef-1234567890ab"

const response = await fetch("https://api.agentmark.co/v1/traces", {
  headers: {
    "Authorization": `Bearer ${process.env.AGENTMARK_API_KEY}`,
    "X-Agentmark-App-Id": process.env.AGENTMARK_APP_ID!,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.agentmark.co/v1/traces",
    headers={
        "Authorization": f"Bearer {os.environ['AGENTMARK_API_KEY']}",
        "X-Agentmark-App-Id": os.environ["AGENTMARK_APP_ID"],
    },
)
data = response.json()

​

Rate limiting

​

Span and storage limits

• Span limit: maximum number of spans per month (Hobby/Growth tiers)
• Storage cap: maximum storage used (certain plans only)

​

Error responses

{
  "error": {
    "code": "unauthorized",
    "message": "Not authorized"
  }
}

{
  "error": {
    "code": "span_limit_exceeded",
    "message": "Monthly span limit of 20000 reached. Upgrade your plan to raise this limit.",
    "currentCount": 20000,
    "limit": 20000,
    "upgradeUrl": "https://app.agentmark.co/settings/billing"
  }
}

{
  "error": {
    "code": "invalid_request_body",
    "message": "Invalid request body",
    "details": {
      "score": "Expected number, received string"
    }
  }
}