{"openapi":"3.1.0","info":{"title":"Swiss Graph Public API","version":"1.0.0","summary":"Swiss commercial register (SHAB/SOGC): companies, officers and people — free, read-only preview API of graph.swiss.","description":"Read-only, unauthenticated JSON access to the Swiss commercial register as published by Swiss Graph (https://graph.swiss): companies, their registered officers and gazette publications, and the people who hold mandates. Source: the Swiss Official Gazette of Commerce (SHAB/SOGC); the cantonal register remains the legal authority.\n\n## When to use\n- Resolve a Swiss company name, UID (CHE-…) or city to a registry record, its legal form, status, address and NOGA industry code.\n- Find who sits on a Swiss board or signs for a company today, and which companies a person holds mandates in.\n- Ground an answer about a Swiss company in its latest gazette publications.\n- Not for: bulk export of the register, contact details (email/phone), financial statements, or non-Swiss companies. For volume and full-depth data use the keyed Graph Swiss API (https://docs.graph.swiss/).\n\n## How to call\n- No authentication. Per-client rate limits: 60 search or autocomplete calls and 120 detail calls per minute; every response carries X-RateLimit-Limit / -Remaining / -Reset and a 429 carries Retry-After.\n- Pagination: `limit` (max 25) and `offset` (max 44); the preview walks at most 45 rows per query — narrow the query instead of paging deeper.\n- Errors: every non-2xx body is `{ \"error\": { \"code\", \"message\", \"hint\", \"docs\" } }` with a stable `code`.\n- Every company and person record links its canonical profile (`url`) and a Markdown fact sheet (`markdown_url`, the same URL with `.md`) for agents that prefer text.\n- The same operations are exposed as MCP tools at https://graph.swiss/mcp (Streamable HTTP; descriptor at https://graph.swiss/.well-known/mcp). Site overview for agents: https://graph.swiss/llms.txt.\n\n## Data and privacy\n- Registry facts only — no enrichment, no contact PII. Persons the register has ordered redacted appear as \"Redacted person\" in lists and have no retrievable record.\n- Present officers only; board history and gazette entries beyond the newest 3 are part of the paid product on https://graph.swiss.\n- Terms: https://graph.swiss/legal/terms-of-service · Data sources: https://graph.swiss/legal/data-sources · Operator: Nerturbo AG, Zug (https://graph.swiss/legal/imprint).","termsOfService":"https://graph.swiss/legal/terms-of-service","contact":{"name":"Swiss Graph (Nerturbo AG)","url":"https://graph.swiss/legal/imprint"},"x-logo":{"url":"https://graph.swiss/sg-big-logo-lightbg.svg","altText":"Swiss Graph"}},"servers":[{"url":"https://graph.swiss","description":"Production"}],"externalDocs":{"url":"https://graph.swiss/developer","description":"Swiss Graph API & developer resources — human guide, MCP connection details, keyed Graph Swiss API."},"tags":[{"name":"Companies","description":"Swiss companies from the commercial register: search, autocomplete, full registry record."},{"name":"People","description":"Registered officers and their mandates: search and person record."}],"security":[],"x-mcp":{"url":"https://graph.swiss/mcp","transport":"streamable-http","descriptor":"https://graph.swiss/.well-known/mcp"},"x-llms-txt":"https://graph.swiss/llms.txt","paths":{"/api/v1/companies/search":{"get":{"operationId":"searchCompanies","tags":["Companies"],"summary":"Search Swiss companies","description":"Full-text search over company names and UIDs in the Swiss commercial register, optionally narrowed by canton, register status and legal form. Returns ordered, deterministic pages; each row links the canonical profile and its Markdown fact sheet. Use `autocompleteCompanies` for type-ahead and `getCompany` for the full record.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/canton"},{"$ref":"#/components/parameters/status"},{"$ref":"#/components/parameters/legal_form"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"description":"A page of matching companies.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchPage"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}},"security":[]}},"/api/v1/companies/autocomplete":{"get":{"operationId":"autocompleteCompanies","tags":["Companies"],"summary":"Autocomplete a company name","description":"Fast prefix suggestions for a partial company name (minimum 2 characters): id, name, UID, canton and location. Cheaper than a search; resolve the chosen id with `getCompany`.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/autocompleteLimit"}],"responses":{"200":{"description":"Matching suggestions, best first.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySuggestions"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}},"security":[]}},"/api/v1/companies/{id}":{"get":{"operationId":"getCompany","tags":["Companies"],"summary":"Get a company record","description":"The registry record of one company by its Swiss Graph id (the numeric id in every search result and in profile URLs): identifiers, legal form, status, address, purpose, capital, previous names, NOGA industry classification, the PRESENT board with signing authority, and the newest 3 gazette publications (texts clipped at 2000 characters). Persons the register has redacted appear as \"Redacted person\" without a profile link.","parameters":[{"$ref":"#/components/parameters/companyId"}],"responses":{"200":{"description":"The company record.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDetail"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}},"security":[]}},"/api/v1/people/search":{"get":{"operationId":"searchPeople","tags":["People"],"summary":"Search registered officers","description":"Search natural persons who appear in the Swiss commercial register (board members, managing directors, signatories) by name. Same-person duplicates are collapsed; redacted persons are masked and carry no profile URL. Resolve a row with `getPerson` to see their mandates.","parameters":[{"$ref":"#/components/parameters/q"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"description":"A page of matching people.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonSearchPage"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}},"security":[]}},"/api/v1/people/{id}":{"get":{"operationId":"getPerson","tags":["People"],"summary":"Get a person record","description":"The registry record of one person by their Swiss Graph id: name, residence, nationality, status, and every company mandate (role, signing authority, whether the company is still active). Persons the register has redacted have no retrievable record and answer 404.","parameters":[{"$ref":"#/components/parameters/personId"}],"responses":{"200":{"description":"The person record.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonDetail"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/UpstreamUnavailable"}},"security":[]}}},"components":{"parameters":{"q":{"name":"q","in":"query","required":true,"description":"Search text — company name, UID (e.g. CHE-116.281.710), or person name. 2–200 characters.","schema":{"type":"string","minLength":2,"maxLength":200,"examples":["Nestlé","CHE-116.281.710"]}},"canton":{"name":"canton","in":"query","required":false,"description":"Restrict to one or more cantons (two-letter codes, comma-separated).","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["AG","AI","AR","BE","BL","BS","FR","GE","GL","GR","JU","LU","NE","NW","OW","SG","SH","SO","SZ","TG","TI","UR","VD","VS","ZG","ZH"]},"maxItems":26,"examples":[["ZH","ZG"]]}},"status":{"name":"status","in":"query","required":false,"description":"Restrict to register statuses (comma-separated).","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["active","liquidation","deleted"]},"maxItems":3,"examples":[["active"]]}},"legal_form":{"name":"legal_form","in":"query","required":false,"description":"Restrict to legal forms (comma-separated tokens).","style":"form","explode":false,"schema":{"type":"array","items":{"type":"string","enum":["limited_or_corporation","limited_liability_company","sole_proprietorship","general_partnership","limited_partnership","cooperative","association","foundation","swiss_branch","foreign_branch","institut","indivision","special_legal_forms"]},"maxItems":13,"examples":[["limited_or_corporation"]]}},"limit":{"name":"limit","in":"query","required":false,"description":"Page size (default 10, max 25).","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},"autocompleteLimit":{"name":"limit","in":"query","required":false,"description":"Maximum number of suggestions (default 8, max 25).","schema":{"type":"integer","minimum":1,"maximum":25,"default":8}},"offset":{"name":"offset","in":"query","required":false,"description":"Zero-based row offset (max 44; the preview paginates 45 rows per query). Use `next_offset` from the previous page.","schema":{"type":"integer","minimum":0,"maximum":44,"default":0}},"companyId":{"name":"id","in":"path","required":true,"description":"Swiss Graph company id — the numeric id from search results and profile URLs (/companies/{slug}/{id}).","schema":{"type":"integer","minimum":1,"examples":[102945]}},"personId":{"name":"id","in":"path","required":true,"description":"Swiss Graph person id — the numeric id from search results and profile URLs (/people/{slug}/{id}).","schema":{"type":"integer","minimum":1,"examples":[440730]}}},"headers":{"X-RateLimit-Limit":{"description":"Requests allowed per window for this client.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix time (seconds) at which the window resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"Link":{"description":"RFC 8631 service links: rel=\"service-desc\" → this document, rel=\"service-doc\" → the developer guide.","schema":{"type":"string"}}},"responses":{"InvalidParameter":{"description":"A query or path parameter is missing, malformed or out of range. The message names the parameter; the hint gives the accepted range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tooShort":{"value":{"error":{"code":"invalid_parameter","message":"q must be at least 2 characters.","hint":"Pass a company name, UID or person name of 2–200 characters.","docs":"https://graph.swiss/openapi.json"}}}}}}},"NotFound":{"description":"No record with this id (or the register has suppressed it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"value":{"error":{"code":"not_found","message":"No company with id 1.","hint":"Ids come from searchCompanies or autocompleteCompanies results.","docs":"https://graph.swiss/openapi.json"}}}}}}},"RateLimited":{"description":"Too many requests from this client in the current window.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Link":{"$ref":"#/components/headers/Link"},"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamUnavailable":{"description":"The register backend is temporarily unavailable; retry after the Retry-After delay.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","docs"],"properties":{"code":{"type":"string","enum":["invalid_parameter","not_found","method_not_allowed","rate_limited","upstream_unavailable","internal_error"],"description":"Stable machine-readable error code."},"message":{"type":"string","description":"What went wrong."},"hint":{"type":"string","description":"What to do about it."},"docs":{"type":"string","format":"uri","description":"Where the contract lives."}}}}},"CompanySearchResult":{"type":"object","required":["id","name","uid","status","legal_form","register_date","address","location","canton","url","markdown_url"],"properties":{"id":{"type":"integer","description":"Swiss Graph company id."},"name":{"type":"string"},"uid":{"type":["string","null"],"description":"Swiss UID, e.g. CHE-116.281.710."},"status":{"type":["string","null"],"description":"Register status, e.g. active, deleted."},"legal_form":{"type":["string","null"]},"register_date":{"type":["string","null"],"format":"date"},"address":{"type":["string","null"]},"location":{"type":["string","null"]},"canton":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"Canonical profile on graph.swiss."},"markdown_url":{"type":"string","format":"uri","description":"Markdown fact sheet for agents."}}},"CompanySearchPage":{"type":"object","required":["total","items","limit","offset","next_offset"],"properties":{"total":{"type":"integer","description":"Total matches upstream (may exceed what the preview can page through)."},"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanySearchResult"}},"limit":{"type":"integer"},"offset":{"type":"integer"},"next_offset":{"type":["integer","null"],"description":"Offset of the next page, or null."}}},"CompanySuggestion":{"type":"object","required":["id","name","uid","canton","location","url"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"uid":{"type":["string","null"]},"canton":{"type":["string","null"]},"location":{"type":["string","null"]},"url":{"type":"string","format":"uri"}}},"CompanySuggestions":{"type":"object","required":["suggestions"],"properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/CompanySuggestion"}}}},"NogaClassification":{"type":"object","required":["id","code","level","labels"],"description":"NOGA 2008 economic activity classification (Swiss Federal Statistical Office).","properties":{"id":{"type":"integer"},"code":{"type":"string","examples":["620100"]},"level":{"type":["integer","null"]},"labels":{"type":"object","required":["en","de","fr","it"],"properties":{"en":{"type":["string","null"]},"de":{"type":["string","null"]},"fr":{"type":["string","null"]},"it":{"type":["string","null"]}}}}},"CompanyOfficer":{"type":"object","required":["id","name","role","signing_authority","status","entity_type","redacted","url"],"properties":{"id":{"type":"integer","description":"Swiss Graph person id."},"name":{"type":"string","description":"\"Redacted person\" when the register has suppressed the name."},"role":{"type":["string","null"],"description":"Registry role, e.g. Mitglied des Verwaltungsrates."},"signing_authority":{"type":["string","null"]},"status":{"type":["string","null"]},"entity_type":{"type":"string","enum":["natural_person","legal_entity"]},"redacted":{"type":"boolean"},"url":{"type":["string","null"],"format":"uri","description":"Person profile; null for redacted persons."}}},"CompanyPublication":{"type":"object","required":["id","journal_no","journal_date","sogc_date","text","text_truncated"],"properties":{"id":{"type":"integer"},"journal_no":{"type":["string","null"]},"journal_date":{"type":["string","null"]},"sogc_date":{"type":["string","null"]},"text":{"type":["string","null"],"description":"Gazette text, clipped at 2000 characters."},"text_truncated":{"type":"boolean"}}},"CompanyDetail":{"type":"object","required":["id","name","uid","status","legal_form","register_date","address","location","canton","purpose","capital","previous_names","noga","officers","publications","publications_total","url","markdown_url","source"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"uid":{"type":["string","null"]},"status":{"type":["string","null"]},"legal_form":{"type":["string","null"]},"register_date":{"type":["string","null"],"format":"date"},"address":{"type":["string","null"]},"location":{"type":["string","null"]},"canton":{"type":["string","null"]},"purpose":{"type":["string","null"],"description":"Registered business purpose (original language)."},"capital":{"type":["string","null"]},"previous_names":{"type":"array","items":{"type":"string"}},"noga":{"oneOf":[{"$ref":"#/components/schemas/NogaClassification"},{"type":"null"}]},"officers":{"type":"array","items":{"$ref":"#/components/schemas/CompanyOfficer"},"description":"Present board and signatories only."},"publications":{"type":"array","items":{"$ref":"#/components/schemas/CompanyPublication"},"maxItems":3},"publications_total":{"type":"integer","description":"Number of gazette entries on record (the profile page shows them all)."},"url":{"type":"string","format":"uri"},"markdown_url":{"type":"string","format":"uri"},"source":{"type":"string"}}},"PersonSearchResult":{"type":"object","required":["id","name","first_name","last_name","residence","nationality","status","redacted","url"],"properties":{"id":{"type":"integer","description":"Swiss Graph person id."},"name":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"residence":{"type":["string","null"]},"nationality":{"type":["string","null"]},"status":{"type":["string","null"]},"redacted":{"type":"boolean"},"url":{"type":["string","null"],"format":"uri"}}},"PersonSearchPage":{"type":"object","required":["total","items","limit","offset","next_offset"],"properties":{"total":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PersonSearchResult"}},"limit":{"type":"integer"},"offset":{"type":"integer"},"next_offset":{"type":["integer","null"]}}},"PersonMandateCompany":{"type":"object","required":["id","name","uid","status","legal_form","location","canton","url"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"uid":{"type":["string","null"]},"status":{"type":["string","null"]},"legal_form":{"type":["string","null"]},"location":{"type":["string","null"]},"canton":{"type":["string","null"]},"url":{"type":"string","format":"uri"}}},"PersonMandate":{"type":"object","required":["company","role","signing_authority","company_active"],"properties":{"company":{"$ref":"#/components/schemas/PersonMandateCompany"},"role":{"type":["string","null"]},"signing_authority":{"type":["string","null"]},"company_active":{"type":"boolean","description":"False when the company is no longer active (a former mandate)."}}},"PersonDetail":{"type":"object","required":["id","name","first_name","last_name","residence","nationality","status","mandates","url","markdown_url","source"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"residence":{"type":["string","null"]},"nationality":{"type":["string","null"]},"status":{"type":["string","null"]},"mandates":{"type":"array","items":{"$ref":"#/components/schemas/PersonMandate"}},"url":{"type":"string","format":"uri"},"markdown_url":{"type":"string","format":"uri"},"source":{"type":"string"}}}}}}