Meta

Datasets, jurisdictions, currencies, the source register and data freshness.

Operation	Summary
`GET /health`	Check that the service is running
`GET /v1/currencies`	List the currencies
`GET /v1/jurisdictions`	List the jurisdictions
`GET /v1/jurisdictions/{code}`	Get a jurisdiction
`GET /v1/meta/datasets`	List the datasets and their versions
`GET /v1/sources`	List the source authorities
`GET /v1/sources/register`	Get the source register
`GET /v1/sources/status`	Check whether the data is current

`GET /health`

Check that the service is running

Liveness check for monitors and load balancers. Returns {"status": "ok"} with status 200 whenever the process answers; it needs no API key and does not read the dataset or the stores.


Authentication	none (public)
Operation id	`healthz_health_get`

Example request

curl "$DATAVNEXT_URL/health" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	map of string

Example response (shape)

{
  "status": "ok"
}

`GET /v1/currencies`

List the currencies

The ISO 4217 currencies the dataset knows, with their numeric code and minor units.

minor_units is the number of decimals the API rounds converted amounts to (2 for EUR, 0 for JPY).


Authentication	an API key, where the server requires one
Operation id	`currencies_v1_currencies_get`

Parameters

In	Name	Type	Required	Description
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/currencies" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_list_Currency__`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": [
    {
      "code": "string",
      "numeric": "string",
      "name": "string",
      "minor_units": 1
    }
  ],
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/jurisdictions`

List the jurisdictions

Countries and subdivisions the dataset knows, with their currency and tax system.

The code is what the other endpoints take as jurisdiction: ISO 3166-1 alpha-2 for a country, ISO 3166-2 for a subdivision (US-CA). groups lists memberships such as EU, parent the country of a subdivision and indirect_tax_system whether it levies VAT, GST, sales tax or none. The filters narrow the list; an unknown value returns an empty list.


Authentication	an API key, where the server requires one
Operation id	`jurisdictions_v1_jurisdictions_get`

Parameters

In	Name	Type	Description
query	`group`	string or null	Only members of this group, case-insensitive: 'EU' or 'EEA'. Default: all.
query	`parent`	string or null	Only subdivisions of this country, ISO 3166 alpha-2, case-insensitive, e.g. 'CA' for its provinces. Default: all.
query	`dataset_version`	string or null	Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/jurisdictions" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_list_Jurisdiction__`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": [
    {
      "code": "string",
      "name": "string",
      "level": "country",
      "parent": "string",
      "currency": "string",
      "groups": [
        "string"
      ],
      "indirect_tax_system": "none"
    }
  ],
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/jurisdictions/{code}`

Get a jurisdiction

One jurisdiction: name, level, parent, currency, group memberships and tax system.

404 for an unknown code.


Authentication	an API key, where the server requires one
Operation id	`jurisdiction_v1_jurisdictions__code__get`

Parameters

In	Name	Type	Required	Description
path	`code`	string	yes	ISO 3166 code of a country or subdivision, case-insensitive, e.g. 'DE' or 'CA-ON'.
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/jurisdictions/DE" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_Jurisdiction_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "code": "string",
    "name": "string",
    "level": "country",
    "parent": "string",
    "currency": "string",
    "groups": [
      "string"
    ],
    "indirect_tax_system": "none"
  },
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/meta/datasets`

List the datasets and their versions

The datasets behind the API, how many records each has and how fresh the series are.

data.dataset_version identifies the bundle that answered; it is also in every response's meta.dataset_version and can be passed back as the dataset_version query parameter to reproduce an answer later. Curated datasets (tax rates, decision tables, calendars, ...) have a record count; market time series (fx.ecb, rates.sofr, ...) have latest, their newest stored date. For a judgement of freshness use /v1/sources/status.


Authentication	an API key, where the server requires one
Operation id	`datasets_v1_meta_datasets_get`

Parameters

In	Name	Type	Required	Description
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/meta/datasets" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_DatasetsInfo_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "dataset_version": "3f2a9c1b7d4e",
    "built_at": "2026-10-01T06:00:00Z",
    "datasets": [
      {
        "id": "jurisdictions",
        "kind": "curated",
        "records": 52
      },
      {
        "id": "tax.indirect.rates",
        "kind": "curated",
        "records": 415
      },
      {
        "id": "fx.ecb",
        "kind": "timeseries",
        "latest": "2026-09-30"
      }
    ]
  },
  "meta": {
    "dataset_version": "3f2a9c1b7d4e",
    "sources": [],
    "notes": []
  }
}

`GET /v1/sources`

List the source authorities

The source registry: the one authority each domain is collected from, per jurisdiction.

Each authority lists its official web hosts, the domains it provides, how (feed pulled by a connector or curated by hand), how often and where the data is published. With domain and jurisdiction the answer is the single primary authority (or an empty list).


Authentication	an API key, where the server requires one
Operation id	`sources_v1_sources_get`

Parameters

In	Name	Type	Description
query	`domain`	`"accounting_standards"` \| `"benchmark_rates"` \| `"calendars"` \| `"e_invoicing"` \| `"fixed_assets"` \| `"fx_reference"` \| `"indirect_tax"` \| `"legislation"` \| `"recapitulative_statements"` \| `"tax_fx"` \| `"tax_returns"` or null	Only authorities that provide this domain: 'indirect_tax', 'tax_fx', 'fx_reference', 'benchmark_rates', 'calendars', 'fixed_assets', 'e_invoicing', 'legislation', 'accounting_standards', 'tax_returns' or 'recapitulative_statements'. Default: all.
query	`jurisdiction`	string or null	Only the authority that is primary here (or for a parent). Requires `domain`; without it the call gives 422. ISO 3166 code, case-insensitive.
query	`dataset_version`	string or null	Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/sources" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_list_SourceAuthority__`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "jurisdiction": "string",
      "homepage": "string",
      "hosts": [
        "string"
      ],
      "licence": "string",
      "provides": [
        null
      ]
    }
  ],
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/sources/register`

Get the source register

Every data point we collect: its authority, how and how often it arrives, the records it produces and which endpoints and ERP features use it (docs/source-register.md).

data.domains describes each kind of data and the endpoints that serve it, data.data_points has one row per authority and domain, and data.authorities lists the publishers. It is the same content as the generated register in the repository.


Authentication	an API key, where the server requires one
Operation id	`source_register_v1_sources_register_get`

Parameters

In	Name	Type	Required	Description
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/sources/register" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_Register_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "dataset_version": "string",
    "domains": [
      {
        "domain": null,
        "title": null,
        "purpose": null,
        "api": null,
        "erp": null,
        "authorities": null
      }
    ],
    "data_points": [
      {
        "authority": null,
        "domain": null,
        "title": null,
        "jurisdictions": null,
        "method": null,
        "cadence": null,
        "url": null,
        "notes": null,
        "feeds": null,
        "records": null
      }
    ],
    "authorities": [
      {
        "id": null,
        "name": null,
        "jurisdiction": null,
        "homepage": null,
        "hosts": null,
        "licence": null
      }
    ]
  },
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

`GET /v1/sources/status`

Check whether the data is current

Whether each data point of the register is current: per ingest feed the newest stored date, its freshness rule and the connector's last run; per curated data point the records, the oldest and newest verification dates and the source watcher's coverage. States: ok, stale, no_data, error (see docs/data-sources.md).

meta.as_of is the date freshness was judged on. A data point is error when the last ingest run failed, no_data when nothing is stored, stale when older than its rule allows and ok otherwise.


Authentication	an API key, where the server requires one
Operation id	`source_status_v1_sources_status_get`

Parameters

In	Name	Type	Required	Description
query	`as_of`	string (date) or null		Judge freshness on this date (ISO 8601, e.g. 2026-10-01). Defaults to today.
query	`dataset_version`	string or null		Pin the response to an archived dataset version (git SHA). Defaults to the current version. Also accepted as the X-Dataset-Version header. The version that answered is in meta.dataset_version; an archived version that does not exist gives 404.

Example request

curl "$DATAVNEXT_URL/v1/sources/status" \
  -H "X-API-Key: $DATAVNEXT_KEY"

Responses

Status	Meaning	Body
200	OK	`Envelope_SourcesStatus_`
401	Missing or invalid API key.	`Error`
404	Nothing found for the identifier, or the pinned `dataset_version` is not archived.	`Error`
422	The request is invalid: `{"detail": "…"}` for a rule the service checks, or FastAPI's `{"detail": [{"loc", "msg", "type"}]}` for a malformed parameter or body.	`HTTPValidationError`

Example response (shape)

{
  "data": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "counts": {},
    "data_points": [
      {
        "authority": null,
        "domain": null,
        "jurisdictions": null,
        "method": null,
        "state": null,
        "detail": null,
        "feeds": null,
        "citations": null
      }
    ],
    "watcher": {
      "available": true,
      "run_date": null,
      "dry_run": null,
      "checked": null,
      "unreachable": null,
      "changed": null,
      "note": null
    }
  },
  "meta": {
    "dataset_version": "string",
    "as_of": "2026-09-21",
    "known_at": "2026-09-21",
    "sources": [
      {
        "authority": null,
        "url": null,
        "reference": null,
        "verified_at": null,
        "kind": null
      }
    ],
    "notes": [
      "string"
    ]
  }
}

Schemas

`AuthorityEntry`

Field	Type	Required
`id`	string	yes
`name`	string	yes
`jurisdiction`	string	yes
`homepage`	string	yes
`hosts`	array of string	yes
`licence`	string or null

`CitationStatus`

Field	Type	Required	Description
`records`	integer	yes
`cited_urls`	integer	yes
`watched_urls`	integer	yes	Cited URLs the source watcher fetches each week.
`oldest_verified_at`	string (date) or null
`newest_verified_at`	string (date) or null
`unreachable_urls`	array of string		Cited URLs the latest watcher run could not fetch.
`changed_urls`	array of string		Cited URLs whose content changed in the latest run.

`Currency`

Field	Type	Required	Description
`code`	string	yes	ISO 4217 alphabetic code, e.g. 'CHF'. (pattern `^[A-Z]{3}$`)
`numeric`	string	yes	ISO 4217 numeric code, e.g. '756'. (pattern `^[0-9]{3}$`)
`name`	string	yes	English name, e.g. 'Swiss franc'.
`minor_units`	integer	yes	Decimals of the smallest unit (2 for EUR, 0 for JPY); amounts round to it. (min 0; max 4)

`DataPoint`

One kind of data one authority is the primary source for.

Field	Type	Required
`authority`	string	yes
`domain`	string	yes
`title`	string	yes
`jurisdictions`	array of string	yes
`method`	string	yes
`cadence`	string or null
`url`	string or null
`notes`	string or null
`feeds`	array of `Feed`
`records`	array of `Records`

`DataPointStatus`

Field	Type	Required
`authority`	string	yes
`domain`	string	yes
`jurisdictions`	array of string	yes
`method`	string	yes
`state`	`"error"` \| `"no_data"` \| `"ok"` \| `"stale"`	yes
`detail`	string	yes
`feeds`	array of `FeedStatus`	yes
`citations`	`CitationStatus`	yes

`Dataset`

Field	Type	Required	Description
`id`	string	yes	Dataset id, e.g. 'tax.indirect.rates', 'fx.ecb' or 'rates.sofr'.
`kind`	string	yes	'curated': reviewed YAML records in the bundle; 'timeseries': market data ingested from a publisher's feed.
`records`	integer or null		Number of records of a curated dataset; null for time series.
`latest`	string (date) or null		Newest stored date of a time series; null for curated datasets or when nothing is stored.

`DatasetsInfo`

Field	Type	Required	Description
`dataset_version`	string	yes	Identifier of the dataset bundle that answered (the commit it was built from); pass it as `dataset_version` to pin later calls to it.
`built_at`	string (date-time) or null	yes	When the bundle was built (ISO 8601 UTC); null for a local build.
`datasets`	array of `Dataset`	yes	Every dataset the API serves.

`DomainEntry`

Field	Type	Required
`domain`	string	yes
`title`	string	yes
`purpose`	string	yes
`api`	array of string	yes
`erp`	array of string	yes
`authorities`	array of string	yes

`Envelope_DatasetsInfo_`

Field	Type	Required	Description
`data`	`DatasetsInfo`	yes
`meta`	`Meta`	yes

`Envelope_Jurisdiction_`

Field	Type	Required	Description
`data`	`Jurisdiction`	yes
`meta`	`Meta`	yes

`Envelope_Register_`

Field	Type	Required	Description
`data`	`Register`	yes
`meta`	`Meta`	yes

`Envelope_SourcesStatus_`

Field	Type	Required	Description
`data`	`SourcesStatus`	yes
`meta`	`Meta`	yes

`Envelope_list_Currency__`

Field	Type	Required	Description
`data`	array of `Currency`	yes
`meta`	`Meta`	yes

`Envelope_list_Jurisdiction__`

Field	Type	Required	Description
`data`	array of `Jurisdiction`	yes
`meta`	`Meta`	yes

`Envelope_list_SourceAuthority__`

Field	Type	Required	Description
`data`	array of `SourceAuthority`	yes
`meta`	`Meta`	yes

`Feed`

Field	Type	Required	Description
`id`	string	yes
`kind`	string	yes	'ingest' (time series) or 'legislation' (watcher).
`description`	string	yes

`FeedStatus`

Field	Type	Required	Description
`connector`	string	yes
`description`	string	yes
`kind`	string	yes
`series`	array of `SeriesLatest`	yes
`latest`	string (date) or null	yes	The oldest of the series' newest dates.
`age_days`	integer or null	yes	Days from 'latest' to as_of (negative when dated ahead).
`freshness`	`FreshnessRule`	yes
`state`	`"error"` \| `"no_data"` \| `"ok"` \| `"stale"`	yes
`detail`	string	yes
`last_run`	`IngestRun` or null

`FreshnessRule`

Field	Type	Required
`max_age_days`	integer or null
`min_horizon_days`	integer or null
`rule`	string	yes

`IngestRun`

The last run of one ingest connector, as the runner recorded it in the store.

Field	Type	Required	Description
`connector`	string	yes	Connector id, e.g. 'ecb-fx'.
`started_at`	string (date-time)	yes	When the run started (UTC).
`finished_at`	string (date-time)	yes	When the run ended (UTC).
`ok`	boolean	yes	True if the run finished without error.
`window_start`	string (date) or null		First date the run asked the publisher for.
`window_end`	string (date) or null		Last date the run asked the publisher for.
`fetched`	integer		Records fetched from the publisher. (default `0`)
`stored`	integer		Records written to the store. (default `0`)
`warehoused`	integer		Records also written to the warehouse. (default `0`)
`error`	string or null		Why the run failed (truncated).
`last_success_at`	string (date-time) or null		When the connector last ran without error (this run or before).

`Jurisdiction`

Field	Type	Required	Description
`code`	string	yes	ISO 3166-1 alpha-2 for countries, ISO 3166-2 for subdivisions (e.g. US-CA). (pattern `^[A-Z]{2}(-[A-Z0-9]{1,3})?$`)
`name`	string	yes	English name, e.g. 'Germany'.
`level`	`"country"` \| `"subdivision"`	yes	'country' or 'subdivision' (state, province).
`parent`	string or null		Code of the country a subdivision belongs to; null for countries.
`currency`	string or null		ISO 4217 code of the currency used, e.g. 'EUR'. (pattern `^[A-Z]{3}$`)
`groups`	array of string		Memberships relevant to tax rules, e.g. 'EU'.
`indirect_tax_system`	`"consumption_tax"` \| `"gst"` \| `"none"` \| `"sales_tax"` \| `"vat"`		vat, gst, sales_tax, consumption_tax, or none if no indirect tax is levied. (default `"none"`)

`Provision`

One kind of data an authority is the primary source for.

Field	Type	Required	Description
`domain`	`"accounting_standards"` \| `"benchmark_rates"` \| `"calendars"` \| `"e_invoicing"` \| `"fixed_assets"` \| `"fx_reference"` \| `"indirect_tax"` \| `"legislation"` \| `"recapitulative_statements"` \| `"tax_fx"` \| `"tax_returns"`	yes	The kind of data the authority is the source for.
`jurisdictions`	array of string	yes	Jurisdiction codes, a group such as 'EU', or 'global'. (min items 1)
`method`	`"curated"` \| `"feed"`	yes	'feed': pulled automatically by an ingest connector; 'curated': maintained as YAML in data/ and checked by the source watcher.
`connectors`	array of string		Ingest connector ids (method 'feed').
`feeds`	array of string		Legislation feeds (domain 'legislation') that the source watcher reads to discover new acts no record cites yet; ids from src/datavnext/watch/legislation.py.
`cadence`	string or null		e.g. 'daily', 'monthly'.
`url`	string (uri) or null		Where the data is published. (min length 1)
`notes`	string or null		Remarks on coverage or method.

`Records`

Field	Type	Required	Description
`dataset`	string	yes
`records`	integer	yes
`series`	integer or null		Distinct series, where versioned.

`Register`

Field	Type	Required
`dataset_version`	string	yes
`domains`	array of `DomainEntry`	yes
`data_points`	array of `DataPoint`	yes
`authorities`	array of `AuthorityEntry`	yes

`SeriesLatest`

Field	Type	Required	Description
`id`	string	yes	Store key: FX source, benchmark id or calendar id.
`kind`	string	yes	'fx', 'rate' or 'calendar'.
`latest`	string (date) or null	yes	Newest stored date (newest holiday).

`SourceAuthority`

Field	Type	Required	Description
`id`	string	yes	e.g. 'ch-estv'. (pattern `^[a-z0-9-]+$`)
`name`	string	yes	Official name of the publisher.
`jurisdiction`	string	yes	Home jurisdiction, or 'global'.
`homepage`	string (uri)	yes	The authority's website. (min length 1)
`hosts`	array of string	yes	Official web hosts. A record sourced from this authority must cite a URL on one of them (subdomains included). (min items 1)
`licence`	string or null		Terms of reuse, if notable.
`provides`	array of `Provision`	yes	The kinds of data this authority is the primary source for. (min items 1)

`SourcesStatus`

Field	Type	Required	Description
`dataset_version`	string	yes
`as_of`	string (date)	yes
`counts`	map of integer	yes	Data points per state.
`data_points`	array of `DataPointStatus`	yes
`watcher`	`WatcherStatus`	yes

`WatcherStatus`

Field	Type	Required
`available`	boolean	yes
`run_date`	string (date) or null
`dry_run`	boolean or null
`checked`	integer or null
`unreachable`	integer or null
`changed`	integer or null
`note`	string or null