The Data.co REST API
Versioned JSON endpoints for dataset discovery, record search and legal documents — one scoped key, cursor pagination, provenance on every record. The API is live: sign up at app.data.co, create a key and call it today.
- Base URL
- https://api.data.co/v1
- Status
- Live
- Auth
- Bearer API key (scoped)
- Pagination
- Cursor, ≤100 per page
- First provider
- LAW.co — live
Endpoint overview
Catalog
| Endpoint | Description | LAW.co backing |
|---|---|---|
GET /datasets | List datasets with catalog metadata, per-channel access status and plan entitlement. | Supported (catalog) |
GET /datasets/{id} | Full dataset descriptor: sources, license, coverage, access methods, quality notes. {id} is the slug. | Supported (catalog) |
GET /datasets/{id}/schema | Field list with types, nullability and derived flags. | Supported (catalog) |
GET /providers | List providers. | Supported (catalog) |
Records
| Endpoint | Description | LAW.co backing |
|---|---|---|
GET /datasets/{id}/records | Search one dataset's records. | 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). | Partial — as above |
Legal
| Endpoint | Description | LAW.co backing |
|---|---|---|
GET /legal/cases | Search court opinions. | Partial — sampled keyword search over opinions |
GET /legal/cases/{id} | Get an opinion: text, metadata, provenance, entitled enrichment, authorities, cited-by. | Supported |
POST /legal/search | Search across legal datasets (by dataset or document_type; default court opinions). | Partial — sampled keyword search over opinions (statute reference values not yet populated) |
POST /legal/citations/resolve | Resolve a citation string to records. | Unavailable — returns 501 unsupported_operation (LAW.co has no resolver endpoint yet) |
GET /legal/jurisdictions | List jurisdictions covered by legal datasets. | Catalog-level only (U.S. federal, U.S. state) |
Downloads & usage
| Endpoint | Description | LAW.co backing |
|---|---|---|
POST /datasets/{id}/downloads | Request a bulk export (rights-gated); returns a single-use grant token. | Unavailable — 403 rights_restricted (awaiting rights confirmation; no bulk endpoint) |
GET /usage | Usage events for your organization. | 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.
Predictable responses.
Every response has data, meta and error. meta carries the request id, paging (next_cursor, total), a demo flag and warnings for provider caveats such as sampled upstream search. Errors return a typed error object with the same request id.
{
"data": [
{
"id": "lawco:case:<id>",
"title": "<case name>",
"citations": ["<reporter cite>"],
"court": "<court>",
"date": "YYYY-MM-DD",
"provenance": { "provider": "lawco", "licenseId": "us-gov-edicts-public-domain", "isDerived": false }
}
],
"meta": {
"request_id": "req_…",
"api_version": "v1",
"demo": false,
"next_cursor": "<opaque>",
"total": null,
"warnings": ["Upstream search is sampled; results are not stable across calls."]
},
"error": null
}Illustrative · shapes from the API reference
From key to cited record
- 1
Discover
Call
GET /datasetsto list datasets with their per-channel access status and whether your plan is entitled to each one. - 2
Inspect
Call
GET /datasets/{id}/schemato see field names, types, nullability and which fields are derived. - 3
Search
Call
GET /legal/casesorPOST /legal/searchwith a query and filters; followmeta.next_cursorto page. - 4
Fetch and cite
Call
GET /legal/cases/{id}for the full opinion, provenance, entitled enrichment, authorities and cited-by.
Least privilege by default
| Scope | Grants |
|---|---|
datasets:read | Catalog, dataset descriptors, schemas and providers. |
datasets:query | Record search and download requests. |
legal:read | Legal endpoints: cases, search, jurisdictions. |
usage:read | Your organization's usage events. |
mcp:invoke | Calling MCP tools with the same key. |
curl https://api.data.co/v1/legal/cases/lawco:case:<id> \
-H "Authorization: Bearer $DATACO_API_KEY"
# 200 → data: { id, title, citations, court, date,
# body: { text, format }, provenance: { … isDerived: false },
# enrichment: { summary, holding, provenance: { isDerived: true } } | null,
# authorities: [ … ], citedBy: [ … ] }REST API FAQ
Is there an OpenAPI document?
Yes. The platform serves an OpenAPI 3.1 document for the v1 surface, which you can use to generate a client or import into an API tool.
Is there an official SDK?
Not yet; SDKs are planned. The API is plain JSON over HTTPS, so any HTTP client works.
Why does search include warnings?
Provider caveats travel with the data. LAW.co's current search samples up to 50 matches at random, so results can differ between calls, and meta.warnings says so on every affected response.
How do I know whether a record is real or demo?
Check meta.demo and the X-Dataco-Demo response header. Live LAW.co records come back with meta.demo false. Demo records are synthetic, titled with a [DEMO] prefix, and never billed; the previews on this site use them.
What happens when a channel is not live?
You get a typed error, not empty results: 503 not_configured when a provider channel is not connected, 403 rights_restricted when rights block a channel, and 501 unsupported_operation when the provider cannot back an operation.
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.