Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/emporix:emporix-agent-chat-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Emporix Agent Chat API
version: ''
contact:
name: Emporix
url: https://emporix.com
email: documentation@emporix.com
description: 'Operations tagged Agent Chat across 2 of this provider''s published API definitions: emporix-ai-service-openapi.yml, emporix-ai-service-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
tags:
- name: Agent Chat
description: Chat With Agents
paths:
/ai-service/{tenant}/agentic/chat:
parameters:
- $ref: '#/components/parameters/path_tenant'
- $ref: '#/components/parameters/header_session-id'
post:
summary: Starting agent chat
operationId: POST-ai-agents-chat
responses:
'200':
description: Chat response.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChatResponse'
examples:
JobId:
value:
- agentId: complaint-agent
agentType: complaint
message: Found an order with its details.
sessionId: fe91d168-4ce9-4b4d-8451-0029035b34a5
'400':
$ref: '#/components/responses/400_resp_common'
'401':
$ref: '#/components/responses/401_resp_common'
'403':
$ref: '#/components/responses/403_resp_common'
'500':
$ref: '#/components/responses/500_resp_common'
description: 'Allows for communication with Emporix agents. Conversational continuity requires both the `session-id` header and `enabledMemory` set to `true` on the agent. Collaborations configured in `agentCollaborations` run in the same session.
When the request includes `attachments`, each `attachments[].attachmentId` must reference a file already uploaded in this session. Send the upload `sessionId` as the `session-id` header. The attachment must already be attached to the `agentId` in the request body. After a file upload, send that same path `agentId` in the chat body. After reuse, send the target agent''s path `agentId` in the chat body. If they differ, the request returns `400`. To use the file with a different agent, first assign the attachment to that agent with `attachmentId` on `POST /ai-service/{tenant}/agentic/{agentId}/attachments` using the target `agentId` in the path, then chat with that target agent.'
security:
- OAuth2:
- ai.agentexecution_manage_own
- ai.agentexecution_manage
requestBody:
$ref: '#/components/requestBodies/AgenticChat'
tags:
- Agent Chat
servers:
- url: https://api.emporix.io
/ai-service/{tenant}/agentic/chat-stream:
parameters:
- $ref: '#/components/parameters/path_tenant'
- $ref: '#/components/parameters/header_session-id'
- schema:
type: string
example: text/event-stream
name: Accept
in: header
required: false
description: Use `text/event-stream` to receive the response as a Server-Sent Events stream.
post:
summary: Starting agent chat stream
operationId: POST-ai-agents-chat-stream
responses:
'200':
description: Chat response stream as Server-Sent Events. Each named event carries a JSON object in `data`. Concatenate `token` `content` values for the assistant reply. When `session_id` is present on the `done` event, send it as the `session-id` header on later calls.
content:
text/event-stream:
schema:
type: string
description: "Complete Server-Sent Events body. The HTTP entity is `event:` / `data:` text, not a JSON object.\n\nEach `data` line is a JSON object. The object shape depends on the event name and is documented by `ChatStreamEventData`:\n\n* `token` — `ChatStreamTokenData`\n* `thinking` — **The `thinking` event is in preview mode** - some of the features may not be fully operational yet.\n\n `ChatStreamThinkingData`\n* `tool_start` and `tool_end` — `ChatStreamToolMetaData`\n* `tool_result` — `ChatStreamToolResultData`\n* `done` — `ChatStreamDoneData`\n* `error` — **The `error` event is in preview mode** - some of the features may not be fully operational yet.\n\n `ChatStreamErrorData`"
examples:
TokenDeltasAndCompletion:
summary: Incremental assistant text followed by session metadata
value: 'event: token
data: {"content":"Standard "}
event: token
data: {"content":"delivery is available for order EON1243."}
event: done
data: {"agent_id":"generic-agent","agent_type":"generic","session_id":"33a550d0-d812-4fb2-bb0d-d50dbfe3627b"}'
ToolActivity:
summary: Tool start, result, and end around a token delta
value: 'event: tool_start
data: {"tool_name":"get-quotes","tool_call_id":"call-1"}
event: tool_result
data: {"tool_name":"get-quotes","tool_call_id":"call-1","output":{"quotes":[{"id":"Q1"}]}}
event: tool_end
data: {"tool_name":"get-quotes","tool_call_id":"call-1"}
event: token
data: {"content":"Quote Q1 is available."}
event: done
data: {"agent_id":"generic-agent","agent_type":"generic","session_id":"33a550d0-d812-4fb2-bb0d-d50dbfe3627b"}'
StreamError:
summary: In-stream error before completion
value: 'event: error
data: {"code":"AGENT_SETUP","message":"Agent setup failed"}
event: done
data: {"session_id":"33a550d0-d812-4fb2-bb0d-d50dbfe3627b"}'
'400':
$ref: '#/components/responses/400_resp_common'
'401':
$ref: '#/components/responses/401_resp_common'
'403':
$ref: '#/components/responses/403_resp_common'
'500':
$ref: '#/components/responses/500_resp_common'
description: 'Allows for communication with Emporix agents using a Server-Sent Events stream. Conversational continuity requires both the `session-id` header and `enabledMemory` set to `true` on the agent. Collaborations configured in `agentCollaborations` run in the same session.
When the request includes `attachments`, each `attachments[].attachmentId` must reference a file already uploaded in this session. Send the upload `sessionId` as the `session-id` header. The attachment must already be attached to the `agentId` in the request body. After a file upload, send that same path `agentId` in the chat body. After reuse, send the target agent''s path `agentId` in the chat body. If they differ, the request returns `400`. To use the file with a different agent, first assign the attachment to that agent with `attachmentId` on `POST /ai-service/{tenant}/agentic/{agentId}/attachments` using the target `agentId` in the path, then chat with that target agent.
The response `Content-Type` is `text/event-stream`. Each frame uses an SSE `event` name and a JSON object in `data`. Concatenate successive `token` `content` values to build the assistant reply. The `done` event carries session metadata, including `session_id` when present. Send that value as the `session-id` header on later chat and attachment calls. The `done` event does not repeat the full message.
Named events:
* `token` — Incremental text of the assistant reply. `data` is `{ "content": "..." }`.
* `thinking` — **The `thinking` event is in preview mode** - some of the features may not be fully operational yet.
Optional reasoning text. `data` is `{ "content": "..." }`. Do not treat this as part of the user-facing reply unless the client displays reasoning.
* `tool_start` — The agent started a tool. `data` is `{ "tool_name": "...", "tool_call_id": "..." }`.
* `tool_end` — The agent finished a tool. `data` uses the same fields as `tool_start`.
* `tool_result` — Tool output. `data` is `{ "tool_name": "...", "tool_call_id": "...", "output": {} }`. `output` is a JSON object or array. Credential-like keys in `output` are omitted.
* `done` — The stream completed. `data` includes `agent_id`, `agent_type`, and `session_id` when present. At least one of these fields is sent.
* `error` — **The `error` event is in preview mode** - some of the features may not be fully operational yet.
A failure during generation. `data` includes `message` and/or `code`. Example codes are `AGENT_SETUP` and `RECURSION_LIMIT`.
SSE `data` fields use snake_case (`session_id`, `agent_id`, `agent_type`). They are not the camelCase fields of the synchronous chat `ChatResponse` (`sessionId`, `agentId`, `agentType`).
HTTP `400`, `401`, `403`, and `500` responses are JSON problem bodies, not SSE events. They occur when the request is rejected before the stream starts. Unknown event names are not forwarded. Frames without an event name and with no data may appear as keepalives; ignore them.'
security:
- OAuth2:
- ai.agentexecution_manage_own
- ai.agentexecution_manage
requestBody:
$ref: '#/components/requestBodies/AgenticChat'
tags:
- Agent Chat
servers:
- url: https://api.emporix.io
/ai-service/{tenant}/agentic/chat-async:
parameters:
- $ref: '#/components/parameters/path_tenant'
- $ref: '#/components/parameters/header_session-id'
post:
summary: Starting agent async chat
operationId: POST-ai-agents-chat-async
responses:
'201':
description: Job ID response.
content:
application/json:
schema:
$ref: '#/components/schemas/JobIdResponse'
examples:
JobId:
value:
jobId: 68835cc3ef4e8e1425c360ad
'400':
$ref: '#/components/responses/400_resp_common'
'401':
$ref: '#/components/responses/401_resp_common'
'403':
$ref: '#/components/responses/403_resp_common'
'500':
$ref: '#/components/responses/500_resp_common'
description: 'Allows for communication with Emporix agents in async way. Conversational continuity requires both the `session-id` header and `enabledMemory` set to `true` on the agent. Collaborations configured in `agentCollaborations` run in the same session.
When the request includes `attachments`, each `attachments[].attachmentId` must reference a file already uploaded in this session. Send the upload `sessionId` as the `session-id` header. The attachment must already be attached to the `agentId` in the request body. After a file upload, send that same path `agentId` in the chat body. After reuse, send the target agent''s path `agentId` in the chat body. If they differ, the request returns `400`. To use the file with a different agent, first assign the attachment to that agent with `attachmentId` on `POST /ai-service/{tenant}/agentic/{agentId}/attachments` using the target `agentId` in the path, then chat with that target agent.'
security:
- OAuth2:
- ai.agentexecution_manage_own
- ai.agentexecution_manage
requestBody:
$ref: '#/components/requestBodies/AgenticChat'
tags:
- Agent Chat
servers:
- url: https://api.emporix.io
/ai-service/{tenant}/agentic/{agentId}/attachments:
parameters:
- $ref: '#/components/parameters/path_tenant'
- schema:
type: string
name: agentId
in: path
required: true
description: Unique identifier of the agent that receives the attachment. For a file upload, a later chat request must send this same value in the body `agentId` field. When you reuse an attachment, this path value is the target agent. The later chat request must send that target `agentId`.
- $ref: '#/components/parameters/header_session-id'
post:
summary: Uploading attachment
operationId: POST-ai-agents-upload-attachment
responses:
'201':
description: Attachment created.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentResponse'
examples:
AttachmentId:
value:
id: 68835cc3ef4e8e1425c360ad
sessionId: 0499bef6-a4d2-45b9-86a0-2edf7d70d726
'200':
description: Existing media assigned to the agent. The body contains the attachment `id` and the `sessionId` to send on later chat requests.
content:
application/json:
schema:
$ref: '#/components/schemas/AttachmentResponse'
examples:
AttachmentId:
value:
id: 68835cc3ef4e8e1425c360ad
sessionId: 0499bef6-a4d2-45b9-86a0-2edf7d70d726
'400':
$ref: '#/components/responses/400_resp_common'
'401':
$ref: '#/components/responses/401_resp_common'
'403':
$ref: '#/components/responses/403_resp_common'
'500':
$ref: '#/components/responses/500_resp_common'
description: 'Uploads a new file and assigns it to the agent, or assigns an existing media asset to the agent.
Send exactly one of `attachment` or `attachmentId`. Sending both or neither returns `400`.
**Upload a file:** Send the `attachment` form field. The response is `201` with the new attachment `id` and `sessionId`. Supported file extensions:
- jpg
- jpeg
- png
- pdf
- csv
- text
- txt
**Assign existing media:** Send `attachmentId` and the target agent''s `agentId` in the path. Use either the `attachmentId` form field or an `application/json` body with `attachmentId`. The response is `200` with the attachment `id` and `sessionId`. If you omit the `session-id` header, the response includes the generated `sessionId`.
With the `ai.agentexecution_manage` scope, `attachmentId` can be any existing media asset. The asset does not have to belong to the session and does not have to already have references. AI Service adds an `AGENT` reference and attaches the file to the session in the response.
With only the `ai.agentexecution_manage_own` scope, the attachment must already belong to the `session-id` session.
**Chat with the attachment:** Call the Starting agent chat, Starting agent chat stream, or Starting agent async chat endpoint. Send the returned `sessionId` as the `session-id` header and the path `agentId` in the chat body. If the chat `agentId` is not the agent in this path, the API returns `400` with the message `Agent chat attachment with id={attachmentId} cannot be used to chat with agentId={agentId}`.'
security:
- OAuth2:
- ai.agentexecution_manage_own
- ai.agentexecution_manage
requestBody:
required: true
content:
multipart/form-data:
schema:
oneOf:
- type: object
required:
- attachment
additionalProperties: false
properties:
attachment:
type: string
format: binary
description: Content of the file. Use this field to upload a new file.
- type: object
required:
- attachmentId
additionalProperties: false
properties:
attachmentId:
type: string
description: Identifier of an existing media asset. With `ai.agentexecution_manage`, any media id can be assigned to the path agent. With only `ai.agentexecution_manage_own`, the attachment must already belong to the session.
application/json:
schema:
type: object
required:
- attachmentId
additionalProperties: false
properties:
attachmentId:
type: string
description: Identifier of an existing media asset. With `ai.agentexecution_manage`, any media id can be assigned to the path agent. With only `ai.agentexecution_manage_own`, the attachment must already belong to the session.
tags:
- Agent Chat
servers:
- url: https://api.emporix.io
components:
schemas:
AttachmentResponse:
type: object
properties:
id:
type: string
description: Unique identifier of the created attachment.
sessionId:
type: string
description: Unique identifier of the session the attachment is on. Send this value as the `session-id` header on later chat requests. If the assign request omits `session-id`, this value is the generated session.
ErrorMessage:
type: object
properties:
code:
type: integer
type:
type: string
message:
type: string
moreInfo:
type: string
details:
type: array
items:
type: object
properties:
field:
type: string
type:
type: string
message:
type: string
moreInfo:
type: string
description: ''
ErrorMessageFault:
type: object
properties:
fault:
type: object
properties:
faultstring:
type: string
detail:
type: object
properties:
errorcode:
type: string
AgentType:
type: string
description: Type of the agent handling the request.
enum:
- generic
- complaint
- anti_fraud
ChatResponse:
type: object
properties:
agentId:
type: string
description: Unique identifier of the agent.
agentType:
$ref: '#/components/schemas/AgentType'
sessionId:
type: string
description: Unique identifier of the session. Send this value back as the `session-id` header on later chat and attachment calls.
message:
type: string
description: Agent message.
JobIdResponse:
type: object
properties:
jobId:
type: string
description: Identifier of the job.
AgenticRequest:
type: object
properties:
agentId:
type: string
description: Unique identifier of the agent.
message:
type: string
description: The user message to the agent.
attachments:
type: array
items:
type: object
properties:
attachmentId:
type: string
description: Identifier returned by the upload. Required for each attached file. The attachment must belong to the current session and be attached to this request's `agentId`.
caption:
type: string
description: Caption of the attachment.
purpose:
type: string
description: Purpose of the attachment.
required:
- attachmentId
required:
- agentId
- message
parameters:
header_session-id:
name: session-id
in: header
required: false
schema:
type: string
format: uuid
description: 'Optional UUID of the AI Service chat session. If omitted, the system generates one.
Reuse the same value on later chat and attachment calls to continue the same session, access attachments from that session, and keep conversational memory when `enabledMemory` is `true` on the agent. A new value starts a new session.
On [Starting agent chat](https://developer.emporix.io/api-documentation/api-guides/artificial-intelligence/ai-service/api-reference/agent-chat#post-ai-service-tenant-agentic-chat), the value is `sessionId` in the JSON response. On [Starting agent chat stream](https://developer.emporix.io/api-documentation/api-guides/artificial-intelligence/ai-service/api-reference/agent-chat#post-ai-service-tenant-agentic-chat-stream), the value is `session_id` in the SSE `done` event. When a chat request includes `attachments`, send the same value returned as `sessionId` from the upload or from assigning existing media. Do not send `sessionId` in the request body. Omitting `session-id` when you assign media starts a new session and returns that `sessionId`.
'
path_tenant:
name: tenant
in: path
required: true
schema:
type: string
description: 'Your Emporix tenant name.
**Note**: The tenant name should always be provided in lowercase.
'
responses:
403_resp_common:
description: Authorization scopes of the access token are not sufficient and do not match the scopes required by the endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Access forbidden:
value:
code: 403
status: Forbidden
message: The access to the requested resource has been forbidden by the server.
401_resp_common:
description: The authorization token is invalid or has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessageFault'
examples:
Invalid access token:
value:
fault:
faultstring: Invalid access token
detail:
errorcode: oauth.v2.InvalidAccessToken
Access token expired:
value:
fault:
faultstring: Access Token expired
detail:
errorcode: keymanagement.service.access_token_expired
400_resp_common:
description: The request was syntactically incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Code must not be null:
value:
code: 400
status: Bad Request
message: Validation problem with request body.
details:
- message: code must not be null nor blank
500_resp_common:
description: A server-side error occurred.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
examples:
Internal Server Error:
value:
code: 500
status: Internal Server Error
message: Problem encountered while trying to connect to the database.
requestBodies:
AgenticChat:
content:
application/json:
schema:
$ref: '#/components/schemas/AgenticRequest'
examples:
Agentic Chat request:
value:
agentId: complaint-agent
message: Find a product with "EON1243" code
Agentic Chat with attachment:
value:
agentId: order-assistant-agent
message: Find products or equivalents from the attached order request and create an order for the customer
attachments:
- attachmentId: 6a1d5961a8c0af22364a2c54
caption: Order Request
purpose: Serves as a basis to create an order with the data, customer, and products mentioned in the file.
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
scopes:
ai.text_manage: Needed to execute actions related to the text generation.
ai.completion_manage: Needed to execute actions related to the AI completions.
ai.agentexecution_manage: Needed to execute agentic chat.
ai.agentexecution_manage_own: Needed to execute agentic chat by customers.
ai.agent_read: Needed to read AI agents.
ai.agent_manage: Needed to manage AI agents.
tokenUrl: https://api.emporix.io/oauth/token
x-refined-from:
- emporix-ai-service-openapi.yml
- emporix-ai-service-openapi.yml