> ## Documentation Index > Fetch the complete documentation index at: https://docs.suppio.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an agent response > Send one support message with optional base64 image attachments and caller-defined function tools to a Suppio agent. The response includes the agent answer, usage, built-in action signals, and recorded custom tool calls your backend can handle. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/agents/{agentId}/responses openapi: 3.1.0 info: title: Suppio Agent API description: >- Call a Suppio agent from trusted backend code with text, optional base64 image attachments, and optional caller-defined function tools, then receive a support response with structured action signals and tool calls. version: 1.2.0 servers: - url: https://api.suppio.ai description: Production API host. security: - bearerAuth: [] paths: /v1/agents/{agentId}/responses: post: summary: Create an agent response description: >- Send one support message with optional base64 image attachments and caller-defined function tools to a Suppio agent. The response includes the agent answer, usage, built-in action signals, and recorded custom tool calls your backend can handle. operationId: createAgentResponse parameters: - name: agentId in: path required: true description: >- The Suppio agent ID. The bearer API key must be scoped to this same agent. schema: type: string example: agent_123 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentResponseRequest' examples: passwordReset: summary: Password reset question value: message: How do I reset my password? imageQuestion: summary: Question with an image attachment value: message: What does this error screenshot mean? attachments: - type: image name: error.png media_type: image/png data: iVBORw0KGgoAAAANSUhEUgAA... customTool: summary: Support request with a caller-defined tool value: message: Please have a support agent contact me. tools: - type: function name: create_ticket description: Create a support ticket. instructions: Call when the user needs human follow-up. strict: true parameters: type: object properties: priority: type: string enum: - low - high required: - priority additionalProperties: false responses: '200': description: >- The request was processed. Check `outcome` for `success` or `blocked`. headers: X-RateLimit-Limit: description: The request limit for the current one-minute window. schema: type: integer X-RateLimit-Remaining: description: Remaining requests in the current one-minute window. schema: type: integer X-RateLimit-Reset: description: Unix timestamp when the current rate-limit window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/AgentResponse' examples: success: summary: Successful support answer value: outcome: success response: I’ll pass this to the support team. actions: - type: escalate_to_human reason: The user requested human follow-up. tool_calls: - name: create_ticket arguments: priority: high usage: credits: 12 tokens: 1234 blocked: summary: Blocked response value: outcome: blocked response: I can't help with that request. actions: [] tool_calls: [] usage: credits: 2 tokens: 120 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/OutOfCredits' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/AgentNotFound' '409': $ref: '#/components/responses/ContextRequired' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: CreateAgentResponseRequest: type: object additionalProperties: false required: - message properties: message: type: string description: >- The support message. Empty messages are rejected. Input is capped at 12,000 characters after trimming. minLength: 1 maxLength: 12000 example: How do I reset my password? attachments: type: array description: >- Optional base64-encoded image inputs. Images count toward input tokens and Suppio credit usage. maxItems: 5 items: $ref: '#/components/schemas/ImageAttachment' tools: type: array description: >- Optional caller-defined action-signal tools for this request. Up to 10 tools are allowed. Each parameters schema is limited to 16 KB, and the complete tools array is limited to 64 KB. maxItems: 10 items: $ref: '#/components/schemas/CustomFunctionTool' AgentResponse: type: object required: - outcome - response - actions - tool_calls - usage properties: outcome: type: string enum: - success - blocked response: type: string actions: type: array items: $ref: '#/components/schemas/ActionSignal' tool_calls: type: array description: >- Caller-defined tool calls recorded during the agent run. Blocked responses return an empty array. items: $ref: '#/components/schemas/CustomToolCall' usage: $ref: '#/components/schemas/Usage' ImageAttachment: type: object additionalProperties: false required: - type - media_type - data properties: type: type: string const: image name: type: string maxLength: 120 description: Optional display name for the image. media_type: type: string enum: - image/png - image/jpeg - image/webp - image/gif data: type: string contentEncoding: base64 maxLength: 6990508 description: >- Raw base64 image data without a data URL prefix. Each decoded image is limited to 5 MB, and all decoded images are limited to 10 MB per request. CustomFunctionTool: type: object additionalProperties: false required: - type - name - description - instructions - parameters properties: type: type: string const: function name: type: string minLength: 1 maxLength: 64 pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$ description: >- A request-unique function name. Suppio-owned tool names are reserved. description: type: string minLength: 1 maxLength: 1024 description: A concise description of the function's purpose. instructions: type: string minLength: 1 maxLength: 4000 description: >- When and how the agent should call the function. Suppio appends these instructions to the agent instructions for this request. strict: type: boolean const: true default: true description: May be omitted or true. Non-strict tools are rejected. parameters: type: object description: >- A strict object JSON Schema. Every object must set additionalProperties to false and list every property in required. required: - type - properties - required - additionalProperties properties: type: type: string const: object properties: type: object additionalProperties: true required: type: array items: type: string additionalProperties: type: boolean const: false additionalProperties: true ActionSignal: oneOf: - $ref: '#/components/schemas/EscalateToHumanAction' - $ref: '#/components/schemas/MarkResolvedAction' - $ref: '#/components/schemas/SuggestTitleAction' CustomToolCall: type: object additionalProperties: false required: - name - arguments properties: name: type: string description: The caller-defined function name. arguments: type: object additionalProperties: true description: >- Arguments generated according to the function's strict parameters schema. Usage: type: object required: - credits - tokens properties: credits: type: integer minimum: 0 tokens: type: integer minimum: 0 ApiError: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string examples: - invalid_request - invalid_tools - context_required - out_of_credits message: type: string EscalateToHumanAction: type: object required: - type - reason properties: type: type: string const: escalate_to_human reason: type: string MarkResolvedAction: type: object required: - type - reason properties: type: type: string const: mark_resolved reason: type: string SuggestTitleAction: type: object required: - type - reason - title properties: type: type: string const: suggest_title reason: type: string title: type: string description: A short support title for routing or labeling the conversation. responses: BadRequest: description: The request body was invalid. content: application/json: schema: $ref: '#/components/schemas/ApiError' Unauthorized: description: Authentication is missing or the API key is invalid. content: application/json: schema: $ref: '#/components/schemas/ApiError' OutOfCredits: description: The workspace is out of credits. content: application/json: schema: $ref: '#/components/schemas/ApiError' Forbidden: description: The key is scoped to another agent, or the requested agent is disabled. content: application/json: schema: $ref: '#/components/schemas/ApiError' AgentNotFound: description: The requested agent was not found for this key. content: application/json: schema: $ref: '#/components/schemas/ApiError' ContextRequired: description: The agent has no active context. content: application/json: schema: $ref: '#/components/schemas/ApiError' PayloadTooLarge: description: The JSON body exceeded 16 MB. content: application/json: schema: $ref: '#/components/schemas/ApiError' RateLimited: description: The key or agent exceeded a rate limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ApiError' InternalError: description: Suppio could not generate the response. content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: suppio_live API key ````