Foretak.dev Meta API

openapi: 3.2.0
info:
  title: Foretak Dev Meta API
  version: 0.4.2
  contact:
    url: https://github.com/foretak/registry-mcp
  license:
    name: MIT
  description: 'Operations tagged meta across 2 of this provider''s published API definitions: foretak-dev-openapi.json, foretak-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
tags:
- name: Meta
  description: Discover what this service supports and whether it is up.
paths:
  /health:
    get:
      tags:
      - Meta
      summary: Liveness probe
      description: 'Liveness check for monitoring — returns 200 with the running version and the currently supported country codes whenever the process is up. Not part of the data API: it does no upstream call and has no error mode. Do not call it in a polling loop faster than your monitoring actually needs.'
      operationId: health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: ok
                version: 0.4.2
                countries:
                - 'NO'
  /v1/countries:
    get:
      tags:
      - Meta
      summary: List supported countries and registries
      description: Discover which national business registries this service can answer for right now, and what each one's identifier looks like — for Norway, an organisasjonsnummer (orgnr) looked up in Enhetsregisteret (Brønnøysundregistrene, brreg). Call this before your first lookup in a country you have not used here before, or whenever a user names a country you are unsure is supported. Never hard-code this list in your own code — it grows as country modules are added, with no change to any other endpoint's shape. A 500 here means a bug on our side; retry once, this call has no other error mode.
      operationId: get_countries_v1_countries_get
      parameters:
      - name: src
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Attribution tag for the channel this call came from — set to whichever value (if any) is on the install line you copied this URL from, e.g. `readme`, `llms`, `docs`, `plugin`, `article`. Free text, entirely optional: lower-cased and reduced to `[a-z0-9_-]` (32 characters max) before it is stored, and it is never required to call this API.'
          title: Src
        description: 'Attribution tag for the channel this call came from — set to whichever value (if any) is on the install line you copied this URL from, e.g. `readme`, `llms`, `docs`, `plugin`, `article`. Free text, entirely optional: lower-cased and reduced to `[a-z0-9_-]` (32 characters max) before it is stored, and it is never required to call this API.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountriesResponse'
              example:
                countries:
                - country: GB
                  registry: companies-house
                  name: Companies House (United Kingdom)
                  id_scheme: company number
                  id_example: 00445790
                  id_description: 'A UK company registration number (CRN): 8 characters, either 8 digits or a two-letter prefix and 6 digits. Shorter numbers are zero-padded, so 445790 is written 00445790. There is no check digit.'
                  source_url: https://api.company-information.service.gov.uk
                  license: Crown copyright — Companies House public register, free to re-use
                  is_stub: false
                  requires_api_key: true
                  api_key_env: COMPANIES_HOUSE_API_KEY
                - country: 'NO'
                  registry: brreg
                  name: Enhetsregisteret (Brønnøysundregistrene)
                  id_scheme: organisasjonsnummer
                  id_example: '923609016'
                  id_description: 'A Norwegian organisasjonsnummer (orgnr): nine digits, the ninth a MOD11 check digit. Written ''923 609 016'' or ''923609016''; a VAT number adds ''MVA''.'
                  source_url: https://data.brreg.no/enhetsregisteret/api
                  license: NLOD 2.0
                  is_stub: false
                  requires_api_key: false
                - country: SE
                  registry: bolagsverket
                  name: Bolagsverket (Sweden)
                  id_scheme: organisationsnummer
                  id_example: '5560160680'
                  id_description: 'A Swedish organisationsnummer: ten digits, written 556016-0680, with a check digit. A sole trader is looked up by a twelve-digit personnummer instead (YYYYMMDDNNNN), and one such number can carry several registered businesses.'
                  source_url: https://gw.api.bolagsverket.se/vardefulla-datamangder/v1
                  license: Free re-use (Bolagsverket/SCB high-value datasets, EU Open Data Directive) — the publisher names no licence
                  is_stub: false
                  requires_api_key: true
                  api_key_env: BOLAGSVERKET_CLIENT_ID
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
          default: ok
        version:
          type: string
          title: Version
        countries:
          items:
            type: string
          type: array
          title: Countries
      type: object
      required:
      - version
      - countries
      title: HealthResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CountryInfo:
      properties:
        country:
          type: string
          title: Country
          description: ISO-3166-1 alpha-2, upper-case, e.g. 'NO'.
        registry:
          type: string
          title: Registry
          description: Registry slug, e.g. 'brreg'.
        name:
          type: string
          title: Name
          description: Human-readable register name.
        id_scheme:
          type: string
          title: Id Scheme
          description: What the national identifier is called locally, e.g. 'organisasjonsnummer'.
        id_example:
          type: string
          title: Id Example
          description: A real, valid identifier the caller can use to smoke-test the service.
        id_description:
          type: string
          title: Id Description
          description: One sentence describing the identifier's format.
        source_url:
          type: string
          title: Source Url
          description: Base URL of the upstream registry API, for citation.
        license:
          type: string
          title: License
          description: Licence of the upstream data, e.g. 'NLOD 2.0'.
        is_stub:
          type: boolean
          title: Is Stub
          description: True for example/template modules, which are hidden from the public list unless stubs are explicitly requested.
          default: false
        requires_api_key:
          type: boolean
          title: Requires Api Key
          description: True when this registry's upstream API needs a credential the operator must supply. A self-hosted deployment that has not set it gets upstream_error on every call to this country (DECISIONS.md D-017).
          default: false
        api_key_env:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key Env
          description: Name of the environment variable holding that credential, e.g. 'COMPANIES_HOUSE_API_KEY'. None when no key is needed. Never the key itself.
        supported_includes:
          items:
            type: string
          type: array
          title: Supported Includes
          description: Attachment names this registry declares — the closed set of valid values for `include=[…]` on `lookup_company`, sorted. Empty when this registry offers no attachments today. Lets an agent discover what more it can ask for before it asks (DECISIONS.md D-042(d)); an `include` value outside this list raises `bad_request` naming this same set, never a silently empty block.
      additionalProperties: false
      type: object
      required:
      - country
      - registry
      - name
      - id_scheme
      - id_example
      - id_description
      - source_url
      - license
      title: CountryInfo
      description: 'One supported country/registry pair, as returned by the discovery operation.


        Built by ``Registry.country_info()`` from the class attributes of a

        :class:`~registry_mcp.core.registry.Registry` subclass — the same nine

        values ``Registry.describe()`` has always emitted, now with a type

        (``DECISIONS.md`` D-012).


        This is the country-neutral half of the contract even though its *values*

        name a country: it carries no report data, so unlike every other returned

        model it is a row *about* a registry rather than a document *from* one.'
    CountriesResponse:
      properties:
        countries:
          items:
            $ref: '#/components/schemas/CountryInfo'
          type: array
          title: Countries
          description: One row per registry that can answer right now, sorted by country code.
      additionalProperties: false
      type: object
      title: CountriesResponse
      description: 'The answer to "which countries can you answer for?".


        The only shape the discovery operation returns, on both surfaces

        (``DECISIONS.md`` D-012): REST ``GET /v1/countries`` and the MCP tool

        ``list_countries``. Before D-012 each surface re-derived this envelope from

        ``Registry.describe()`` on its own, which is how the two could have drifted

        — REST validated the dict through a private model that silently *dropped* an

        unrecognised key while MCP passed the raw dict through and *kept* it.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
x-refined-from:
- foretak-dev-openapi.json
- foretak-dev-openapi.yml