API Reference

Complete reference for all A2A and core API endpoints.

Agent Discovery

GET /.well-known/agent.json

Returns Relex's agent card — public, no authentication required.

GET /.well-known/agent.json

Response 200:

{
  "name": "Relex Legal AI Agent",
  "description": "AI-powered legal case analysis, document review, and compliance management",
  "url": "https://relex.you",
  "version": "1.0.0",
  "protocols": ["a2a/1.0"],
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": true
  },
  "authentication": {
    "schemes": ["bearer"]
  },
  "skills": [...]
}

Agent Registration

POST /v1/agents/registration-token

Generate a registration token. Requires Firebase auth.

POST /v1/agents/registration-token
Authorization: Bearer

Response 201:

{
  "registration_token": "...",
  "expires_in_seconds": 600
}

Errors: 401 Unauthorized, 409 Agent already connected.

POST /v1/agents/register

Register an external agent. Requires a valid registration token.

POST /v1/agents/register
Content-Type: application/json

{
  "registration_token": "...",
  "agent_card_url": "https://your-agent.com/.well-known/agent.json"
}

Response 201:

{
  "agent_id": "...",
  "name": "...",
  "status": "active",
  "shared_api_key": "rlx_sk_..."
}

Errors: 400 Invalid card URL or missing fields, 401 Invalid/expired token.

GET /v1/agents/me

Get the current user's connected agent. Requires Firebase auth.

DELETE /v1/agents/{agentId}

Disconnect an agent. Requires Firebase auth. Only the owning user can disconnect.

GET /v1/agents/{agentId}/health

Check agent health by re-fetching its agent card. Returns 200 with {"status": "healthy"} or 503 with {"status": "unhealthy", "error": "..."}.

Authentication

POST /v1/auth/token

Exchange an API key for a bearer token. No Firebase auth required.

POST /v1/auth/token
Content-Type: application/json

{
  "api_key": "rlx_sk_..."
}

Response 200:

{
  "bearer_token": "eyJ...",
  "expires_in": 3600,
  "expires_at": 1711900800
}

Agent Interaction (Streaming)

POST /v1/agent

Send a task to the Relex agent. Returns a Server-Sent Events (SSE) stream.

POST /v1/agent
Authorization: Bearer 
Content-Type: application/json

{
  "sessionId": "unique-session-id",
  "seedPhase": {
    "phaseId": "client-generated-uuid"
  },
  "containerId": "case-id-or-support-id",
  "containerType": "case",
  "requestType": "case_req",
  "prompt": "Analyze this employment contract for potential issues..."
}

Request Types

Type Description
eval_req Evaluate a new case — determines complexity tier
case_req Active case work — analysis, documents, strategy
support_req Support ticket interaction
sales_req Sales inquiry interaction
admin_req Administrative tasks

SSE Event Types

Event Description
status Processing status update (processing, orchestrating, tool, working, reasoning, responding)
content_chunk Streamed text content
direct_response Complete agent response (JSON)
phase_start Phase processing started
phase_end Phase processing completed
heartbeat Keep-alive signal (every 3 seconds)
error Error message

Core API Endpoints

Cases

Method Path Description
POST /v1/cases Create a case
GET /v1/cases?caseId={id} Get a case
GET /v1/cases List cases
PATCH /v1/cases/{caseId} Update a case
DELETE /v1/cases/{caseId} Delete a case
POST /v1/cases/{caseId}/files Upload case file
GET /v1/cases/{caseId}/files List case files

Workspace

Method Path Description
GET /v1/workspace/{containerType}/{containerId} Get bundled workspace (case/support/sales)

Timeline & Branching

Method Path Description
GET /v1/timeline/{timelineId} Get timeline
POST /v1/branch Create a branch
GET /v1/branch/{branchId} Get branch
GET /v1/phases?branchId={id} Get phases

Parties

Method Path Description
POST /v1/parties Create a party
GET /v1/parties List parties
GET /v1/parties/{partyId} Get party
PUT /v1/parties/{partyId} Update party

Partners Marketplace

Method Path Description
GET /v1/partners Search partners
POST /v1/cases/{caseId}/partners/{partnerId}/invite Invite partner to case

Error Responses

All errors follow this format:

{
  "error": "ErrorType",
  "message": "Human-readable description"
}
Status Meaning
400 Bad request — invalid input
401 Unauthorized — missing or invalid auth
403 Forbidden — insufficient permissions
404 Not found
409 Conflict — resource already exists
500 Internal server error