{ "openapi": "3.1.0", "info": { "title": "OpenQloud Public API", "version": "0.1.0", "license": { "name": "UNLICENSED", "identifier": "UNLICENSED" }, "description": "Credential-free OpenQloud discovery: the service registry, integrations catalog, integration applications and reference datasets. Integration applications are reviewed by the OpenQloud integrations team. This API does not provision restaurants or configure connections. Restaurant provisioning and commercial responsibility belong to the Customer API for explicitly enabled customer accounts. Configuration and restaurant data management belong to the Management API with explicit delegated permissions, independent of software category and payment. Middleware is another integrated software capability, not the operator or provisioner. These API references are public on the OpenQloud website; Console and Team contracts remain private." }, "servers": [ { "url": "https://api.openqloud.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Public API", "description": "Credential-free public API routes." }, { "name": "Public integrations", "description": "Credential-free integrations directory exposed by OpenQloud." }, { "name": "Integration requests", "description": "Public applications reviewed by the OpenQloud integrations team." }, { "name": "Public data", "description": "Credential-free reference datasets and public metadata." } ], "paths": { "/public-api/v1/health": { "get": { "tags": [ "Public API" ], "summary": "Public API health", "description": "Liveness probe for the public API surface.", "operationId": "getPublicApiHealth", "responses": { "200": { "description": "Public API health response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiHealthResponse" }, "example": { "ok": true, "api": "public", "version": "v1" } } } } } } }, "/public-api/v1": { "get": { "tags": [ "Public API" ], "summary": "Public API index", "description": "Entry point for the public API namespace.", "operationId": "getPublicApiIndex", "responses": { "200": { "description": "Public API index payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiIndexResponse" }, "example": { "ok": true, "api": "public", "version": "v1", "openapi": "/openapi-public-api.json", "services": [ { "id": "service_registry", "name": "Service Registry", "status": "active", "visibility": "public", "description": "Initial public discovery surface for the credential-free OpenQloud API.", "basePath": "/public-api/v1/services" }, { "id": "integrations_catalog", "name": "Integrations Catalog", "status": "active", "visibility": "public", "description": "Public directory of canonical marketplaces, delivery companies, OpenQloud Operators, and OMS modules known by OpenQloud.", "basePath": "/public-api/v1/integrations" } ] } } } } } } }, "/public-api/v1/services": { "get": { "tags": [ "Public API" ], "summary": "Public service registry", "description": "Lists the public services exposed by the public API namespace.", "operationId": "listPublicApiServices", "responses": { "200": { "description": "Public services collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiService" } } }, "required": [ "items" ] }, "example": { "items": [ { "id": "service_registry", "name": "Service Registry", "status": "active", "visibility": "public", "description": "Initial public discovery surface for the credential-free OpenQloud API.", "basePath": "/public-api/v1/services" }, { "id": "integration_requests", "name": "Integration Requests", "status": "active", "visibility": "public", "description": "Receives integration applications for review by the OpenQloud integrations team.", "basePath": "/public-api/v1/integration-requests" } ] } } } } } } }, "/public-api/v1/integrations": { "get": { "tags": [ "Public integrations" ], "summary": "List public integrations", "description": "Returns the public integrations directory exposed by OpenQloud. The current canonical model groups modules under public integration categories stored in the OpenQloud entity graph.", "operationId": "listPublicIntegrations", "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/PublicIntegrationLang" }, "example": "en", "description": "Language of the public directory labels and category descriptions. Defaults to `en`." }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "example": "glovo", "description": "Case-insensitive text search across item name and code." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "example": 20 }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 5000, "default": 0 }, "example": 0 } ], "responses": { "200": { "description": "Public integrations collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicIntegrationListResponse" }, "example": { "ok": true, "lang": "en", "source": "openqloud_entity_graph", "total": 1, "limit": 20, "offset": 0, "categories": [ { "code": "delivery-marketplaces", "name": "Delivery marketplaces", "description": "Delivery ordering platforms.", "total": 1, "items": [ { "id": "module_glovo", "oqid": "module_glovo", "name": "Glovo", "code": "GLOVO", "imageLocation": "https://cdn.openqloud.com/modules/GLOVO.png", "image": "https://cdn.openqloud.com/modules/GLOVO.png", "active": true, "categoryCode": "delivery-marketplaces", "categoryName": "Delivery marketplaces", "categoryDescription": "Delivery ordering platforms." } ] } ], "items": [ { "id": "module_glovo", "oqid": "module_glovo", "name": "Glovo", "code": "GLOVO", "imageLocation": "https://cdn.openqloud.com/modules/GLOVO.png", "image": "https://cdn.openqloud.com/modules/GLOVO.png", "active": true, "categoryCode": "delivery-marketplaces", "categoryName": "Delivery marketplaces", "categoryDescription": "Delivery ordering platforms." } ] } } } }, "400": { "description": "Invalid pagination: limit must be an integer from 1 to 500 and offset an integer from 0 to 5000.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" } } } } } } }, "/public-api/v1/integration-requests": { "post": { "tags": [ "Integration requests" ], "summary": "Submit an integration request", "description": "Stores a new integration request with `pending_validation` status for manual review by OpenQloud.", "operationId": "createIntegrationRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequestCreate" }, "example": { "tradeName": "TableFlow", "companyLegalName": "TableFlow Technologies SL", "taxId": "B12345678", "companyAddress": "Carrer de Mallorca 100, Barcelona", "contactName": "Alex Doe", "email": "alex@example.com", "phone": "+34600000000", "services": [ "table-ordering", "pos" ], "restaurantsUsing": 25, "restaurantsToIntegrate": 10, "source": "openqloud-developer", "locale": "en", "requestUrl": "https://www.openqloud.com/en/integrations/", "website": "https://example.com" } } } }, "responses": { "201": { "description": "Integration request registered and pending validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequestCreateResponse" }, "example": { "ok": true, "data": { "id": "irq_01m1403adnrnhh91czptxzwk1q", "status": "pending_validation", "createdAt": "2026-08-28T10:54:23.669Z" } } } } }, "400": { "description": "Invalid integration request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" }, "example": { "success": false, "message": "INVALID_INTEGRATION_REQUEST" } } } } } } }, "/public-data/v1/info": { "get": { "tags": [ "Public data" ], "summary": "Public data service info", "description": "Returns service metadata for the public-data surface, including the current dataset count.", "operationId": "getPublicDataInfo", "responses": { "200": { "description": "Public data service info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDataInfoResponse" }, "example": { "success": true, "data": { "service": "OpenQloud Public Data", "datasets": 3 } } } } } } } }, "/public-data/v1/datasets": { "get": { "tags": [ "Public data" ], "summary": "List public datasets", "description": "Returns the public datasets exposed by the backend without credentials.", "operationId": "listPublicDatasets", "responses": { "200": { "description": "Public datasets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDatasetSummary" } }, "example": [ { "id": "openqloud-entity-types", "name": { "en": "Entity types", "es": "Tipos de entidad" }, "description": { "en": "Record families OpenQloud keeps, with their oqid prefix.", "es": "Familias de registros que guarda OpenQloud, con su prefijo de oqid." }, "columns": [ { "id": "code", "label": { "en": "Code", "es": "Código" } }, { "id": "prefix", "label": { "en": "oqid prefix", "es": "Prefijo oqid" } }, { "id": "domain", "label": { "en": "Domain", "es": "Dominio" } } ], "rowsCount": 10 } ] } } } } } }, "/public-data/v1/datasets/{datasetId}": { "get": { "tags": [ "Public data" ], "summary": "Read public dataset", "description": "Returns one public dataset by id. The openqloud-auth-model dataset distinguishes integrated middleware software, independently enabled customer accounts and explicit delegated restaurant permissions. Software category, account membership and payment responsibility alone do not grant restaurant data access.", "operationId": "getPublicDataset", "parameters": [ { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "openqloud-entity-types" } ], "responses": { "200": { "description": "Public dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicDataset" }, "example": { "id": "openqloud-entity-types", "name": { "en": "Entity types", "es": "Tipos de entidad" }, "description": { "en": "Record families OpenQloud keeps, with their oqid prefix.", "es": "Familias de registros que guarda OpenQloud, con su prefijo de oqid." }, "columns": [ { "id": "code", "label": { "en": "Code", "es": "Código" } }, { "id": "prefix", "label": { "en": "oqid prefix", "es": "Prefijo oqid" } }, { "id": "domain", "label": { "en": "Domain", "es": "Dominio" } } ], "rows": [ { "code": "location", "prefix": "loc", "domain": "Identity" } ] } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicApiErrorResponse" }, "example": { "success": false, "message": "DATASET_NOT_FOUND" } } } } } } }, "/public-data/v1/allergens": { "get": { "tags": [ "Public data" ], "summary": "List public allergens", "description": "Returns the public allergen dataset published by OpenQloud.", "operationId": "listPublicAllergens", "responses": { "200": { "description": "Public allergen dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicAllergensResponse" }, "example": { "success": true, "data": [ { "id": "gluten", "label": { "en": "Gluten", "es": "Gluten" } }, { "id": "milk", "label": { "en": "Milk", "es": "Leche" } }, { "id": "nuts", "label": { "en": "Nuts", "es": "Frutos secos" } } ] } } } } } } } }, "components": { "schemas": { "PublicLocalizedText": { "type": "object", "required": [ "en", "es" ], "additionalProperties": false, "properties": { "en": { "type": "string" }, "es": { "type": "string" } } }, "PublicDatasetColumn": { "type": "object", "required": [ "id", "label" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "label": { "$ref": "#/components/schemas/PublicLocalizedText" } } }, "PublicDatasetSummary": { "type": "object", "required": [ "id", "name", "description", "columns", "rowsCount" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/PublicLocalizedText" }, "description": { "$ref": "#/components/schemas/PublicLocalizedText" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDatasetColumn" } }, "rowsCount": { "type": "integer", "minimum": 0 } } }, "PublicDataset": { "type": "object", "required": [ "id", "name", "description", "columns", "rows" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "$ref": "#/components/schemas/PublicLocalizedText" }, "description": { "$ref": "#/components/schemas/PublicLocalizedText" }, "columns": { "type": "array", "items": { "$ref": "#/components/schemas/PublicDatasetColumn" } }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/PublicLocalizedText" } ] } } } } }, "PublicApiErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "PublicApiHealthResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "api": { "type": "string", "const": "public" }, "version": { "type": "string", "const": "v1" } }, "required": [ "ok", "api", "version" ] }, "PublicApiIndexResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "api": { "type": "string", "const": "public" }, "version": { "type": "string", "const": "v1" }, "openapi": { "type": "string", "example": "/openapi-public-api.json" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/PublicApiService" } } }, "required": [ "ok", "api", "version", "openapi", "services" ] }, "PublicApiService": { "type": "object", "properties": { "id": { "type": "string", "example": "service_registry" }, "name": { "type": "string", "example": "Service Registry" }, "status": { "type": "string", "enum": [ "planned", "active" ], "example": "planned" }, "visibility": { "type": "string", "const": "public" }, "description": { "type": "string", "example": "Skeleton registration for a future credential-free public service." }, "basePath": { "type": "string", "example": "/public-api/v1/services" } }, "required": [ "id", "name", "status", "visibility", "description", "basePath" ] }, "IntegrationRequestServiceType": { "type": "string", "enum": [ "pos", "delivery-ordering", "takeaway", "table-ordering", "kiosk", "on-demand-delivery", "other" ] }, "IntegrationRequestCreate": { "type": "object", "additionalProperties": false, "required": [ "tradeName", "companyLegalName", "taxId", "companyAddress", "contactName", "email", "phone", "services", "restaurantsUsing", "restaurantsToIntegrate" ], "properties": { "tradeName": { "type": "string", "minLength": 2, "maxLength": 180 }, "companyLegalName": { "type": "string", "minLength": 2, "maxLength": 180 }, "taxId": { "type": "string", "minLength": 2, "maxLength": 40 }, "companyAddress": { "type": "string", "minLength": 4, "maxLength": 300 }, "contactName": { "type": "string", "minLength": 2, "maxLength": 160 }, "email": { "type": "string", "format": "email", "maxLength": 180 }, "phone": { "type": "string", "minLength": 4, "maxLength": 80 }, "services": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/IntegrationRequestServiceType" } }, "otherService": { "type": [ "string", "null" ], "maxLength": 1000 }, "restaurantsUsing": { "type": "integer", "minimum": 0 }, "restaurantsToIntegrate": { "type": "integer", "minimum": 1 }, "source": { "type": "string", "const": "openqloud-developer", "default": "openqloud-developer" }, "locale": { "type": "string", "minLength": 2, "maxLength": 10, "default": "en" }, "requestUrl": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 }, "website": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000 }, "honeypot": { "type": "string", "maxLength": 0 } } }, "IntegrationRequestCreateResponse": { "type": "object", "required": [ "ok", "data" ], "properties": { "ok": { "type": "boolean", "const": true }, "data": { "type": "object", "required": [ "id", "status", "createdAt" ], "properties": { "id": { "type": "string", "example": "irq_01knexample00000000000001" }, "status": { "type": "string", "const": "pending_validation" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "PublicIntegrationLang": { "type": "string", "enum": [ "ar", "ca", "de", "en", "es", "fr", "it", "pt", "zh" ], "example": "es" }, "PublicIntegrationCatalogItem": { "type": "object", "properties": { "id": { "type": "string", "example": "GLOVO-0-delivery-marketplaces" }, "name": { "type": "string", "example": "Glovo" }, "code": { "type": "string", "example": "GLOVO" }, "imageLocation": { "type": [ "string", "null" ], "example": "https://cdn.openqloud.com/modules/GLOVO.png" }, "image": { "type": [ "string", "null" ], "example": "https://cdn.openqloud.com/modules/GLOVO.png" }, "active": { "type": "boolean", "example": true }, "categoryCode": { "type": "string", "example": "delivery-marketplaces" }, "categoryName": { "type": "string", "example": "Delivery orders marketplaces" }, "categoryDescription": { "type": "string", "example": "A delivery orders platform is a web or mobile app that allows users to place delivery orders from different restaurants." } }, "required": [ "id", "name", "code", "categoryCode", "categoryName", "categoryDescription" ] }, "PublicIntegrationCatalogCategory": { "type": "object", "properties": { "code": { "type": "string", "example": "delivery-marketplaces" }, "name": { "type": "string", "example": "Delivery orders marketplaces" }, "description": { "type": "string", "example": "A delivery orders platform is a web or mobile app that allows users to place delivery orders from different restaurants." }, "total": { "type": "integer", "example": 52 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIntegrationCatalogItem" } } }, "required": [ "code", "name", "description", "total", "items" ] }, "PublicIntegrationListResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "lang": { "$ref": "#/components/schemas/PublicIntegrationLang" }, "source": { "type": "string", "const": "openqloud_entity_graph" }, "total": { "type": "integer", "example": 125 }, "limit": { "type": "integer", "example": 100 }, "offset": { "type": "integer", "example": 0 }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIntegrationCatalogCategory" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicIntegrationCatalogItem" } } }, "required": [ "ok", "lang", "source", "total", "limit", "offset", "categories", "items" ] }, "PublicDataInfoResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "service": { "type": "string", "example": "OpenQloud Public Data" }, "datasets": { "type": "integer", "example": 3 } }, "required": [ "service", "datasets" ] } }, "required": [ "success", "data" ] }, "PublicAllergen": { "type": "object", "properties": { "id": { "type": "string", "example": "gluten" }, "label": { "type": "object", "properties": { "en": { "type": "string", "example": "Gluten" }, "es": { "type": "string", "example": "Gluten" } }, "required": [ "en", "es" ] } }, "required": [ "id", "label" ] }, "PublicAllergensResponse": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAllergen" } } }, "required": [ "success", "data" ] } } } }