API Reference

The Nexus REST API lets you ingest traces and spans from any language or framework. No SDK required — every endpoint accepts plain JSON over HTTPS.

Authentication

Required on all /api/v1/* endpoints

Pass your API key as a Bearer token in the Authorization header on every request.

Authorization: Bearer nxs_a1b2c3d4e5f6...

Getting an API key

1. Create a free account — no credit card required
2. Go to Dashboard → API Keys
3. Click Create new key and give it a name
4. Copy the key — it is shown exactly once
5. Store it in your environment: NEXUS_API_KEY=nxs_...

Rate Limits & Plan Limits

Limits reset on the 1st of each calendar month (UTC)

Rate limit responses

{
  "error": "Monthly trace limit reached. Upgrade to Pro.",
  "limit": 1000,
  "current": 1001,
  "upgrade_url": "/dashboard/billing"
}

{
  "error": "Free plan limited to 1 agent",
  "upgrade_url": "/dashboard/billing"
}

Error Codes

All error responses include a JSON body with an error field

Create a new trace. Agents are auto-created on first use — no separate registration step required.

Requires authentication · Returns 201 Created

{
  "agent_id": "my-assistant",
  "name": "user-query-2026-04-06",
  "status": "running",
  "started_at": "2026-04-06T12:00:00Z",
  "ended_at": null,
  "metadata": { "user_id": "u_123" }
}

{
  "trace_id": "f47ac10b-58cc-4372-..."
}

Request fields

curl example

curl -s -X POST https://nexus.keylightdigital.dev/api/v1/traces \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-assistant",
    "name": "user-query",
    "status": "running",
    "started_at": "2026-04-06T12:00:00Z"
  }'

# Response
# {"trace_id":"f47ac10b-58cc-4372-..."}

Error responses

Add a span to an existing trace. Spans represent individual sub-steps — LLM calls, tool uses, sub-agent invocations, or any discrete unit of work.

Requires authentication · Returns 201 Created

{
  "name": "llm-call",
  "status": "ok",
  "started_at": "2026-04-06T12:00:01Z",
  "ended_at": "2026-04-06T12:00:02Z",
  "input": { "prompt": "Summarize this..." },
  "output": { "text": "Here is a summary..." },
  "error": null,
  "parent_span_id": null
}

{
  "span_id": "a1b2c3d4-e5f6-..."
}

Request fields

curl example

curl -s -X POST https://nexus.keylightdigital.dev/api/v1/traces/TRACE_ID/spans \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "llm-call",
    "status": "ok",
    "started_at": "2026-04-06T12:00:01Z",
    "ended_at": "2026-04-06T12:00:02Z",
    "input": { "prompt": "Summarize this document" },
    "output": { "text": "Here is the summary..." }
  }'

# Response
# {"span_id":"a1b2c3d4-e5f6-..."}

Error responses

Finalize a trace — update its status and set the end time. All fields are optional; only provided fields are updated.

Requires authentication · Returns 200 OK · Triggers Pro email alert on error/timeout

{
  "status": "success",
  "ended_at": "2026-04-06T12:00:05Z"
}

{
  "ok": true
}

Request fields

curl example

curl -s -X PATCH https://nexus.keylightdigital.dev/api/v1/traces/TRACE_ID \
  -H "Authorization: Bearer $NEXUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "success", "ended_at": "2026-04-06T12:00:05Z"}'

# Response
# {"ok":true}

Error responses

Retrieve a trace by ID, including all its spans. Useful for verifying ingestion or building custom UIs.

Requires authentication · Returns 200 OK

{
  "id": "f47ac10b-58cc-4372-...",
  "agent_id": "my-assistant",
  "name": "user-query-2026-04-06",
  "status": "success",
  "started_at": "2026-04-06T12:00:00Z",
  "ended_at": "2026-04-06T12:00:05Z",
  "metadata": { "user_id": "u_123" },
  "spans": [
    {
      "id": "a1b2c3d4-...",
      "name": "llm-call",
      "status": "ok",
      "started_at": "2026-04-06T12:00:01Z",
      "ended_at": "2026-04-06T12:00:02Z",
      "input": { "prompt": "..." },
      "output": { "text": "..." },
      "error": null,
      "parent_span_id": null
    }
  ]
}

curl example

curl -s https://nexus.keylightdigital.dev/api/v1/traces/TRACE_ID \
  -H "Authorization: Bearer $NEXUS_API_KEY"

# Returns the full trace object with spans array

Error responses

Health check endpoint. No authentication required. Returns 200 OK when the service is up.

Public · No authentication required · Returns 200 OK

{
  "status": "ok"
}

curl example

curl -s https://nexus.keylightdigital.dev/health

# Response
# {"status":"ok"}

API Playground

Try the API directly from your browser. Enter your API key, pick an endpoint, and hit Send. Your key is stored in sessionStorage — cleared automatically when you close the tab.