API Reference

REST API for session capture, issue creation, and data retrieval.

Authentication

All API requests require an x-api-key header with your project API key.

bash

curl -X POST https://api.usercontext.com/v1/sessions \
  -H "x-api-key: uc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"externalSessionId": "session_abc123"}'

Base URL

https://api.usercontext.com

Endpoints

POST/v1/sessions

Create or resume a capture session.

Request body

json

{
  "externalSessionId": "string"
}

Response 201 (created)

json

{
  "sessionId": "uuid"
}

Response 200 (session already exists)

json

{
  "sessionId": "uuid"
}

POST/v1/sessions/:id/logs

Batch ingest session logs. Maximum 100 entries per batch.

Request body

json

{
  "logs": [
    {
      "type": "console" | "network" | "storage",
      "level": "error" | "warn" | "info" | "debug",
      "payload": {},
      "timestamp": "ISO 8601",
      "eventType": "log" | "click" | "navigation",
      "eventMetadata": {}
    }
  ]
}

Response 202

json

{
  "accepted": 42
}

POST/v1/issues

Create an issue from a session. Triggers async AI analysis (priority, root cause, revenue impact).

Request body

json

{
  "sessionId": "uuid",
  "userDescription": "string (1-5000 chars)",
  "metadata": {
    "url": "string",
    "browser": "string"
  }
}

Response 201

json

{
  "issueId": "uuid"
}

GET/v1/issues/:id

Get issue details including AI analysis and session logs.

Response 200

json

{
  "issueId": "uuid",
  "sessionId": "uuid",
  "userDescription": "Checkout button does nothing",
  "ai_summary": "User attempted checkout but click handler failed...",
  "priority": "P1",
  "impact_score": 85,
  "logs": [
    { "type": "console", "level": "error", "payload": {...} }
  ],
  "createdAt": "2026-02-27T12:00:00Z"
}

GET/v1/projects/:id/issues

List project issues (paginated).

Query parameters

page — Page number (default: 1)
limit — Items per page (default: 20)

Response 200

json

{
  "issues": [...],
  "total": 142,
  "page": 1
}

GET/v1/issues/:id/export

Export issue as markdown for Jira/Linear ticket creation.

Response 200

json

{
  "markdown": "## Issue: Checkout button does nothing\n\n**Priority:** P1\n..."
}

Error Responses

All errors follow a consistent format:

json

{
  "statusCode": 400,
  "error": "VALIDATION_ERROR",
  "message": "Description of what went wrong"
}

Status	Meaning
400	Validation error — check request body
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	Internal server error