{"openapi":"3.1.0","info":{"title":"OpenRegister API","version":"1.0.0","description":"Versioned access to normalized company records, complete national source data and provenance."},"servers":[{"url":"https://md.hanta.io","description":"Current environment"}],"tags":[{"name":"Registry","description":"Metered company-registry endpoints"},{"name":"Account","description":"Clerk-authenticated developer account operations"},{"name":"Billing","description":"Stripe subscription lifecycle"}],"paths":{"/api/v1/health/live":{"get":{"summary":"Liveness probe","security":[],"responses":{"200":{"description":"Process is alive","content":{"application/json":{"schema":{"type":"object","required":["status","service","version"],"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"web"},"version":{"type":"string"}}}}}}}}},"/api/v1/health/ready":{"get":{"summary":"Readiness probe","security":[],"responses":{"200":{"description":"Service, migrations and database are ready","content":{"application/json":{"schema":{"type":"object","required":["status","database","version"],"properties":{"status":{"type":"string","const":"ready"},"database":{"type":"string","const":"ok"},"version":{"type":"string"}}}}}},"503":{"description":"Database is unavailable or migrations have not completed","content":{"application/json":{"schema":{"type":"object","required":["status","database","version"],"properties":{"status":{"type":"string","const":"unavailable"},"database":{"type":"string","const":"error"},"version":{"type":"string"}}}}}}}}},"/api/v1/countries":{"get":{"tags":["Registry"],"summary":"List supported countries","security":[{"ApiKeyHeader":[]},{"ApiKeyBearer":[]}],"responses":{"200":{"description":"Country catalogue","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current minute window resets","schema":{"type":"integer"}},"X-Monthly-Quota-Limit":{"description":"Maximum requests allowed in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Remaining":{"description":"Requests remaining in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Reset":{"description":"ISO 8601 timestamp when the billing-period quota resets","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"meta":{"type":"object","required":["count"],"properties":{"count":{"type":"integer"}}}}}}}},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/entities":{"get":{"tags":["Registry"],"summary":"Search legal entities","security":[{"ApiKeyHeader":[]},{"ApiKeyBearer":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Name or national registration-number fragment"},{"name":"country","in":"query","schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country code"},{"name":"legalForm","in":"query","schema":{"type":"string"},"description":"Exact national legal-form value"},{"name":"activity","in":"query","schema":{"type":"string"},"description":"Exact national activity code"},{"name":"activityType","in":"query","schema":{"type":"string","enum":["unlicensed","licensed"],"default":"unlicensed"},"description":"Activity-code collection to filter"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Paginated entity summaries","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current minute window resets","schema":{"type":"integer"}},"X-Monthly-Quota-Limit":{"description":"Maximum requests allowed in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Remaining":{"description":"Requests remaining in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Reset":{"description":"ISO 8601 timestamp when the billing-period quota resets","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntitySearchResponse"}}}},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/entities/{id}":{"get":{"tags":["Registry"],"summary":"Get a complete legal-entity record","description":"Returns normalized fields, typed national fields, lossless sourceData, registrations and source-file provenance.","security":[{"ApiKeyHeader":[]},{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Complete entity record","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}},"X-RateLimit-Limit":{"description":"Maximum requests allowed in the current minute","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current minute","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the current minute window resets","schema":{"type":"integer"}},"X-Monthly-Quota-Limit":{"description":"Maximum requests allowed in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Remaining":{"description":"Requests remaining in the current billing period","schema":{"type":"integer"}},"X-Monthly-Quota-Reset":{"description":"ISO 8601 timestamp when the billing-period quota resets","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EntityDetail"}}}}}},"400":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/plans":{"get":{"tags":["Billing"],"summary":"List API plans and entitlements","security":[],"responses":{"200":{"description":"Public plan catalogue","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiPlan"}}}}}}}}}},"/api/v1/account":{"get":{"tags":["Account"],"summary":"Get billing, usage and API-key summaries","security":[{"ClerkSession":[]}],"responses":{"200":{"description":"Developer account"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Account"],"summary":"Get the current Clerk user profile","security":[{"ClerkSession":[]}],"responses":{"200":{"description":"Authenticated user"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/api-keys":{"get":{"tags":["Account"],"summary":"List active API keys","security":[{"ClerkSession":[]}],"responses":{"200":{"description":"API-key summaries"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Account"],"summary":"Create an API key","description":"The full secret is returned once and never stored in plaintext.","security":[{"ClerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":60}}}}}},"responses":{"201":{"description":"API key including its one-time secret"},"400":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/api-keys/{id}":{"delete":{"tags":["Account"],"summary":"Revoke an API key","security":[{"ClerkSession":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Revoked"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create a Stripe Checkout subscription session","security":[{"ClerkSession":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan"],"properties":{"plan":{"type":"string","enum":["pro","business"]}}}}}},"responses":{"200":{"description":"Short-lived Stripe Checkout URL"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/portal":{"post":{"tags":["Billing"],"summary":"Create a Stripe Customer Portal session","security":[{"ClerkSession":[]}],"responses":{"200":{"description":"Short-lived Stripe Customer Portal URL"},"401":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/billing/webhook":{"post":{"tags":["Billing"],"summary":"Receive signed Stripe subscription events","description":"Internal Stripe destination. Requires a valid Stripe-Signature header.","security":[],"responses":{"200":{"description":"Event processed, identified as a duplicate, or acknowledged as stale","content":{"application/json":{"schema":{"type":"object","required":["received","duplicate","stale"],"properties":{"received":{"type":"boolean","const":true},"duplicate":{"type":"boolean"},"stale":{"type":"boolean"}}}}}},"400":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Error response","headers":{"X-Request-ID":{"description":"Stable identifier for support and log correlation","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Recommended authentication for metered registry endpoints."},"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"OpenRegister API key","description":"Bearer-compatible alternative for metered registry endpoints."},"ClerkSession":{"type":"http","scheme":"bearer","bearerFormat":"Clerk session token","description":"Clerk session used by developer account and billing endpoints."}},"schemas":{"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"},"docs":{"type":"string","format":"uri"}}}}},"Country":{"type":"object","required":["code","name","nativeName","enabled"],"properties":{"code":{"type":"string","minLength":2,"maxLength":2},"name":{"type":"string"},"nativeName":{"type":"string"},"enabled":{"type":"boolean"}}},"EntitySummary":{"type":"object","required":["id","countryCode","canonicalName","status"],"properties":{"id":{"type":"string","format":"uuid"},"countryCode":{"type":"string"},"canonicalName":{"type":"string"},"status":{"type":"string"},"legalForm":{"type":["string","null"]},"registeredAt":{"type":["string","null"],"format":"date"},"updatedAt":{"type":"string","format":"date-time"}}},"EntitySearchResponse":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EntitySummary"}},"meta":{"type":"object","required":["page","pageSize","pageCount","total"],"properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"pageCount":{"type":"integer"},"total":{"type":"integer"}}}}},"EntityDetail":{"allOf":[{"$ref":"#/components/schemas/EntitySummary"},{"type":"object","properties":{"registry":{"type":"object","additionalProperties":true},"sourceData":{"type":"object","additionalProperties":true},"registrations":{"type":"array","items":{"type":"object"}},"provenance":{"type":["object","null"],"additionalProperties":true}}}]},"ApiPlan":{"type":"object","required":["id","name","monthlyPriceEur","monthlyRequests","requestsPerMinute","maxApiKeys"],"properties":{"id":{"type":"string","enum":["free","pro","business"]},"name":{"type":"string"},"monthlyPriceEur":{"type":"number"},"monthlyRequests":{"type":"integer"},"requestsPerMinute":{"type":"integer"},"maxApiKeys":{"type":"integer"}}}}}}