Public API

Every path below sits under the /api prefix.

Authentication

Public endpoints (reception and collection) accept the application’s API Token in three equivalent forms:

x-api-token: <token>
Authorization: Bearer <token>
Authorization: Basic <base64(anything:token)>

With Basic, the login and password of one of the Application’s Inbound Credentials also work: the CMS tries the password as a token and, if it is not one, checks the pair as a Credential.

Administrative endpoints use a user JWT (Authorization: Bearer <jwt>), obtained from POST /auth/login.

Message reception (Delivery)

POST /api/{queueCode}/{messageCode}

A two-segment catch-all. That is why administrative routes that could collide use three segments (/collectors/sap/..., /definitions/sap/...).

Collector reception

POST /api/collect/{queueCode}/{collectorCode}

The public counterpart of the delivery endpoint, letting an external producer trigger a Collector by supplying its Input Parameters: the fetch from the source runs right away, and forwarding to the destinations on the queue’s next cycle. Three segments, precisely so it does not collide with the catch-all above. It only exists for a Collector with at least one Input Parameter — without one, 404.

The response carries one id_message per message generated: an SQL Collector that brought back five rows returns an array with five. If the Collector has Return the collected result in the API response on, the response also carries collected_payload, with what the fetch returned — see Configuration.

A Collector response comes with message_type: "SYNC": the fetch at the source already ran inside the call. return_message says what happened — Data collected successfully, or Data collected; forwarding to destinations queued when the result only goes to the destinations. ASYNC is kept for the case of a source Application that is offline, where the fetch is postponed.

Documenting the integration for whoever consumes it

Two exports describe, in a single file, everything an Application receives and sends. They exist to be handed to the team on the other side without writing documentation by hand.

Both require a JWT and the /definitions Tool — the file describes the Definitions, and it is whoever looks after them who hands it over. The Postman collection is also available from the orange icon on the Applications screen.

The base URL of both is resolved from the address the request came through (honouring X-Forwarded-Host/X-Forwarded-Proto), so the file already points at an externally reachable address — the same treatment the WSDL gets.

SOAP

GET  /api/ws/{queueCode}/{messageCode}?wsdl
POST /api/ws/{queueCode}/{messageCode}

The WSDL is generated dynamically from the Definition. Authentication by header or WS-Security UsernameToken.

The Collector API has its own SOAP counterpart, for a Collector with Enable WebService (WSDL) turned on:

GET  /api/ws/collect/{queueCode}/{collectorCode}?wsdl
POST /api/ws/collect/{queueCode}/{collectorCode}

The operation is ExecutarColeta, with one element per Input Parameter inside <parametros>. The token goes in the apiToken element of the body, or in the wsse:UsernameToken with WS-Security — which here also accepts the login and password of an Inbound Credential. Details in Configuration.

User authentication and 2FA

The last two sit under /auth, not /users, on purpose: every logged-in user must be able to see and adjust what is theirs, even without the Users Tool in their role.

AI configuration endpoint

POST /api/mcp is the CMS MCP server: JSON-RPC 2.0 over HTTP, stateless — each request is complete in itself. It authenticates with a token of its own, created under /mcp-tokens:

Authorization: Bearer cms_mcp_...

AI integrations endpoint

POST /api/mcp/applications/{code} is an Application’s MCP integration server: also JSON-RPC 2.0 over HTTP, it lists as tools the Deliveries and Collectors of that Application marked with Expose as MCP tool, and runs them along the same path as message reception. It authenticates with an API Key, an Inbound Credential (Basic) or a user MCP token with the /mcp/integration-tools Tool.

Do not confuse the three channels:

An API Key does not authenticate on /api/mcp, and an MCP token does not send messages through the reception endpoint — only through the tools someone has marked, and with its own Tool in the Role. The separation is deliberate: these are different levels of risk, and they are granted separately.

Internal endpoints

Not exposed through nginx — they exist only inside the compose network: