API reference

75 endpoints, read from the running API's own OpenAPI document. For the walkthrough, keys and MCP setup, start with the guide.

Base URL: https://aggre.orbbit.ai
Auth: x-aggre-api-key: aggre_sk_… or Authorization: Bearer aggre_sk_…
Errors: JSON { "error": "…" } with the status code. A refusal names what was refused and why.
Try it: Swagger UI sends real requests; openapi.json is the raw document.

Use the data

Any key that can read the datasets.

MCP over HTTP

Every MCP tool, callable as plain JSON. List the tools, then call one by name.

MCP call

POST/v1/mcp/call

Request body · McpCallRequest
Name	Type	Notes
`arguments`	`any`
`name`required	`string`

200 response · McpCallResponse

200 response fields
Name	Type	Notes
`name`required	`string`
`result`required	`any`

Errors: 400, 401, 403

List MCP tools

GET/v1/mcp/tools

200 response · McpToolResponse

200 response fields
Name	Type	Notes
`tools`required	`any[]`

Search and export

Search across the datasets a key can read, read one record, or export in bulk.

Export records

POST/v1/export

Request body · ExportRequest
Name	Type	Notes
`dataset_id`required	`uuid`
`format`	`null \| DataFormat`
`limit`	`integer \| null`

200 response · ExportResponse

200 response fields
Name	Type	Notes
`content`	`string \| null`
`format`required	`DataFormat`
`records`required	`Record[]`
`total`required	`integer`

Errors: 404

Get record

GET/v1/records/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Record ID

200 response · Record

200 response fields
Name	Type	Notes
`created_at`required	`string`
`data`required	`any`
`data_hash`	`string \| null`
`dataset_id`required	`uuid`
`external_id`	`string \| null`
`id`required	`uuid`
`source_id`	`uuid \| null`
`version`required	`integer`

Errors: 404

Search

POST/v1/search

Request body · SearchRequest
Name	Type	Notes
`dataset_id`	`uuid \| null`
`limit`	`integer \| null`
`query`required	`string`

200 response · SearchResponse

200 response fields
Name	Type	Notes
`results`required	`Record[]`
`total`required	`integer`

Errors: 500

Catalog

The platform datasets your plan lets you select, and your organization's selections.

Get catalog

GET/v1/catalog

Parameters
Name	In	Type	Notes
`org_id`	query	`uuid`	Staff only: another organization's view

200 response · CatalogResponse

200 response fields
Name	Type	Notes
`categories`required	`CatalogCategory[]`	The platform's categories (a flat list; nest by `parent_id`), each with the datasets filed directly under it.
`limit`required	`CatalogLimit`
`org_id`required	`uuid`
`other`required	`CatalogDataset[]`	Catalog datasets in no category, plus the org's own datasets.
`tier`required	`Tier`
`used`required	`integer`	Selections counted against `limit.total` right now.

Errors: 401, 403, 404

Select catalog dataset

POST/v1/catalog/selections

Request body · SelectCatalogDatasetRequest
Name	Type	Notes
`dataset_id`required	`uuid`
`org_id`	`uuid \| null`	Staff only: select on behalf of another organization.

200 response · OrgDatasetSelection

200 response fields
Name	Type	Notes
`created_at`required	`string`
`dataset_id`required	`uuid`
`org_id`required	`uuid`

Errors: 401, 403, 404, 409

Deselect catalog dataset

DELETE/v1/catalog/selections/{dataset_id}

Parameters
Name	In	Type	Notes
`dataset_id`required	path	`uuid`	Dataset ID
`org_id`	query	`uuid`	Staff only: another organization

204 response

Errors: 401, 403, 404

Datasets

Datasets your key can read: their records, versions and counts.

List datasets

GET/v1/datasets

200 response · PaginatedDataset

200 response fields
Name	Type	Notes
`items`required	`Dataset[]`
`total`required	`integer`

Errors: 500

Create dataset

POST/v1/datasets

Request body · CreateDatasetRequest
Name	Type	Notes
`category`	`string \| null`
`description`	`string \| null`
`governance`	`any`
`name`required	`string`
`org_id`	`uuid \| null`
`schema`	`any`
`slug`required	`string`
`tags`	`string[] \| null`

200 response · Dataset

200 response fields
Name	Type	Notes
`category`	`string \| null`
`created_at`required	`string`
`description`	`string \| null`
`governance`required	`any`
`id`required	`uuid`
`name`required	`string`
`org_id`required	`uuid`
`schema`required	`any`
`slug`required	`string`
`status`required	`DatasetStatus`
`tags`required	`string[]`
`updated_at`required	`string`
`version`required	`integer`

Errors: 500

Get customer dataset stats

GET/v1/datasets/stats

200 response

Errors: 401

Get dataset

GET/v1/datasets/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID

200 response · Dataset

200 response fields
Name	Type	Notes
`category`	`string \| null`
`created_at`required	`string`
`description`	`string \| null`
`governance`required	`any`
`id`required	`uuid`
`name`required	`string`
`org_id`required	`uuid`
`schema`required	`any`
`slug`required	`string`
`status`required	`DatasetStatus`
`tags`required	`string[]`
`updated_at`required	`string`
`version`required	`integer`

Errors: 404

Update dataset

PATCH/v1/datasets/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID

Request body · UpdateDatasetRequest
Name	Type	Notes
`category`	`string \| null`
`description`	`string \| null`
`governance`	`any`
`name`	`string \| null`
`schema`	`any`
`status`	`null \| DatasetStatus`
`tags`	`string[] \| null`

200 response · Dataset

200 response fields
Name	Type	Notes
`category`	`string \| null`
`created_at`required	`string`
`description`	`string \| null`
`governance`required	`any`
`id`required	`uuid`
`name`required	`string`
`org_id`required	`uuid`
`schema`required	`any`
`slug`required	`string`
`status`required	`DatasetStatus`
`tags`required	`string[]`
`updated_at`required	`string`
`version`required	`integer`

Errors: 400, 404

List records

GET/v1/datasets/{id}/records

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID
`limit`	query	`integer`	Page size, 1-500 (omit both limit and offset for the full dump)
`offset`	query	`integer`	Page offset

200 response · PaginatedRecord

200 response fields
Name	Type	Notes
`items`required	`Record[]`
`total`required	`integer`

Errors: 404

Count records

GET/v1/datasets/{id}/records/count

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID

200 response · RecordCountResponse

200 response fields
Name	Type	Notes
`count`required	`integer`

Errors: 404

Republish dataset

POST/v1/datasets/{id}/republish

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID

200 response · RepublishResponse

200 response fields
Name	Type	Notes
`dataset`required	`Dataset`
`job`required	`Job`
`records`required	`integer`
`version`required	`DatasetVersion`

Errors: 400, 404

List dataset versions

GET/v1/datasets/{id}/versions

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Dataset ID

200 response · PaginatedDatasetVersion

200 response fields
Name	Type	Notes
`items`required	`DatasetVersion[]`
`total`required	`integer`

Errors: 404

Your account

Owners and admins of an organization.

API keys

Create, list and revoke keys. A key never carries more than the person who made it.

List API keys

GET/v1/api-keys

Parameters
Name	In	Type	Notes
`org_id`	query	`uuid`	Filter to one organization (staff may name any)

200 response · ApiKey[]

Errors: 403, 500

Create API key

POST/v1/api-keys

Request body · CreateApiKeyRequest
Name	Type	Notes
`dataset_ids`	`uuid[] \| null`	Datasets the key may read. Omit for every dataset the org can read; an empty list is refused rather than read as "nothing".
`name`required	`string`
`org_id`	`uuid \| null`
`scopes`	`Permission[] \| null`

200 response · ApiKeyCreated

200 response fields
Name	Type	Notes
`key`required	`ApiKey`
`secret_once`required	`string`

Errors: 500

Revoke API key

POST/v1/api-keys/{id}/revoke

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	API key ID

200 response · ApiKey

200 response fields
Name	Type	Notes
`created_at`required	`string`
`dataset_ids`	`uuid[] \| null`	The datasets this key may read. `None` means every dataset its org can read; a list narrows the key further, never widens the org's access.
`expires_at`	`string \| null`
`id`required	`uuid`
`name`required	`string`
`org_id`required	`uuid`
`prefix`required	`string`
`revoked_at`	`string \| null`
`scopes`required	`Permission[]`
`secret_hash`required	`string`

Errors: 401, 403, 404

Usage

Metered calls, for the organization's monthly total.

List usage events

GET/v1/usage

200 response · UsageEvent[]

Errors: 401, 403

Billing

The plan summary. Changing plans and credits is staff-only until payments go live.

Create credit entry

POST/v1/billing/credits

Request body · CreateCreditRequest
Name	Type	Notes
`amount`required	`integer`
`metadata`	`any`
`org_id`	`uuid \| null`	The org to credit (staff may name any); defaults to the caller's.
`reason`required	`string`

200 response · CreditLedgerEntry

200 response fields
Name	Type	Notes
`amount`required	`integer`
`created_at`required	`string`
`id`required	`uuid`
`metadata`required	`any`
`org_id`required	`uuid`
`reason`required	`string`

Errors: 400, 401, 403

Create invoice

POST/v1/billing/invoices

Request body · CreateInvoiceRequest
Name	Type	Notes
`amount_due`required	`integer`
`currency`required	`string`
`hosted_invoice_url`	`string \| null`
`period_end`	`string \| null`
`period_start`	`string \| null`
`provider`	`string \| null`
`provider_invoice_id`	`string \| null`
`status`required	`string`

200 response · InvoiceRecord

200 response fields
Name	Type	Notes
`amount_due`required	`integer`
`created_at`required	`string`
`currency`required	`string`
`hosted_invoice_url`	`string \| null`
`id`required	`uuid`
`org_id`required	`uuid`
`period_end`	`string \| null`
`period_start`	`string \| null`
`provider`required	`string`
`provider_invoice_id`	`string \| null`
`status`required	`string`

Errors: 400, 401, 403

Stripe webhook

POST/v1/billing/stripe/webhook

Request body · StripeWebhookRequest
Name	Type	Notes
`data`required	`any`
`event_type`required	`string`
`org_id`	`uuid \| null`

200 response · StripeWebhookResponse

200 response fields
Name	Type	Notes
`accepted`required	`boolean`
`action`required	`string`
`invoice`	`null \| InvoiceRecord`
`subscription`	`null \| BillingSubscription`

Errors: 400, 401, 403

Upsert billing subscription

POST/v1/billing/subscription

Request body · UpsertSubscriptionRequest
Name	Type	Notes
`current_period_end`	`string \| null`
`current_period_start`	`string \| null`
`org_id`	`uuid \| null`
`provider`	`string \| null`
`provider_subscription_id`	`string \| null`
`status`required	`string`
`tier`required	`Tier`

200 response · BillingSubscription

200 response fields
Name	Type	Notes
`created_at`required	`string`
`current_period_end`	`string \| null`
`current_period_start`	`string \| null`
`id`required	`uuid`
`org_id`required	`uuid`
`provider`required	`string`
`provider_subscription_id`	`string \| null`
`status`required	`string`
`tier`required	`Tier`
`updated_at`required	`string`

Errors: 400, 401, 403

Billing summary

GET/v1/billing/summary

Parameters
Name	In	Type	Notes
`org_id`	query	`uuid`	Staff only: another organization's summary

200 response · BillingSummary

200 response fields
Name	Type	Notes
`addon_dataset_slots`	`integer`
`catalog_selected`	`integer`	Catalog selections currently counted against the plan's limit.
`credit_balance`required	`integer`
`entitlements`required	`Entitlements`
`invoices`required	`InvoiceRecord[]`
`org_id`required	`uuid`
`period`	`string`	The billing period `request_usage` covers, `YYYY-MM` (UTC).
`request_usage`required	`integer`	Data-plane requests the org made in `period` (all keys and SSO sessions together) -- the number `entitlements.monthly_requests` caps.
`subscription`	`null \| BillingSubscription`
`tier`required	`Tier`

Errors: 401, 403, 404

X402 quote

POST/v1/x402/quote

Request body · X402QuoteRequest
Name	Type	Notes
`route`required	`string`
`units`	`integer \| null`

200 response · X402Quote

200 response fields
Name	Type	Notes
`amount`required	`integer`
`currency`required	`string`
`expires_at`required	`string`
`id`required	`uuid`
`payment_header`required	`string`
`route`required	`string`
`units`required	`integer`

Errors: 400, 401, 403

X402 settle

POST/v1/x402/settle

Request body · X402SettleRequest
Name	Type	Notes
`amount`required	`integer`
`currency`required	`string`
`proof`	`string \| null`
`quote_id`required	`uuid`
`route`required	`string`

200 response · X402SettleResponse

200 response fields
Name	Type	Notes
`accepted`required	`boolean`
`ledger_entry`required	`CreditLedgerEntry`

Errors: 400, 401, 403

Bring your own data

Keys with write access to their organization's datasets.

Sources

Where a dataset's records come from: preview a source, then run it.

List sources

GET/v1/sources

Parameters
Name	In	Type	Notes
`dataset_id`	query	`uuid`	Optional dataset filter

200 response · PaginatedSource

200 response fields
Name	Type	Notes
`items`required	`Source[]`
`total`required	`integer`

Errors: 500

Create source

POST/v1/sources

Request body · CreateSourceRequest
Name	Type	Notes
`config`	`any`
`dataset_id`required	`uuid`
`kind`required	`SourceKind`
`name`required	`string`
`org_id`	`uuid \| null`
`schedule_interval_minutes`	`integer \| null`
`slug`required	`string`

200 response · Source

200 response fields
Name	Type	Notes
`config`required	`any`
`created_at`required	`string`
`dataset_id`required	`uuid`
`enabled`required	`boolean`
`id`required	`uuid`
`kind`required	`SourceKind`
`name`required	`string`
`org_id`required	`uuid`
`schedule_interval_minutes`	`integer \| null`	How often the scheduler should automatically re-run this source, in minutes. `None` means manual-only (the pre-existing behavior).
`slug`required	`string`
`updated_at`required	`string`

Errors: 404

Get source

GET/v1/sources/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID

200 response · Source

200 response fields
Name	Type	Notes
`config`required	`any`
`created_at`required	`string`
`dataset_id`required	`uuid`
`enabled`required	`boolean`
`id`required	`uuid`
`kind`required	`SourceKind`
`name`required	`string`
`org_id`required	`uuid`
`schedule_interval_minutes`	`integer \| null`	How often the scheduler should automatically re-run this source, in minutes. `None` means manual-only (the pre-existing behavior).
`slug`required	`string`
`updated_at`required	`string`

Errors: 404

Update source

PATCH/v1/sources/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID

Request body · UpdateSourceRequest
Name	Type	Notes
`config`	`any`
`enabled`	`boolean \| null`
`name`	`string \| null`
`schedule_interval_minutes`	`integer \| null`	Set to change the schedule; `Some(0)` (or any non-positive value) clears it back to manual-only. `None` leaves it unchanged.

200 response · Source

200 response fields
Name	Type	Notes
`config`required	`any`
`created_at`required	`string`
`dataset_id`required	`uuid`
`enabled`required	`boolean`
`id`required	`uuid`
`kind`required	`SourceKind`
`name`required	`string`
`org_id`required	`uuid`
`schedule_interval_minutes`	`integer \| null`	How often the scheduler should automatically re-run this source, in minutes. `None` means manual-only (the pre-existing behavior).
`slug`required	`string`
`updated_at`required	`string`

Errors: 400, 404

Enqueue source

POST/v1/sources/{id}/enqueue

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 400, 404

Ingest source

POST/v1/sources/{id}/ingest

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID

Request body · IngestRequest
Name	Type	Notes
`cursor`	`string \| null`
`format`	`null \| DataFormat`
`job_id`	`uuid \| null`
`records`required	`any[]`

200 response · IngestResponse

200 response fields
Name	Type	Notes
`accepted`required	`integer`
`cursor`	`string \| null`
`errors`required	`string[]`
`job`required	`Job`
`raw_archive`required	`RawArchive`
`records`required	`Record[]`
`rejected`required	`integer`

Errors: 400, 404

Preview source

POST/v1/sources/{id}/preview

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID
`limit`	query	`integer`	Preview record limit, capped at 50

200 response · SourcePreviewResponse

200 response fields
Name	Type	Notes
`accepted`required	`integer`
`dataset_id`required	`uuid`
`errors`required	`string[]`
`format`required	`string`
`records`required	`any[]`
`rejected`required	`integer`
`returned`required	`integer`
`source_id`required	`uuid`
`total`required	`integer`

Errors: 400, 404, 502

Same fire-and-poll shape as run_job (see the comment there) -- a source with a large enough backlog can take longer to fetch and ingest than a proxy's request timeout allows, so this starts the job and returns immediately rather than blocking the response on the whole run.

POST/v1/sources/{id}/run

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Source ID

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 400, 404, 502

Jobs

Pipeline runs and the errors they logged.

List error logs

GET/v1/error-logs

Parameters
Name	In	Type	Notes
`job_id`	query	`uuid`	Optional job filter
`source_id`	query	`uuid`	Optional source filter
`dataset_id`	query	`uuid`	Optional dataset filter

200 response · PipelineErrorLog[]

Errors: 401, 403

List jobs

GET/v1/jobs

200 response · Job[]

Errors: 500

Create job

POST/v1/jobs

Request body · CreateJobRequest
Name	Type	Notes
`dataset_id`	`uuid \| null`
`kind`required	`JobKind`
`max_attempts`	`integer \| null`
`source_id`	`uuid \| null`

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 500

Get job

GET/v1/jobs/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Job ID

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 404

Claim job

POST/v1/jobs/{id}/claim

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Job ID

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 400, 404

Fetching + ingesting can take far longer than a proxy's request timeout once a source has tens of thousands of records (each paginated fetch is one round trip, and a big enough batch of records is still real work to validate and write). Doing that inline in the HTTP handler meant a slow run got its connection killed by the reverse proxy mid-flight, which silently dropped the in-flight future -- the job was left stuck at "running" forever, while whatever had already been written stayed in the dataset. So run_job only starts the job and returns immediately; the actual work happens in a spawned task, and callers poll GET /v1/jobs/{id} for the terminal status.

POST/v1/jobs/{id}/run

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Job ID

200 response · Job

200 response fields
Name	Type	Notes
`attempts`required	`integer`
`created_at`required	`string`
`dataset_id`	`uuid \| null`
`error`	`string \| null`
`id`required	`uuid`
`kind`required	`JobKind`
`max_attempts`required	`integer`
`source_id`	`uuid \| null`
`status`required	`JobStatus`
`updated_at`required	`string`

Errors: 400, 404

Raw archives

The untouched payloads every run keeps.

List raw archives

GET/v1/raw-archives

200 response · PaginatedRawArchive

200 response fields
Name	Type	Notes
`items`required	`RawArchive[]`
`total`required	`integer`

Errors: 500

Platform staff

Only Orbbit's own staff organization.

Grants

Category access given to an organization outside its plan.

List subscriptions

GET/v1/subscriptions

Parameters
Name	In	Type	Notes
`org_id`	query	`uuid`	Filter to one organization's subscriptions

200 response · Subscription[]

Errors: 401, 403

Create subscription

POST/v1/subscriptions

Request body · CreateSubscriptionRequest
Name	Type	Notes
`category_id`required	`uuid`
`org_id`required	`uuid`

200 response · Subscription

200 response fields
Name	Type	Notes
`category_id`required	`uuid`
`created_at`required	`string`
`org_id`required	`uuid`

Errors: 401, 403, 404

Delete subscription

DELETE/v1/subscriptions/{org_id}/{category_id}

Parameters
Name	In	Type	Notes
`org_id`required	path	`uuid`	Organization ID
`category_id`required	path	`uuid`	Category ID

204 response

Errors: 401, 403, 404

Administration

Every organization, user and key, and platform status.

List orgs

GET/v1/admin/orgs

Parameters
Name	In	Type	Notes
`q`	query	`string`	Matches slug, name or a member's email (case-insensitive)
`limit`	query	`integer`	Page size, 1-200 (default 50)
`offset`	query	`integer`	Page offset

200 response · AdminOrgList

200 response fields
Name	Type	Notes
`items`required	`AdminOrgRow[]`
`total`required	`integer`

Errors: 401, 403

Get org

GET/v1/admin/orgs/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Organization ID

200 response · AdminOrgDetail

200 response fields
Name	Type	Notes
`api_keys`required	`ApiKey[]`
`billing`required	`BillingSummary`
`grants`required	`AdminGrant[]`
`members`required	`AdminMember[]`
`org`required	`Organization`
`selections`required	`AdminSelection[]`
`usage`required	`AdminUsage`

Errors: 401, 403, 404

Update org

PATCH/v1/admin/orgs/{id}

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Organization ID

Request body · AdminUpdateOrgRequest
Name	Type	Notes
`addon_dataset_slots`	`integer \| null`
`name`	`string \| null`
`tier`	`null \| Tier`

200 response · Organization

200 response fields
Name	Type	Notes
`addon_dataset_slots`	`integer`	Catalog datasets this org may select on top of its tier's `catalog_datasets`. Staff-set for now; a paid add-on later.
`created_at`required	`string`
`id`required	`uuid`
`kind`required	`OrganizationKind`	GitHub-style account model: every Orbbit SSO login gets a Personal org (auto-provisioned, sole Owner) so customers never need to be granted membership anywhere just to use Aggre. Team orgs are for multi-member organizations -- including Orbbit's own internal staff org -- and are created explicitly. Enterprise is a billing `Tier` on a Team org, not a separate kind, since org shape and billing tier are independent axes.
`name`required	`string`
`slug`required	`string`
`tier`required	`Tier`

Errors: 400, 401, 403, 404

Add org member

POST/v1/admin/orgs/{id}/members

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Organization ID

Request body · AdminAddMemberRequest
Name	Type	Notes
`email`required	`string`
`role`required	`Role`

200 response · AdminMember

200 response fields
Name	Type	Notes
`created_at`required	`string`	When the membership (not the user) was created.
`email`required	`string`
`name`required	`string`
`role`required	`Role`
`user_id`required	`uuid`

Errors: 400, 401, 403, 404

Status

GET/v1/admin/status

200 response · AdminStatusResponse

200 response fields
Name	Type	Notes
`audit_logs`required	`integer`
`auth_required`required	`boolean`
`credit_ledger_entries`required	`integer`
`database_enabled`required	`boolean`
`dataset_versions`required	`integer`
`datasets`required	`integer`
`error_logs`required	`integer`
`event_backend`required	`string`
`event_target`required	`string`
`invoices`required	`integer`
`job_queue_backend`required	`string`
`job_queue_target`required	`string`
`jobs`required	`integer`
`organization_members`required	`integer`
`organizations`required	`integer`
`raw_archive_backend`required	`string`
`raw_archive_location`required	`string`
`raw_archive_root`required	`string`
`raw_archives`required	`integer`
`request_quota_per_key`required	`integer`
`sources`required	`integer`
`subscriptions`required	`integer`
`usage_events`required	`integer`
`users`required	`integer`

Errors: 401, 403

List users

GET/v1/admin/users

Parameters
Name	In	Type	Notes
`q`	query	`string`	Matches email or name (case-insensitive)
`limit`	query	`integer`	Page size, 1-200 (default 50)
`offset`	query	`integer`	Page offset

200 response · AdminUserList

200 response fields
Name	Type	Notes
`items`required	`AdminUserRow[]`
`total`required	`integer`

Errors: 401, 403

List audit logs

GET/v1/audit-logs

Parameters
Name	In	Type	Notes
`limit`	query	`integer`	Page size, 1-500
`offset`	query	`integer`	Page offset

200 response · PaginatedAuditLog

200 response fields
Name	Type	Notes
`items`required	`AuditLog[]`
`total`required	`integer`

Errors: 401, 403

legal-api runs on an internal-only address (not reachable from the browser), so the admin console goes through this proxy rather than calling it directly.

GET/v1/legal-api/judicial-credentials

200 response · JudicialCredentialsStatus

200 response fields
Name	Type	Notes
`configured`required	`boolean`
`source`required	`string`
`username`	`string \| null`

Errors: 401, 403, 502

Put legal API judicial credentials

PUT/v1/legal-api/judicial-credentials

Request body · SetJudicialCredentialsRequest
Name	Type	Notes
`password`required	`string`
`username`required	`string`

204 response

Errors: 400, 401, 403, 502

Delete legal API judicial credentials

DELETE/v1/legal-api/judicial-credentials

204 response

Errors: 401, 403, 502

Proxy to legal-api's Twelve Data API key setting (global-equities provider), mirroring the judicial-credentials proxy above -- legal-api is internal-only.

GET/v1/legal-api/twelvedata-key

200 response · TwelveDataKeyStatus

200 response fields
Name	Type	Notes
`configured`required	`boolean`
`hint`	`string \| null`
`source`required	`string`

Errors: 401, 403, 502

Put legal API twelvedata key

PUT/v1/legal-api/twelvedata-key

Request body · SetTwelveDataKeyRequest
Name	Type	Notes
`key`required	`string`

204 response

Errors: 400, 401, 403, 502

Delete legal API twelvedata key

DELETE/v1/legal-api/twelvedata-key

204 response

Errors: 401, 403, 502

List organizations

GET/v1/orgs

200 response · Organization[]

Errors: 401, 403

Create organization

POST/v1/orgs

Request body · CreateOrganizationRequest
Name	Type	Notes
`kind`	`null \| OrganizationKind`
`name`required	`string`
`slug`required	`string`
`tier`	`null \| Tier`

200 response · Organization

200 response fields
Name	Type	Notes
`addon_dataset_slots`	`integer`	Catalog datasets this org may select on top of its tier's `catalog_datasets`. Staff-set for now; a paid add-on later.
`created_at`required	`string`
`id`required	`uuid`
`kind`required	`OrganizationKind`	GitHub-style account model: every Orbbit SSO login gets a Personal org (auto-provisioned, sole Owner) so customers never need to be granted membership anywhere just to use Aggre. Team orgs are for multi-member organizations -- including Orbbit's own internal staff org -- and are created explicitly. Enterprise is a billing `Tier` on a Team org, not a separate kind, since org shape and billing tier are independent axes.
`name`required	`string`
`slug`required	`string`
`tier`required	`Tier`

Errors: 400, 401, 403

List organization members

GET/v1/orgs/{id}/members

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Organization ID

200 response · OrganizationMember[]

Errors: 401, 403, 404

Add organization member

POST/v1/orgs/{id}/members

Parameters
Name	In	Type	Notes
`id`required	path	`uuid`	Organization ID

Request body · AddOrganizationMemberRequest
Name	Type	Notes
`role`required	`Role`
`user_id`required	`uuid`

200 response · OrganizationMember

200 response fields
Name	Type	Notes
`created_at`required	`string`
`org_id`required	`uuid`
`role`required	`Role`
`user_id`required	`uuid`

Errors: 400, 401, 403, 404

List users

GET/v1/users

200 response · User[]

Errors: 401, 403

Create user

POST/v1/users

Request body · CreateUserRequest
Name	Type	Notes
`email`required	`string`
`name`required	`string`

200 response · User

200 response fields
Name	Type	Notes
`created_at`required	`string`
`email`required	`string`
`id`required	`uuid`
`name`required	`string`

Errors: 400, 401, 403

System

Liveness and readiness, no key needed.

Health

GET/health

200 response · HealthResponse

200 response fields
Name	Type	Notes
`service`required	`string`
`status`required	`string`

Ready

GET/ready

200 response · ReadyResponse

200 response fields
Name	Type	Notes
`database`required	`string`
`reranker`required	`string`
`service`required	`string`
`status`required	`string`

Errors: 503

Name	Type	Notes
`clear_parent`	`boolean`	Move the category to the top level, clearing parent_id. Distinct from parent_id being absent (leave the parent unchanged) -- ordinary JSON can't tell "omitted" from "explicitly null" without extra deserializer plumbing, so this is a plain flag instead.
`description`	`string \| null`
`name`	`string \| null`
`parent_id`	`uuid \| null`

Name	Type	Notes
`added_at`required	`string`
`category_id`required	`uuid`
`dataset_id`required	`uuid`

Use the data

MCP over HTTP

MCP call

List MCP tools

Search and export

Export records

Get record

Search

Catalog

Get catalog

Select catalog dataset

Deselect catalog dataset

Datasets

List datasets

Create dataset

Get customer dataset stats

Get dataset

Update dataset

List records

Count records

Republish dataset

List dataset versions

Your account

API keys

List API keys

Create API key

Revoke API key

Usage

List usage events

Billing

Create credit entry

Create invoice

Stripe webhook

Upsert billing subscription

Billing summary

X402 quote

X402 settle

Bring your own data

Sources

List sources

Create source

Get source

Update source

Enqueue source

Ingest source

Preview source

Same fire-and-poll shape as run_job (see the comment there) -- a source with a large enough backlog can take longer to fetch and ingest than a proxy's request timeout allows, so this starts the job and returns immediately rather than blocking the response on the whole run.

Jobs

List error logs

List jobs

Create job

Get job

Claim job

Raw archives

List raw archives

Platform staff

Categories

List categories

Create category

Get category

Update category

Delete category

List category datasets

Add category dataset

Remove category dataset

Grants

List subscriptions

Create subscription

Delete subscription

Administration

List orgs

Get org

Update org

Add org member

Status

List users

List audit logs

legal-api runs on an internal-only address (not reachable from the browser), so the admin console goes through this proxy rather than calling it directly.

Put legal API judicial credentials

Delete legal API judicial credentials