OpenAPI spec
OpenAPI spec
Last updated 5/24/2026
# DataZoom API — OpenAPI 3.1 Specification
## Endpoint Summary
| # | Method | Path | Tag | Auth |
|---|--------|------|-----|------|
| 1 | GET | `/api/activity` | Activity | ✓ |
| 2 | POST | `/api/activity` | Activity | ✓ |
| 3 | GET | `/api/activity/export` | Activity | ✓ |
| 4 | GET | `/api/activity/metrics` | Activity | ✓ |
| 5 | GET | `/api/activity/unified/calendar` | Activity | ✓ |
| 6 | GET | `/api/activity/unified/day` | Activity | ✓ |
| 7 | GET | `/api/activity/unified/feed` | Activity | ✓ |
| 8 | POST | `/api/activity/unified/refresh` | Activity | ✓ |
| 9 | GET | `/api/admin/pipeline` | Admin | ✓ |
| 10 | POST | `/api/admin/pipeline/cloud` | Admin | ✓ |
| 11 | GET | `/api/admin/pipeline/health` | Admin | ✓ |
| 12 | POST | `/api/admin/pipeline/retry` | Admin | ✓ |
| 13 | GET | `/api/admin/routing-stats` | Admin | ✓ |
| 14 | GET | `/api/advisor` | Advisor | ✓ |
| 15 | POST | `/api/advisor` | Advisor | ✓ |
| 16 | POST | `/api/advisor/batch` | Advisor | ✓ |
| 17 | POST | `/api/advisor/process-queue` | Advisor | ✓ |
| 18 | POST | `/api/advisor/risk-memo` | Advisor | ✓ |
| 19 | POST | `/api/advisor/strategic-options` | Advisor | ✓ |
| 20 | POST | `/api/ai/track-interaction` | AI | ✓ |
| 21 | POST | `/api/analysis/party` | Analysis | ✓ |
| 22 | POST | `/api/analysis/regenerate` | Analysis | ✓ |
| 23 | GET | `/api/business-type-profiles` | Business Types | ✓ |
| 24 | GET | `/api/business-type-profiles/{profileKey}` | Business Types | ✓ |
| 25 | GET | `/api/business-types` | Business Types | ✓ |
| 26 | GET | `/api/business-types/{typeKey}/checklist` | Business Types | ✓ |
| 27 | GET | `/api/cap-table/as-of` | Cap Table | ✓ |
| 28 | POST | `/api/cap-table/auto-populate` | Cap Table | ✓ |
| 29 | GET | `/api/cap-table/current` | Cap Table | ✓ |
| 30 | POST | `/api/cap-table/extract` | Cap Table | ✓ |
| 31 | GET | `/api/cap-table/health` | Cap Table | ✓ |
| 32 | GET | `/api/cap-table/review` | Cap Table | ✓ |
| 33 | POST | `/api/cap-table/review/{id}/approve` | Cap Table | ✓ |
| 34 | POST | `/api/cap-table/review/{id}/reject` | Cap Table | ✓ |
| 35 | GET | `/api/cap-table/transactions` | Cap Table | ✓ |
| 36 | POST | `/api/cap-table/transactions` | Cap Table | ✓ |
| 37 | POST | `/api/cap-table/transactions/{id}/void` | Cap Table | ✓ |
| 38 | GET | `/api/clauses/compare` | Clauses | ✓ |
| 39 | GET | `/api/clauses/compare/{id}` | Clauses | ✓ |
| 40 | POST | `/api/clerk/proxy` | Auth | ✓ |
| 41 | POST | `/api/collaboration/token` | Collaboration | ✓ |
| 42 | GET | `/api/company-settings` | Company | ✓ |
| 43 | PUT | `/api/company-settings` | Company | ✓ |
| 44 | GET | `/api/company-settings/linkage-mismatches` | Company | ✓ |
---
```yaml
openapi: 3.1.0
info:
title: DataZoom API
version: 1.0.0
description: |
Enterprise-grade document analysis platform with RAG (Retrieval-Augmented Generation).
Enables natural language querying of legal and business documents, cap table management,
AI-driven advisory analysis, activity tracking, and multi-tenant organization management.
All endpoints require a valid Clerk session token transmitted as a Bearer token in the
`Authorization` header. Organization context is derived from the token's active org claim.
**Base URLs**
- Production: `https://app.datazoom.io`
- Staging: `https://staging.datazoom.io`
- Development: `http://localhost:3000`
contact:
name: DataZoom Engineering
email: engineering@datazoom.io
url: https://datazoom.io
license:
name: Proprietary
identifier: LicenseRef-DataZoom-Proprietary
servers:
- url: https://app.datazoom.io
description: Production
- url: https://staging.datazoom.io
description: Staging
- url: http://localhost:3000
description: Local development
security:
- ClerkBearer: []
tags:
- name: Activity
description: >
User and organization activity tracking, unified event calendar,
metrics aggregation, and activity feed operations.
- name: Admin
description: >
Internal pipeline management, cloud worker orchestration, model routing
diagnostics, and health monitoring. Restricted to admin roles.
- name: Advisor
description: >
AI-powered legal and strategic advisory endpoints including risk memos,
strategic options analysis, and batch advisory queue processing.
- name: AI
description: Interaction tracking and telemetry for AI model usage.
- name: Analysis
description: >
Document party analysis and analysis regeneration workflows.
- name: Business Types
description: >
Business type catalog, profile management, and due-diligence checklist
generation keyed by business type.
- name: Cap Table
description: >
Equity cap table read, extraction, manual transaction entry, review
workflow (approve/reject), and snapshot queries.
- name: Clauses
description: >
Contract clause extraction and cross-document clause comparison.
- name: Auth
description: Clerk authentication proxy utilities.
- name: Collaboration
description: Real-time collaborative editing token provisioning (Yjs / TipTap).
- name: Company
description: >
Organization-level settings management and document linkage integrity
diagnostics.
# ─────────────────────────────────────────────────────────────────────────────
# PATHS
# ─────────────────────────────────────────────────────────────────────────────
paths:
# ── Activity ────────────────────────────────────────────────────────────────
/api/activity:
get:
operationId: listActivity
tags: [Activity]
summary: List activity log entries
description: >
Returns a paginated list of activity log entries for the authenticated
organization. Supports filtering by event type, date range, and actor.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: event_type
in: query
schema:
type: string
example: document_upload
description: Filter by activity event type.
- name: actor_id
in: query
schema:
type: string
format: uuid
description: Filter by the Clerk user ID of the actor.
- name: from
in: query
schema:
type: string
format: date-time
description: ISO 8601 start bound (inclusive).
- name: to
in: query
schema:
type: string
format: date-time
description: ISO 8601 end bound (inclusive).
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
description: Paginated activity entries.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
post:
operationId: createActivity
tags: [Activity]
summary: Create an activity log entry
description: >
Manually logs a structured activity event. Most events are created
server-side by background workers; this endpoint is available for
client-initiated events such as user UI actions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityCreateRequest'
responses:
'200':
description: Created activity entry.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityEntry'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/export:
get:
operationId: exportActivity
tags: [Activity]
summary: Export activity log as CSV
description: >
Streams a CSV export of the organization's activity log. Supports the
same filter parameters as `GET /api/activity`. The `Content-Disposition`
header will contain an auto-generated filename.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: event_type
in: query
schema:
type: string
- name: from
in: query
schema:
type: string
format: date-time
- name: to
in: query
schema:
type: string
format: date-time
responses:
'200':
description: CSV file stream.
content:
text/csv:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/metrics:
get:
operationId: getActivityMetrics
tags: [Activity]
summary: Retrieve aggregated activity metrics
description: >
Returns pre-aggregated metrics derived from the activity log materialized
views. Includes event counts grouped by type, date bucket, and actor.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: period
in: query
schema:
type: string
enum: [day, week, month, quarter]
default: week
description: Aggregation period bucket.
- name: from
in: query
schema:
type: string
format: date
- name: to
in: query
schema:
type: string
format: date
responses:
'200':
description: Aggregated metrics payload.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityMetricsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/unified/calendar:
get:
operationId: getUnifiedCalendar
tags: [Activity]
summary: Unified event calendar month view
description: >
Returns a calendar-shaped payload (days → events) for the requested
month. Merges activity log entries, timeline events, and due-diligence
milestones into a single chronological structure.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: year
in: query
required: true
schema:
type: integer
minimum: 2000
maximum: 2100
example: 2025
- name: month
in: query
required: true
schema:
type: integer
minimum: 1
maximum: 12
example: 7
responses:
'200':
description: Calendar month data.
content:
application/json:
schema:
$ref: '#/components/schemas/UnifiedCalendarResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/unified/day:
get:
operationId: getUnifiedDay
tags: [Activity]
summary: Unified event list for a single day
description: >
Returns all unified events (activity, timeline, DD milestones) for a
specific calendar day. Used by the day-drill-down view at
`/activity/[year]/[month]/[day]`.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: date
in: query
required: true
schema:
type: string
format: date
example: '2025-07-04'
responses:
'200':
description: Events for the requested day.
content:
application/json:
schema:
$ref: '#/components/schemas/UnifiedDayResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/unified/feed:
get:
operationId: getUnifiedFeed
tags: [Activity]
summary: Chronological unified event feed
description: >
Returns a reverse-chronological feed of all unified events. Designed
for the activity feed component in `activity-content.tsx`. Supports
cursor-based pagination via `cursor`.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: cursor
in: query
schema:
type: string
description: >
Opaque pagination cursor returned by a previous response. Omit for
the first page.
- $ref: '#/components/parameters/LimitParam'
responses:
'200':
description: Feed page.
content:
application/json:
schema:
$ref: '#/components/schemas/UnifiedFeedResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/activity/unified/refresh:
post:
operationId: refreshUnifiedActivity
tags: [Activity]
summary: Trigger materialized view refresh
description: >
Forces a synchronous refresh of the activity materialized views for the
organization. Intended for use after bulk operations (e.g., large
document imports) when stale view data is unacceptable.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
org_id:
type: string
description: >
Override the org derived from the session. Admin-only.
responses:
'200':
description: Refresh completed.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
# ── Admin ───────────────────────────────────────────────────────────────────
/api/admin/pipeline:
get:
operationId: getPipelineStatus
tags: [Admin]
summary: Get document ingestion pipeline status
description: >
Returns the current state of all pipeline workers including BullMQ
queue depths, active job counts, completed/failed counters, and
last-heartbeat timestamps. Requires admin organization membership.
responses:
'200':
description: Pipeline status snapshot.
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineStatusResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/admin/pipeline/cloud:
post:
operationId: dispatchCloudPipeline
tags: [Admin]
summary: Dispatch document to cloud processing pipeline
description: >
Routes a document to the cloud worker (RunPod / Modal) for GPU-
accelerated embedding and LLM analysis. Used when the local worker
queue is saturated or a cloud-only model is required.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CloudPipelineDispatchRequest'
responses:
'200':
description: Dispatch accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineJobReference'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/admin/pipeline/health:
get:
operationId: getPipelineHealth
tags: [Admin]
summary: Pipeline health check
description: >
Lightweight liveness probe that checks connectivity to Redis (BullMQ),
Supabase, and the cloud worker orchestrator. Returns degraded status
with per-dependency breakdown on partial failure.
responses:
'200':
description: Health status (may include degraded components).
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineHealthResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/admin/pipeline/retry:
post:
operationId: retryPipelineJob
tags: [Admin]
summary: Retry a failed pipeline job
description: >
Re-enqueues a failed document ingestion job identified by its BullMQ
job ID. The job will be retried from the beginning of its pipeline
stage unless `from_stage` is specified.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRetryRequest'
responses:
'200':
description: Job successfully re-enqueued.
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineJobReference'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/admin/routing-stats:
get:
operationId: getRoutingStats
tags: [Admin]
summary: Model routing statistics
description: >
Returns per-model routing statistics including request counts, average
latency, token usage, error rates, and cost estimates. Derived from
the model router telemetry tables.
parameters:
- name: period
in: query
schema:
type: string
enum: [hour, day, week]
default: day
responses:
'200':
description: Routing statistics.
content:
application/json:
schema:
$ref: '#/components/schemas/RoutingStatsResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
# ── Advisor ─────────────────────────────────────────────────────────────────
/api/advisor:
get:
operationId: listAdvisorAnalyses
tags: [Advisor]
summary: List advisor analyses for the organization
description: >
Returns previously generated advisor analyses (risk memos, strategic
options) for the authenticated organization, ordered by creation date
descending.
parameters:
- $ref: '#/components/parameters/OrgId'
- name: analysis_type
in: query
schema:
type: string
enum: [risk_memo, strategic_options, batch]
- $ref: '#/components/parameters/LimitParam'
- $ref: '#/components/parameters/PageParam'
responses:
'200':
description: List of advisor analyses.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorAnalysisListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
post:
operationId: createAdvisorAnalysis
tags: [Advisor]
summary: Create a new advisor analysis
description: >
Initiates an AI advisor analysis for specified documents or an entire
dataroom. The response includes a job ID that can be polled for
completion status.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorAnalysisCreateRequest'
responses:
'200':
description: Analysis job created.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorAnalysisJobResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/advisor/batch:
post:
operationId: batchAdvisorAnalysis
tags: [Advisor]
summary: Submit a batch of advisor analysis jobs
description: >
Enqueues multiple advisor analysis tasks in a single request. Each item
in the batch is processed independently via the BullMQ advisor queue.
Returns an array of job references in the same order as the input.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorBatchRequest'
responses:
'200':
description: Batch accepted; array of job references returned.
content:
application/json:
schema:
$ref: '#/components/schemas/AdvisorBatchResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/advisor/process-queue:
post:
operationId: processAdvisorQueue
tags: [Advisor]
summary: Trigger advisor queue processing
description: >
Instructs the server to begin draining the pending advisor analysis
queue for the organization. Typically called by a cron job or after
a batch submission. Returns the number of jobs dispatched.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
max_jobs:
type: integer
minimum: 1
maximum: 50
default: 10
description: Maximum number of queued jobs to dispatch in this call.
responses:
'200':
description: Queue processing initiated.
content:
application/json:
schema:
$ref: '#/components/schemas/QueueProcessResult'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/advisor/risk-memo:
post:
operationId: generateRiskMemo
tags: [Advisor]
summary: Generate an AI risk memo
description: >
Runs the risk-memo generation pipeline against one or more documents.
The LLM (Qwen2.5:32B via Modal or local Ollama) extracts risk factors,
scores severity, and produces a structured memo with citations to
source document chunks.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RiskMemoRequest'
responses:
'200':
description: Generated risk memo.
content:
application/json:
schema:
$ref: '#/components/schemas/RiskMemoResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/advisor/strategic-options:
post:
operationId: generateStrategicOptions
tags: [Advisor]
summary: Generate strategic options analysis
description: >
Produces a structured strategic-options analysis using single-stage
direct dispatch to the LLM. Returns a ranked list of options with
rationale and risk/benefit scoring derived from the document corpus.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StrategicOptionsRequest'
responses:
'200':
description: Strategic options analysis.
content:
application/json:
schema:
$ref: '#/components/schemas/StrategicOptionsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
# ── AI ──────────────────────────────────────────────────────────────────────
/api/ai/track-interaction:
post:
operationId: trackAiInteraction
tags: [AI]
summary: Track an AI model interaction
description: >
Records a completed AI interaction for telemetry, billing, and
Mixpanel analytics. Called client-side after a chat response is
displayed. Idempotent when the same `interaction_id` is submitted
more than once.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AiTrackInteractionRequest'
responses:
'200':
description: Interaction recorded.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessMessage'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
# ── Analysis ────────────────────────────────────────────────────────────────
/api/analysis/party:
post:
operationId: analyzeParty
tags: [Analysis]
summary: Run party extraction analysis on a document
description: >
Extracts and resolves named parties from a document, cross-referencing
the knowledge graph to disambiguate entities. Returns structured party
records with roles, aliases, and related document references.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PartyAnalysisRequest'
responses:
'200':
description: Extracted party analysis.
content:
application/json:
schema:
$ref: '#/components/schemas/PartyAnalysisResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/analysis/regenerate:
post:
operationId: regenerateAnalysis
tags: [Analysis]
summary: Regenerate document analysis
description: >
Clears cached analysis for the specified document and re-runs the full
analysis pipeline including summary generation, party extraction,
timeline event extraction, and risk scoring.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RegenerateAnalysisRequest'
responses:
'200':
description: Regeneration job queued.
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineJobReference'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
# ── Business Type Profiles ───────────────────────────────────────────────────
/api/business-type-profiles:
get:
operationId: listBusinessTypeProfiles
tags: [Business Types]
summary: List all business type profiles
description: >
Returns the full catalog of business type profiles. Each profile
defines document requirements, checklist templates, and due-diligence
module linkages for a given business category.
parameters:
- $ref: '#/components/parameters/OrgId'
responses:
'200':
description: Array of business type profiles.
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessTypeProfileListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalError'
/api/business-type-profiles/{profileKey}:
get:
operationId: getBusinessTypeProfile
tags: [Business Types]
summary: Get a specific business type profile
description: >
Returns full profile detail for a single business type key, including
document catalog requirements, module linkages, and checklist template
metadata.
parameters:
- name: profileKey
in: path
required: true
schema:
type: string
example: saas_startup
description: Unique slug identifier for the business type profile.
- $ref: '#/components/parameters/OrgId'
responses:
'200':
description: Business type profile detail.
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessTypeProfile'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalError'
/api/business-types:
get:
operationId: listBusinessTypes
tags: [Business Types]
summary: List available business types
description: >
Returns the enumerated list of supported business type keys with
display labels. Used to populate business-type selectors in the
company settings and due-diligence onboarding flows.
responses:
'200':
description: Business type list.
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessTypeListResponse'