{ "openapi": "3.1.0", "info": { "title": "Swiss Data Atlas API", "version": "1.0.0", "description": "Swiss company data: search, contacts, monitors, digests and natural-language questions. Authenticate with a bearer API key; each key carries scopes and data limits." }, "servers": [ { "url": "https://swissdataatlas.com/api/public/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key issued in the app under Settings > API." } }, "schemas": { "Meta": { "type": "object", "properties": { "requestId": { "type": "string" }, "generatedAt": { "type": "string", "format": "date-time" }, "rowsReturned": { "type": "integer" }, "quota": { "type": "object", "additionalProperties": true } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } }, "Company": { "type": "object", "properties": { "ehraId": { "type": "string" }, "name": { "type": "string" }, "uid": { "type": "string" }, "street": { "type": "string" }, "zip": { "type": "string" }, "town": { "type": "string" }, "canton": { "type": "string" }, "cantonName": { "type": "string" }, "registeredDate": { "type": "string", "nullable": true }, "ageYears": { "type": "integer", "nullable": true }, "anniversaryYears": { "type": "integer", "nullable": true }, "anniversaryDate": { "type": "string", "nullable": true }, "nogaCode": { "type": "string" }, "nogaName": { "type": "string" }, "website": { "type": "string" }, "signatories": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "CompanyList": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } } }, "CompanyOne": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" } } }, "Contact": { "type": "object", "additionalProperties": true }, "ContactResult": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "cached": { "type": "boolean" } } }, "MonitorList": { "type": "object", "properties": { "monitors": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "MonitorCreated": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "MonitorRun": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "sent": { "type": "boolean" }, "message": { "type": "string" } } }, "Digest": { "type": "object", "additionalProperties": true }, "AskResult": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" }, "sql": { "type": "string" }, "columns": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "NogaTree": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "Cantons": { "type": "object", "properties": { "cantons": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mutationTypes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } }, "KeyInfo": { "type": "object", "additionalProperties": true }, "CompanySearchRequest": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "anniversary", "registered" ], "default": "registered" }, "industries": { "type": "array", "items": { "type": "object", "required": [ "level", "code" ], "properties": { "level": { "type": "string", "enum": [ "section", "division", "group", "class", "type" ] }, "code": { "type": "string" }, "name": { "type": "string" } } } }, "cantons": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "anniversaryYears": { "type": "array", "items": { "type": "integer" } }, "fromMonths": { "type": "integer", "default": 3 }, "toMonths": { "type": "integer", "default": 24 }, "registeredFrom": { "type": "string", "nullable": true }, "registeredTo": { "type": "string", "nullable": true }, "websiteOnly": { "type": "boolean", "default": false }, "includeDeleted": { "type": "boolean", "default": false }, "includeLiquidation": { "type": "boolean", "default": false }, "limit": { "type": "integer", "default": 50 } } } } }, "x-scopes": { "companies:read": "Search companies and read company details", "contacts:read": "Reveal signatory contact details (billed per lookup)", "monitors:read": "List saved monitors", "monitors:write": "Create monitors and trigger runs", "digests:read": "Read a monitor's current digest", "ask:write": "Ask questions in natural language", "reference:read": "Read industry (NOGA) and canton reference data" }, "paths": { "/me": { "get": { "summary": "Key introspection: scopes, limits and usage", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KeyInfo" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/companies/search": { "post": { "summary": "Search companies (scope: companies:read)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyList" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "403": { "description": "Scope or data restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/companies/{uid}": { "get": { "summary": "One company by Swiss UID or registry id (scope: companies:read)", "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CompanyOne" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/contacts/reveal": { "post": { "summary": "Reveal a signatory's contact details (scope: contacts:read, billed)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ehraId", "fullName" ], "properties": { "ehraId": { "type": "string" }, "fullName": { "type": "string" }, "companyName": { "type": "string", "nullable": true }, "residence": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContactResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/monitors": { "get": { "summary": "List saved monitors (scope: monitors:read)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorList" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } }, "post": { "summary": "Create a monitor (scope: monitors:write)", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorCreated" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/monitors/{id}/run": { "post": { "summary": "Run a monitor now and mail its digest (scope: monitors:write)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MonitorRun" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/digests/{id}": { "get": { "summary": "Current digest for a monitor (scope: digests:read)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lookbackDays", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Digest" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/ask": { "post": { "summary": "Ask a question in plain language (scope: ask:write)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "minLength": 5, "maxLength": 500 }, "history": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AskResult" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/reference/noga": { "get": { "summary": "Industry tree (scope: reference:read)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/NogaTree" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } }, "/reference/cantons": { "get": { "summary": "Cantons and mutation types (scope: reference:read)", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Cantons" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } } } } } } }