Developers · Reference · v1 live

API reference

https://api.data.co/v1 — the live v1 surface. Create a key at app.data.co and call any endpoint below; tell us what is missing.

Quickstart Authentication

Conventions

Ground rules

Topic	Rule
Transport	HTTPS only. JSON request and response bodies, UTF-8.
Versioning	Major version in the path (/v1). Additive changes within a version; breaking changes get a new version.
Authentication	Authorization: Bearer dc_live_<prefix>_<secret>. Scopes are checked per endpoint.
Request IDs	Every response has a server-generated X-Request-Id header and meta.request_id. Send your own X-Request-Id to correlate; it is echoed as X-Client-Request-Id and meta.client_request_id, and never used for metering.
Field naming	snake_case in query parameters; record objects keep the connector's field names.
Dates	ISO 8601: YYYY-MM-DD for dates, full timestamps in UTC.
Provenance	Every record carries a provenance object. AI enrichment is a separate block with isDerived: true.
Demo data	Live records return demo: false. Records with demo: true are synthetic and never billed.

Envelope

Response envelope

Every response has the same three keys: data, meta and error. Single objects return data as an object; lists return an array with meta.next_cursor. meta.total is null when the provider does not report it — it is never estimated.

200 OKIllustrative

{
  "data": [ { …record… } ],
  "meta": {
    "request_id": "req_…",
    "api_version": "v1",
    "demo": false,
    "next_cursor": "eyJ…" | null,
    "total": 42 | null,
    "warnings": [ "…provider caveat…" ]
  },
  "error": null
}

Pagination

Cursor pagination

Pass limit (1–100, default 20). When next_cursor is non-null, send it back as cursor to get the next page. Cursors are opaque and tied to the query; don't construct them. There is no offset parameter.

terminalIllustrative

curl -G https://api.data.co/v1/legal/search \
  -H "Authorization: Bearer $DATACO_API_KEY" \
  --data-urlencode "q=easement" \
  --data-urlencode "limit=50" \
  --data-urlencode "cursor=eyJ…"

Provider caveat: LAW.co's current search endpoint returns a randomly sampled, unpaginated set of up to 50 matches. Cursors page within that sample and a warning says so. Stable keyset pagination depends on LAW.co's proposed internal endpoint.

Errors

Error objects

Non-2xx responses return a single error object. Branch on code, not message.

errorIllustrative

{
  "data": null,
  "meta": { "request_id": "req_…", "api_version": "v1", "demo": false },
  "error": {
    "type": "rights_error",
    "code": "rights_restricted",
    "message": "Dataset 'lawco-case-summaries' 'download' access is awaiting rights confirmation from the provider.",
    "param": null,
    "request_id": "req_…"
  }
}

HTTP	type	code	When
400	`invalid_request_error`	`invalid_params`	A parameter is missing or malformed.
401	`authentication_error`	`invalid_api_key`	Key missing, malformed, expired or revoked.
403	`permission_error`	`missing_scope`	The key lacks the scope this endpoint needs.
403	`rights_error`	`rights_restricted`	The dataset's license or rights status blocks this channel (for example bulk download).
404	`not_found_error`	`not_found`	Dataset or record does not exist.
403	`permission_error`	`not_entitled`	Your plan does not include this dataset's pricing tier.
429	`rate_limit_error`	`rate_limited`	Per-key token bucket is empty; honor Retry-After.
429	`rate_limit_error`	`quota_exceeded`	Monthly plan quota (API requests, MCP calls or downloads) is used up.
501	`unsupported_error`	`unsupported_operation`	The provider cannot back this operation yet (for example citation resolution).
502	`upstream_error`	`upstream`	The provider's API failed or timed out.
503	`unavailable_error`	`not_configured`	The provider channel is not connected yet; it is not live.

Endpoints

Endpoint reference

Catalog

Endpoint	Description	Scope	Parameters	LAW.co backing
`GET /datasets`	List datasets with catalog metadata, per-channel access status and plan entitlement.	`datasets:read`	q, category, provider, tier, access, cursor, limit	Supported (catalog)
`GET /datasets/{id}`	Full dataset descriptor: sources, license, coverage, access methods, quality notes. {id} is the slug.	`datasets:read`	—	Supported (catalog)
`GET /datasets/{id}/schema`	Field list with types, nullability and derived flags.	`datasets:read`	—	Supported (catalog)
`GET /providers`	List providers.	`datasets:read`	cursor, limit	Supported (catalog)

Records

Endpoint	Description	Scope	Parameters	LAW.co backing
`GET /datasets/{id}/records`	Search one dataset's records.	`datasets:query`	q, jurisdiction, court, document_type, date_from, date_to, citation, topic, cursor, limit	Partial — opinions only (q required); upstream search is sampled (≤50), topic filter unsupported. Statute reference values not yet populated
`POST /datasets/{id}/query`	Same search with a JSON body (same fields).	`datasets:query`	JSON body: q, jurisdiction, court, document_type, date_from, date_to, citation, topic, cursor, limit	Partial — as above

Legal

Endpoint	Description	Scope	Parameters	LAW.co backing
`GET /legal/cases`	Search court opinions.	`legal:read`	q (required), jurisdiction, court, date_from, date_to, citation, cursor, limit	Partial — sampled keyword search over opinions
`GET /legal/cases/{id}`	Get an opinion: text, metadata, provenance, entitled enrichment, authorities, cited-by.	`legal:read`	—	Supported
`POST /legal/search`	Search across legal datasets (by dataset or document_type; default court opinions).	`legal:read`	JSON body: q, dataset, document_type, jurisdiction, court, date_from, date_to, citation, cursor, limit	Partial — sampled keyword search over opinions (statute reference values not yet populated)
`POST /legal/citations/resolve`	Resolve a citation string to records.	`legal:read`	JSON body: citation	Unavailable — returns 501 unsupported_operation (LAW.co has no resolver endpoint yet)
`GET /legal/jurisdictions`	List jurisdictions covered by legal datasets.	`legal:read`	—	Catalog-level only (U.S. federal, U.S. state)

Downloads & usage

Endpoint	Description	Scope	Parameters	LAW.co backing
`POST /datasets/{id}/downloads`	Request a bulk export (rights-gated); returns a single-use grant token.	`datasets:query`	JSON body: format	Unavailable — 403 rights_restricted (awaiting rights confirmation; no bulk endpoint)
`GET /usage`	Usage events for your organization.	`usage:read`	from, to, dataset, channel, cursor, limit	n/a (Data.co side)

Base URL https://api.data.co/v1. Status: live. “LAW.co backing” describes what LAW.co's API can support through Data.co's service account.

Start building with live data.

API and MCP access is live. Sign up at app.data.co, create a scoped key, or talk to us about your use case.

Get an API key Contact the marketplace team