# API Reference - A2A Docs - Relex

> Complete API reference for Relex A2A endpoints. Agent discovery, registration, authentication, case management, timeline branching, and streaming.

[Home](/) / [Docs](/docs/a2a) / A2A Protocol

### A2A Protocol

- [Overview](/docs/a2a/)
- [Authentication](/docs/a2a/authentication/)
- [API Reference](/docs/a2a/api-reference/)
- [Integration Guide](/docs/a2a/integration-guide/)
- [Examples](/docs/a2a/examples/)

### MCP Server

- [Overview](/docs/mcp)
- [Quickstart](/docs/mcp/quickstart)

#### On this page

- [Agent Discovery](#clause-2)
- [GET /.well-known/agent.json](#clause-3)
- [Agent Registration](#clause-4)
- [POST /v1/agents/registration-token](#clause-5)
- [POST /v1/agents/register](#clause-6)
- [GET /v1/agents/me](#clause-7)
- [DELETE /v1/agents/{agentId}](#clause-8)
- [GET /v1/agents/{agentId}/health](#clause-9)
- [Authentication](#clause-10)
- [POST /v1/auth/token](#clause-11)
- [Agent Interaction (Streaming)](#clause-12)
- [POST /v1/agent](#clause-13)
- [Core API Endpoints](#clause-16)
- [Cases](#clause-17)
- [Workspace](#clause-18)
- [Timeline & Branching](#clause-19)
- [Parties](#clause-20)
- [Partner Network](#clause-21)
- [Error Responses](#clause-22)

# 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. This is an
abridged illustration; the authoritative card is served live at
[/.well-known/agent.json](https://relex.you/.well-known/agent.json).

```
GET /.well-known/agent.json
```

Response `200`:

```json
{
  "protocolVersion": "0.3.0",
  "name": "Relex",
  "description": "Confidential legal automation: the agent reads a de-identified case, reasons, and drafts while client identities stay encrypted in the browser and it only ever sees labels like [Party 1]. A human professional stays accountable for judgment.",
  "url": "https://relex.you/api/a2a",
  "preferredTransport": "JSONRPC",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "securitySchemes": {
    "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "...": "..." } } }
  },
  "skills": [...],
  "additionalInterfaces": [{ "transport": "mcp", "url": "https://relex.you/api/mcp" }]
}
```

> Recommended integration is MCP (OAuth, two tools) at `/api/mcp` — see the
> [MCP docs](https://relex.you/docs/mcp). The agent works only on de-identified
> data; anything that would move a real client identity is refused and the user
> is deep-linked to do it securely in their browser.

## Agent Registration

### POST /v1/agents/registration-token

Generate a registration token. Requires Firebase auth.

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

Response `201`:

```json
{
	"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`:

```json
{
	"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`:

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

### Partner Network

| 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:

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

---

_[View this page on relex.you](https://relex.you/docs/a2a/api-reference)_