> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference/agent-chat.md). # Agent Chat Chat With Agents ## Starting agent chat > 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. ```json {"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"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"}}}},"schemas":{"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."}}},"AgentType":{"type":"string","description":"Type of the agent handling the request.","enum":["generic","complaint","anti_fraud"]},"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"}}}}}}},"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"]}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"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"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat":{"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"}}}}},"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.\n\nWhen 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.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}} ``` ## Starting agent chat stream > 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. ```json {"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"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"}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"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"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"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"}}}}}}},"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"]}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat-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`"}}}},"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.\n\nWhen 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.\n\nThe 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.\n\nNamed events:\n\n* `token` — Incremental text of the assistant reply. `data` is `{ \"content\": \"...\" }`.\n* `thinking` — **The `thinking` event is in preview mode** - some of the features may not be fully operational yet.\n\n Optional reasoning text. `data` is `{ \"content\": \"...\" }`. Do not treat this as part of the user-facing reply unless the client displays reasoning.\n* `tool_start` — The agent started a tool. `data` is `{ \"tool_name\": \"...\", \"tool_call_id\": \"...\" }`.\n* `tool_end` — The agent finished a tool. `data` uses the same fields as `tool_start`.\n* `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.\n* `done` — The stream completed. `data` includes `agent_id`, `agent_type`, and `session_id` when present. At least one of these fields is sent.\n* `error` — **The `error` event is in preview mode** - some of the features may not be fully operational yet.\n\n A failure during generation. `data` includes `message` and/or `code`. Example codes are `AGENT_SETUP` and `RECURSION_LIMIT`.\n\nSSE `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`).\n\nHTTP `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.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}} ``` ## Starting agent async chat > 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. ```json {"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"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"}}}},"schemas":{"JobIdResponse":{"type":"object","properties":{"jobId":{"type":"string","description":"Identifier of the job."}}},"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"}}}}}}},"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"]}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"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"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"requestBodies":{"AgenticChat":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticRequest"}}}}}},"paths":{"/ai-service/{tenant}/agentic/chat-async":{"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"}}}},"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.\n\nWhen 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.","requestBody":{"$ref":"#/components/requestBodies/AgenticChat"},"tags":["Agent Chat"]}}}} ``` ## Uploading attachment > 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}\`. ```json {"openapi":"3.0.0","info":{"title":"AI Service","version":"0.0.1"},"tags":[{"name":"Agent Chat","description":"Chat With Agents"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["ai.agentexecution_manage_own","ai.agentexecution_manage"]}],"components":{"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"}}}},"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"}}}}}}}},"responses":{"400_resp_common":{"description":"The request was syntactically incorrect.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401_resp_common":{"description":"The authorization token is invalid or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessageFault"}}}},"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"}}}},"500_resp_common":{"description":"A server-side error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"paths":{"/ai-service/{tenant}/agentic/{agentId}/attachments":{"post":{"summary":"Uploading attachment","operationId":"POST-ai-agents-upload-attachment","responses":{"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"}}}},"201":{"description":"Attachment created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachmentResponse"}}}},"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.\n\nSend exactly one of `attachment` or `attachmentId`. Sending both or neither returns `400`.\n\n**Upload a file:** Send the `attachment` form field. The response is `201` with the new attachment `id` and `sessionId`. Supported file extensions:\n - jpg\n - jpeg\n - png\n - pdf\n - csv\n - text\n - txt\n\n**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`.\n\nWith 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.\n\nWith only the `ai.agentexecution_manage_own` scope, the attachment must already belong to the `session-id` session.\n\n**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}`.","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"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.emporix.io/api-references/readme/api-reference/agent-chat.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.