Developer Hub

API Reference

Detailed endpoint-level documentation for integrations that ingest data, run analysis, and retrieve citation-backed reports.

Near-term staged-access spec: API onboarding is coordinated through Equitista.

Back to Documentation

API Sections

Overview
Conventions
Endpoints
Error Catalog
Reliability
Changelog Policy

Overview

The API is designed around asynchronous workflows. Most write operations return quickly and emit webhook events as processing advances through ingestion, run execution, and report generation.

Conventions

Base URL

https://api.equitista.com/v1

Authentication

Authorization: Bearer <api_key>

Idempotency

Idempotency-Key header on write requests

Pagination

cursor + limit (max 100)

Filtering

status, created_at, entity_id query params

Versioning

URI versioning and additive change policy

Endpoints

Each endpoint below includes intent, payload contracts, status behavior, and implementation-ready cURL and TypeScript examples.

Workspaces

POST/workspaces

Create a new workspace boundary for users and runs.

Request Body

{
  "name": "Growth Equity Team",
  "region": "us",
  "default_retention_days": 365
}

Response Body

{
  "id": "ws_8f92b1",
  "name": "Growth Equity Team",
  "region": "us",
  "created_at": "2026-03-17T10:20:11Z"
}

Status Codes

201 Created400 Bad Request401 Unauthorized409 Conflict

curl -X POST "https://api.equitista.com/v1/workspaces" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Growth Equity Team","region":"us","default_retention_days":365}'

Ingestion

POST/data-rooms/{data_room_id}/files

Upload a source file and trigger ingestion.

Request Body

{
  "filename": "q4-earnings-call.pdf",
  "mime_type": "application/pdf",
  "source_url": "https://example.com/q4-earnings-call.pdf",
  "metadata": { "period": "Q4-2025", "entity_id": "ent_aa12f" }
}

Response Body

{
  "id": "file_1942ac",
  "status": "processing",
  "indexed_chunks": 0,
  "created_at": "2026-03-17T10:25:04Z"
}

Status Codes

202 Accepted401 Unauthorized413 Payload Too Large422 Unprocessable Entity

curl -X POST "https://api.equitista.com/v1/data-rooms/dr_12/files" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ingest-q4-call-001" \
  -d '{"filename":"q4-earnings-call.pdf","mime_type":"application/pdf","source_url":"https://example.com/q4-earnings-call.pdf","metadata":{"period":"Q4-2025","entity_id":"ent_aa12f"}}'

Analysis Runs

POST/runs

Start an asynchronous analysis run for a given objective.

Request Body

{
  "workspace_id": "ws_8f92b1",
  "entity_id": "ent_aa12f",
  "objective": "risk_scan",
  "file_ids": ["file_1942ac"]
}

Response Body

{
  "id": "run_55c7d8",
  "status": "queued",
  "estimated_seconds": 95
}

Status Codes

202 Accepted400 Bad Request401 Unauthorized404 Not Found

curl -X POST "https://api.equitista.com/v1/runs" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workspace_id":"ws_8f92b1","entity_id":"ent_aa12f","objective":"risk_scan","file_ids":["file_1942ac"]}'

Reports

GET/reports/{report_id}

Fetch report payload with summary, metrics, and citation references.

Response Body

{
  "id": "rep_77ad22",
  "status": "ready",
  "headline": "Margin compression risk identified in 2 segments",
  "sections": [{ "title": "Operating Performance", "confidence": 0.93 }],
  "citation_ids": ["cit_1001", "cit_1002"]
}

Status Codes

200 OK401 Unauthorized404 Not Found

curl -X GET "https://api.equitista.com/v1/reports/rep_77ad22" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY"

Citations

GET/reports/{report_id}/citations

List source-level citations with location metadata for audit trails.

Response Body

{
  "data": [
    {
      "id": "cit_1001",
      "file_id": "file_1942ac",
      "page": 18,
      "snippet": "Gross margin declined 220 bps year-over-year..."
    }
  ],
  "next_cursor": null
}

Status Codes

200 OK401 Unauthorized404 Not Found

curl -X GET "https://api.equitista.com/v1/reports/rep_77ad22/citations?limit=50" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY"

Webhooks

POST/webhooks

Request Body

{
  "url": "https://your-app.com/webhooks/equitista",
  "events": ["run.completed", "run.failed", "report.ready"],
  "secret": "whsec_live_..."
}

Response Body

{
  "id": "wh_29cc02",
  "status": "active"
}

Status Codes

201 Created400 Bad Request401 Unauthorized409 Conflict

curl -X POST "https://api.equitista.com/v1/webhooks" \
  -H "Authorization: Bearer $EQUITISTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.com/webhooks/equitista","events":["run.completed","run.failed","report.ready"],"secret":"whsec_live_..."}'

Error Catalog

Code	Meaning	Recommended Action
invalid_request	Malformed payload, missing required fields, or invalid query params.	Validate against endpoint schema and retry with corrected payload.
unauthorized	API key missing, invalid, or expired.	Refresh credentials and verify Bearer token format.
forbidden	Key does not have access to target workspace or resource.	Update key scope or use a key mapped to the target workspace.
rate_limited	Request exceeded burst or minute quota.	Respect Retry-After header and apply exponential backoff.
internal_error	Unexpected platform failure.	Retry idempotent requests and contact support with request_id.

Reliability and Delivery

Include idempotency keys on write operations to ensure safe retries.
Apply exponential backoff for 429 and transient 5xx responses.
Verify webhook signatures and store delivery attempts for auditability.
Correlate support tickets with request_idvalues from error payloads.

Changelog and Deprecation Policy

Backward-compatible additions may ship continuously. Breaking changes are version-gated and receive migration guidance before enforcement windows.

For access provisioning and migration support, contact developers@equitista.com.