This guide is for whoever writes the integration: the backend of Clínica del Sol's patient portal asking the scheduling agent something, or a system that triggers an agent when something happens. It explains the contracts as they are today, edges included.
There are three ways to call an agent:
| Way | For | Response |
|---|---|---|
| REST API | Conversing from your system, or triggering an automation | Complete, as JSON |
| OpenAI-compatible | Tools that already speak OpenAI's chat API | Streamed or complete |
| A2A | Letting an agent on another platform call yours | JSON-RPC |
Before you start
- The tenant has API access enabled (chapter 8). Without it, every call gets a 403.
- Create an API key in the agent's tenant, with the permission for the channel you will use:
channel:rest,channel:openai_compatorchannel:a2a. The key looks likesk_….
Two things to keep in mind about keys:
- A key only works for its own tenant. A Nortelink key does not reach Clínica del Sol's agents: the key must be created in the clinic's tenant.
- A key works for every agent in the tenant. If you need to separate access per agent, use separate tenants.
The key goes in the x-api-key header (or Authorization: Bearer sk_…). It is a server secret: do not put it on a web page; that is what the widget and its restricted public key are for.
REST API: conversing
The exact URL is in the agent's Channels tab, on the REST card. It has this shape:
POST {API URL}/api/rest/{tenant}/{agent}
On the Synaptic Links installation, {API URL} is https://ai.synapticlinks.com.ar/api, so the path has /api twice. That is correct: copy it as is.
curl -X POST "https://ai.synapticlinks.com.ar/api/api/rest/clinica-del-sol/turnos-clinica" \
-H "x-api-key: $AICHAT_API_KEY" -H "content-type: application/json" \
-d '{ "message": "Are there general practice appointments on Tuesday?", "sessionId": "patient-4821", "locale": "en" }'
| Field | What it does |
|---|---|
message | The user's message. If present, it is a conversation. |
sessionId | Optional. An identifier of yours (for example, the patient's) or the sessionId the previous response returned. Messages with the same value form the same conversation. |
locale | The conversation language. |
scope | Variables for the workflow (variables.* in expressions), for example { "plan": "gold" }. |
includedContext | Entity context, the same a page sends with the widget. If its payload has customerId or entityKey, it is used for per-entity memory (chapter 10). |
The response, with HTTP 200:
{
"sessionId": "8f0c2a1e-…",
"message": "Yes, on Tuesday there are slots at 9:30 and 11:30 at Sede Centro.",
"finishReason": "stop",
"provider": "openai",
"model": "gpt-…",
"latencyMs": 2140,
"usage": { "promptTokens": 0, "completionTokens": 0, "totalTokens": 912 },
"stepExecutions": [ … ]
}
- Field names are camelCase.
- The response arrives complete: this channel does not stream while it is generated.
usageonly reportstotalTokens.
Always check finishReason. If the run failed —including when the balance is exhausted or a consumption limit is reached— the API still answers 200, with finishReason: "error" and a message that may be empty. Your code must not show an empty message to the user as if it were an answer.
How the conversation is built
Without sessionId, each call starts a new conversation. With sessionId, the platform groups messages with that value for that key. As with messaging channels, after 24 hours without messages a new session starts, and the response carries a different sessionId.
The API does not know who your user is: for the platform, every conversation belongs to the key. So:
- Use one
sessionIdper user or per conversation, never a shared one. - If the agent uses long-term memory, send the person's identifier in
includedContextso memories are not mixed between users.
REST API: triggering an automation
The same URL, without message, triggers the agent with data instead of a message. The whole body, except sessionId and locale, reaches the workflow as trigger.*:
{ "event": "appointment_cancelled", "appointment_id": "T-99812", "location": "Sede Norte" }
- It is synchronous: the call waits for the workflow to finish.
- If the workflow has a Respond node, the HTTP response uses the status, headers and body that node defines. If not, it returns the standard body with an empty
message. - There is no idempotency: if you retry a call that actually ran, the workflow runs twice. If the workflow has side effects, include an identifier of your own and discard duplicates in the workflow or in your system.
- There is no notification when it finishes. Outbound webhooks (chapter 5) report platform events, not the result of a run.
OpenAI-compatible
For tools that already use the OpenAI SDK:
POST {API URL}/v1/chat/completions
GET {API URL}/v1/models
- The key goes as
Authorization: Bearer sk_…, with thechannel:openai_compatpermission. modelis the agent key (turnos-clinica)./v1/modelslists the tenant's active agents.- The last
usermessage is used as the turn.systemmessages are added to the instructions. streamis true by default.- To make several calls one conversation, send
extra_metadata.session_id. Without it, each call starts from scratch.
temperature, max_tokens, tools, n and stop are ignored: the agent uses its own configuration. Errors do not come in OpenAI's format but in the platform's (below), and in streaming mode a run error ends as an empty answer.
A2A
For agents on other platforms that speak the A2A protocol:
- Agent card:
GET {API URL}/api/a2a/{tenant}/{agent}/.well-known/agent-card.json. - Messages:
POSTto the same path without the suffix, JSON-RPC, methodsSendMessageandSendStreamingMessage.
The card is not public: it requires Authorization: Bearer with a key with the channel:a2a permission. The agent must also have A2A enabled in its Channels tab, with a name and description.
- Only text parts are accepted, up to 16,000 bytes.
- To continue a conversation, send the
contextIdfrom the previous response. - A flow that stops to ask for an approval returns "unsupported operation".
Errors
HTTP errors always have this shape:
{ "code": "ERR_CHAT_CONVERSATION_BUSY", "error": "conversation_already_active",
"message": "Conversation is already processing a message; …", "reqId": "…" }
| HTTP | code | What happened | What to do |
|---|---|---|---|
| 400 | ERR_CHAT_INVALID_REQUEST | Invalid body or empty message | Fix the request |
| 401 | ERR_AUTH_API_KEY_REQUIRED | The key is missing, or invalid, expired, revoked or lacks the channel permission | Check the key; all those cases return the same error |
| 403 | ERR_FEATURE_DISABLED | The tenant has no API access | Enable it |
| 404 | ERR_AGENT_NOT_FOUND | The tenant or agent does not exist | Check the URL |
| 409 | ERR_CHAT_CONVERSATION_BUSY | The conversation is still processing a previous message | Wait for the previous response and retry with increasing backoff. The message was not queued |
| 429 | ERR_SYS_RATE_LIMITED | The per-minute limit was exceeded | Wait for what Retry-After says |
| 500 | ERR_SYS_INTERNAL_ERROR | Unexpected error | Retry with backoff; if it persists, report the reqId |
The 409 also appears when the conversation is waiting for an approval: until someone decides it, further messages in that conversation are rejected. For an API integration, the workflow should not ask the user for approvals.
Limits
- 60 requests per minute per tenant on REST, OpenAI and A2A, unless a super admin changes it. The counter is per server instance.
- One run at a time per conversation. To parallelise, use separate conversations.
- Response time. A call that takes more than about 30 seconds may be cut by the delivery network even though the run continues. For long automations, ask whoever operates the installation which URL to use.
Where it stops
- REST does not stream the response: it arrives complete.
- There is no end-user identity on REST: the conversation belongs to the key, and separating people depends on the
sessionIdand the context you send. - Automations are synchronous, with no idempotency and no notification when they finish.
- A run failure on REST returns 200 with
finishReason: "error". - The OpenAI-compatible endpoint ignores generation parameters and does not return errors in OpenAI's format.
- Keys are not restricted per agent.
- There are no attachments on REST.
To check
- The key is in the agent's tenant, with the channel permission, and lives on the server.
- Each user or conversation has its own
sessionId. - The code checks
finishReasonand handles the 409 by waiting for the previous response. - Automations with side effects carry an identifier of their own to discard duplicates.
- The workflow called through the API does not depend on a user approval.