{
  "openapi": "3.1.0",
  "info": {
    "title": "NACEBridge REST API",
    "version": "1.0.0",
    "description": "Cross-border European activity classification. Maps EU NACE Rev 2.1 down to the 5th-digit national subclasses used by 27+ countries. See also the MCP server at https://nacebridge.eu/mcp and llms.txt at https://nacebridge.eu/llms.txt.",
    "termsOfService": "https://nacebridge.eu/pricing",
    "contact": {
      "name": "TΣKSOMΛ Technologies",
      "url": "https://tech.teksoma.com",
      "email": "api@nacebridge.eu"
    },
    "license": {
      "name": "Derivative code CC BY 4.0; NACE metadata © EU, Commission Decision 2011/833/EU",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://nacebridge.eu",
      "description": "Production"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Issued at https://nacebridge.eu/auth (free tier, no card required)."
      }
    },
    "schemas": {
      "Country": {
        "type": "object",
        "properties": {
          "iso": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2
          },
          "name": {
            "type": "string"
          },
          "system": {
            "type": "string",
            "description": "Local classification name (e.g. CAE Rev 4, NAF, WZ, SBI)."
          }
        }
      },
      "NaceClass": {
        "type": "object",
        "properties": {
          "class_code": {
            "type": "string",
            "example": "62.01"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "NationalSubclass": {
        "type": "object",
        "properties": {
          "country_iso": {
            "type": "string"
          },
          "local_subclass_code": {
            "type": "string"
          },
          "local_title": {
            "type": "string"
          },
          "local_description": {
            "type": "string"
          },
          "class_digits": {
            "type": "string",
            "description": "The 4-digit NACE class this subclass anchors on."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/search": {
      "get": {
        "operationId": "search",
        "summary": "Free-text search across EU classes and national subclasses",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "tier": {
                      "type": "string"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "eu": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NaceClass"
                          }
                        },
                        "national": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/NationalSubclass"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api/v1/decode": {
      "get": {
        "operationId": "decode",
        "summary": "Decode a national subclass into the full EU NACE hierarchy",
        "parameters": [
          {
            "name": "country_iso",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "404": {
            "description": "Unknown code"
          }
        }
      }
    },
    "/api/v1/cousins": {
      "get": {
        "operationId": "cousins",
        "summary": "Equivalent subclasses in every EU country for a given local code",
        "parameters": [
          {
            "name": "country_iso",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/convert": {
      "get": {
        "operationId": "convert",
        "summary": "Directed conversion between two country's local codes",
        "parameters": [
          {
            "name": "from_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to_country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/grid": {
      "get": {
        "operationId": "grid",
        "summary": "Multi-country pivot of EU classes vs national subclasses",
        "parameters": [
          {
            "name": "division",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          },
          {
            "name": "countries",
            "in": "query",
            "schema": {
              "type": "string",
              "description": "Comma-separated ISO codes"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/api/v1/countries": {
      "get": {
        "operationId": "listCountries",
        "summary": "ISO codes currently loaded",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Country"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-mcp-server": "https://nacebridge.eu/mcp",
  "x-llms-txt": "https://nacebridge.eu/llms.txt",
  "x-handbook-manifest": "https://nacebridge.eu/handbook.json"
}