{
  "openapi": "3.1.0",
  "info": {
    "title": "OpenRegistry HTTP API",
    "version": "1.0.0",
    "description": "Live company-registry data from national registries over plain HTTPS. REST (resource-oriented) and RPC (one endpoint per tool) share one auth pipeline. Auth is optional: omit the token for anonymous access at a lower rate limit, or send a personal access token from /account. Human docs: /api."
  },
  "servers": [
    {
      "url": "https://openregistry.sophymarine.com"
    }
  ],
  "security": [
    {},
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Jurisdictions"
    },
    {
      "name": "Companies"
    },
    {
      "name": "Officers"
    },
    {
      "name": "Documents"
    },
    {
      "name": "RPC"
    }
  ],
  "paths": {
    "/api/v1/jurisdictions": {
      "get": {
        "tags": [
          "Jurisdictions"
        ],
        "operationId": "listJurisdictions",
        "summary": "Cross-country tool-support matrix.",
        "parameters": [
          {
            "name": "supports_tool",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter to countries supporting this tool."
          }
        ],
        "responses": {
          "200": {
            "description": "Tool-support matrix.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/jurisdictions/{cc}": {
      "get": {
        "tags": [
          "Jurisdictions"
        ],
        "operationId": "getJurisdiction",
        "summary": "Schema, ID format and quirks for one country.",
        "parameters": [
          {
            "name": "cc",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, CA-BC)."
          }
        ],
        "responses": {
          "200": {
            "description": "Country reference.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/companies": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "searchCompanies",
        "summary": "Search company names in one registry.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query."
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country code."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Max results."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Result offset."
          }
        ],
        "responses": {
          "200": {
            "description": "Search results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/companies/{jurisdiction}/{company_id}": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getCompanyProfile",
        "summary": "Unified company profile.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Registry company identifier."
          },
          {
            "name": "fresh",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Bypass cache."
          }
        ],
        "responses": {
          "200": {
            "description": "Company profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/companies/{jurisdiction}/{company_id}/officers": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getOfficers",
        "summary": "Directors / corporate officers.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Registry company identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Officer list.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/companies/{jurisdiction}/{company_id}/shareholders": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "getShareholders",
        "summary": "Latest shareholder filing (where exposed).",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Registry company identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Shareholder data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/companies/{jurisdiction}/{company_id}/filings": {
      "get": {
        "tags": [
          "Companies"
        ],
        "operationId": "listFilings",
        "summary": "Filing history with document_id for download.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "company_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Registry company identifier."
          }
        ],
        "responses": {
          "200": {
            "description": "Filing history.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/officers": {
      "get": {
        "tags": [
          "Officers"
        ],
        "operationId": "searchOfficers",
        "summary": "Cross-company person search by name.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Search query."
          },
          {
            "name": "jurisdiction",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country code."
          }
        ],
        "responses": {
          "200": {
            "description": "Officer search results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/documents/{jurisdiction}/{document_id}": {
      "get": {
        "tags": [
          "Documents"
        ],
        "operationId": "getDocumentMetadata",
        "summary": "Document size, format, page count.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier from a filing."
          }
        ],
        "responses": {
          "200": {
            "description": "Document metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/documents/{jurisdiction}/{document_id}/content": {
      "get": {
        "tags": [
          "Documents"
        ],
        "operationId": "fetchDocument",
        "summary": "Raw document bytes (302 redirect for large files).",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier from a filing."
          }
        ],
        "responses": {
          "200": {
            "description": "Raw document bytes.",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "302": {
            "description": "Redirect to a temporary URL for large files."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/documents/{jurisdiction}/{document_id}/navigation": {
      "get": {
        "tags": [
          "Documents"
        ],
        "operationId": "getDocumentNavigation",
        "summary": "Document outline + per-page text preview.",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Country / sub-registry code (e.g. GB, NO, CA-BC)."
          },
          {
            "name": "document_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Document identifier from a filing."
          }
        ],
        "responses": {
          "200": {
            "description": "Document navigation.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/api/v1/rpc/{tool}": {
      "get": {
        "tags": [
          "RPC"
        ],
        "operationId": "rpcGet",
        "summary": "Call any tool by name (args via query string).",
        "parameters": [
          {
            "name": "tool",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "list_jurisdictions",
                "search_companies",
                "search_officers",
                "get_company_profile",
                "get_officers",
                "get_shareholders",
                "list_filings",
                "get_document_metadata",
                "fetch_document",
                "get_document_navigation"
              ]
            },
            "description": "Tool name."
          }
        ],
        "responses": {
          "200": {
            "description": "Tool result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "tags": [
          "RPC"
        ],
        "operationId": "rpcPost",
        "summary": "Call any tool by name (args via JSON body).",
        "parameters": [
          {
            "name": "tool",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "list_jurisdictions",
                "search_companies",
                "search_officers",
                "get_company_profile",
                "get_officers",
                "get_shareholders",
                "list_filings",
                "get_document_metadata",
                "fetch_document",
                "get_document_navigation"
              ]
            },
            "description": "Tool name."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Tool arguments."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Tool result envelope."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Personal access token from /account. Omit for anonymous (lower rate limit)."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable detail."
          },
          "hint": {
            "type": "string",
            "description": "Optional follow-up suggestion."
          }
        },
        "required": [
          "error",
          "message"
        ]
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request (bad params or unsupported jurisdiction).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Token present but invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}