API Endpoints

All endpoints are relative to the base URL:

https://<your-instance>/api/v1/

Requests must include an Authorization: Bearer <access_token> header. See Authentication for details on obtaining a token.

Authentication

Method	Path	Description
POST	/auth/token	Exchange client credentials for a JWT access token

POST /auth/token

Exchange client credentials for an access token.

Request body (JSON):

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

Response 200 OK:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "token_type": "bearer"
}

---

Projects

Method	Path	Description
GET	/projects	List all accessible projects
POST	/projects	Create a new project
GET	/projects/:id	Get project details

GET /projects

Returns a list of projects the authenticated credential has access to.

Query parameters: None.

Response 200 OK:

[
  {
    "id": "uuid",
    "name": "Project Alpha",
    "description": "Merger & acquisition deal room",
    "created_at": "2026-01-15T10:30:00Z",
    "document_count": 12
  }
]

POST /projects

Create a new project.

Request body (JSON):

{
  "name": "Project Beta",
  "description": "Optional description"
}

Response 201 Created:

{
  "id": "uuid",
  "name": "Project Beta",
  "description": "Optional description",
  "created_at": "2026-03-23T14:00:00Z",
  "document_count": 0
}

GET /projects/{id}

Get details for a single project.

Path parameters:

Parameter	Type	Description
id	UUID	Project ID

Response 200 OK:

{
  "id": "uuid",
  "name": "Project Alpha",
  "description": "Merger & acquisition deal room",
  "created_at": "2026-01-15T10:30:00Z",
  "document_count": 12
}

---

Documents

Method	Path	Description
POST	/documents	Upload a document for analysis
GET	/documents?project_id=X	List documents in a project
GET	/documents/:id	Get document details and pipeline status
GET	/documents/:id/report	Get the full analysis report
GET	/documents/:id/obligations	Get extracted obligations
DELETE	/documents/:id	Delete a document

POST /documents

Upload a document for AI-powered analysis. The document enters the processing pipeline immediately.

Content-Type: multipart/form-data

Field	Type	Required	Description
file	File	Yes	The document file (PDF, DOCX, DOC, TXT, PNG, JPG)
project_id	UUID	Yes	Target project ID

curl example:

curl -X POST https://<your-instance>/api/v1/documents \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@/path/to/contract.pdf" \
  -F "project_id=<project-uuid>"

Response 202 Accepted:

{
  "id": "uuid",
  "filename": "contract.pdf",
  "project_id": "uuid",
  "pipeline_status": "queued",
  "created_at": "2026-03-23T14:05:00Z"
}

tip

The 202 Accepted response means the document has been queued for processing. Poll GET /documents/:id to track pipeline progress.

GET /documents

List documents, optionally filtered by project.

Query parameters:

Parameter	Type	Required	Description
project_id	UUID	No	Filter by project

curl example:

curl https://<your-instance>/api/v1/documents?project_id=<project-uuid> \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:

[
  {
    "id": "uuid",
    "filename": "contract.pdf",
    "project_id": "uuid",
    "pipeline_status": "complete",
    "classification": "MSA",
    "created_at": "2026-03-23T14:05:00Z"
  }
]

GET /documents/{id}

Get full document details including current pipeline status.

Path parameters:

Parameter	Type	Description
id	UUID	Document ID

Response 200 OK:

{
  "id": "uuid",
  "filename": "contract.pdf",
  "project_id": "uuid",
  "pipeline_status": "complete",
  "classification": "MSA",
  "parties": ["Acme Corp", "Widget Inc"],
  "effective_date": "2026-01-01",
  "governing_law": "New York",
  "created_at": "2026-03-23T14:05:00Z",
  "completed_at": "2026-03-23T14:07:30Z"
}

Pipeline status values (in processing order):

Status	Description
queued	Waiting to be picked up by a worker
extracting	Text extraction in progress
classifying	AI classification in progress
playbook	Playbook matching and field extraction
analyzing	Clause-by-clause analysis
embedding	Vector embedding generation
storing	Report generation
complete	Processing finished successfully
failed	Processing failed (check error_message)

GET /documents/{id}/report

Retrieve the full AI-generated analysis report.

curl example:

curl https://<your-instance>/api/v1/documents/<document-uuid>/report \
  -H "Authorization: Bearer <access_token>"

Response 200 OK:

{
  "id": "uuid",
  "document_id": "uuid",
  "report_type": "contract_review",
  "overall_risk": "medium",
  "executive_summary": "This Master Services Agreement contains...",
  "clauses": [
    {
      "type": "Limitation of Liability",
      "risk_level": "high",
      "text": "...",
      "analysis": "...",
      "recommendation": "..."
    }
  ],
  "created_at": "2026-03-23T14:07:30Z"
}

note

If the document is still processing, this endpoint returns 404 Not Found until the report has been generated.

GET /documents/{id}/obligations

Retrieve extracted obligations (deadlines, renewal dates, notice periods, etc.).

Response 200 OK:

[
  {
    "id": "uuid",
    "document_id": "uuid",
    "title": "Annual compliance audit",
    "description": "Vendor must complete SOC 2 audit annually",
    "due_date": "2027-01-15",
    "recurrence": "annual",
    "responsible_party": "Vendor",
    "status": "active"
  }
]

DELETE /documents/{id}

Permanently delete a document and all associated data (text, embeddings, reports, obligations).

Response 204 No Content — no response body.

warning

This action is irreversible. All analysis data for the document is permanently removed.

---

HTTP Status Codes

All endpoints use standard HTTP status codes. See Error Codes & Rate Limits for details.

Code	Meaning
200	Success
201	Resource created
202	Request accepted (async processing)
204	Success, no content
400	Bad request
401	Invalid or expired token
403	Insufficient permissions
404	Resource not found
422	Validation error
429	Too many requests
500	Internal server error