Developers

An API your app can cite.

Every response is wrapped in a provenance envelope — source reference, license class and observation time — so what your product or agent returns to a user is always traceable. Two surfaces, one key.

Request an API key See the endpoints

200 OK · application/json

{
  "data": [
    { "dataco_id": "DC4C096C…",
      "line_item": "revenue",
      "value_reported": 152686973000,
      "currency_reported": "NGN",
      "source_ref": "S009:NASCON-FS.pdf#p12",
      "license_class": "S009" }
  ],
  "_license": "License-clean; no natural-person data.",
  "count": 1
}

Base URLs

Two surfaces, one key.

Surface	URL
REST API	`https://dataco-api.northtide.workers.dev`
MCP server	`https://dataco-mcp.northtide.workers.dev/mcp`

These are the current hosted endpoints. A branded custom domain (api.certvas.com) is available to Professional-tier customers.

Authentication

One key, tier-scoped.

Every endpoint except /health and /openapi.json requires an API key, passed as a header. Request one from pricing.

x-api-key: your-key-here

Keys are tier-scoped (sample / starter / professional) and per-minute rate-limited. The same key authenticates the MCP server.

No account? Use the public sandbox key. cv_sandbox_public is a real sample-tier key — same endpoints, same real data, same caps. There is no separate sandbox environment, because one that answers differently from production teaches you the wrong thing and then fails on your first real call.

curl -s -H "x-api-key: cv_sandbox_public" "https://dataco-api.northtide.workers.dev/v1/tenders?country=ZA&limit=5"

Reference

Endpoints.

The full machine-readable description is published as OpenAPI 3.1 at certvas.com/openapi.json — import it into Postman, Swagger UI or an SDK generator. It is generated from the same source as this page and gated in CI against the routes the Worker actually serves, in both directions, so a documented endpoint that 404s fails the build rather than reaching you.

Method & path	Returns
`GET /health`	Liveness check (no key).
`GET /v1/entities/{dataco_id}`	Canonical entity (name, jurisdiction, license).
`GET /v1/fundamentals/{dataco_id}`	Point-in-time fundamentals. Optional `?as_of=` & `?period_type=`.
`GET /v1/tenders?country=ZA`	Public tenders. Optional `?from=`, `?limit=` & `?cursor=` (keyset paging — pass back `next_cursor`).
`GET /v1/macro?country=NGA&indicator=…`	Macro indicators. Optional `?from=` (year) & `?limit=`.
`GET /v1/tender-parties?country=ZA`	Tender buyers/suppliers resolved to canonical entities.
`GET /v1/quality-metrics/{sku}`	Measured coverage/freshness (`af-fund`, `af-tender`, `af-macro`).
`GET /v1/export`	Bulk-download manifest: open Parquet panels (direct URLs, no key) and licensed SKUs.
`GET /v1/status`	Dependency check — touches D1 and KV, unlike `/health` (no key). Status page.
`GET /openapi.json`	OpenAPI description (no key).

Conventions

Paging, versioning, deprecation.

Pagination is keyset, not offset: pass the opaque next_cursor back verbatim, and null means the last page. Every response carries X-Certvas-API-Version. Anything on its way out carries RFC 8594 Deprecation and Sunset headers with at least 180 days’ notice and a named successor — nothing is deprecated today.

Working at scale? The published signal panels are Parquet over HTTPS, CC-BY, readable in place by DuckDB or polars with no key. There is also a dbt source package.

Example

Fetch NASCON’s fundamentals.

curl

curl -H "x-api-key: your-key" \
  https://dataco-api.northtide.workers.dev/v1/fundamentals/DC4C096C…

Every row carries its provenance, and the response is wrapped with a license notice — see the envelope at the top of this page.

For AI agents

MCP — tools that cite themselves.

The MCP server exposes the same gold data as agent-callable tools — search_entities, get_entity, get_fundamentals, search_tenders, get_macro, get_resolved_parties, get_quality_metrics — each returning values with their source and license, so your model can quote them back to a user. Point any MCP client at the server URL with the same x-api-key header.

https://dataco-mcp.northtide.workers.dev/mcp (header: x-api-key)