> ## Documentation Index > Fetch the complete documentation index at: https://docs.gennia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send agent message (sync) > Synchronously sends a message to the agent's published version and blocks until the agent finishes (or `timeoutSeconds` expires). Auto-creates a conversation when `conversationId` is omitted. Response includes token usage and cost. ## OpenAPI ````yaml /api-reference/openapi.json post /public/api/v1/agents/{agentPublicId}/messages openapi: 3.1.0 info: contact: email: support@gennia.ai name: Gennia Support url: https://gennia.ai description: >- Workspace-scoped API authenticated via workspace API key (header `X-Api-Key: gsk_...` or `Authorization: Bearer gsk_...`). title: Gennia Public API version: v1 servers: - description: Production url: https://api.gennia.ai security: - workspaceApiKey: [] tags: - description: Slash commands available inside the agent chat. name: Agent Commands - description: Link skills to an agent. name: Agent Skills - description: Read/rename/delete workspace knowledge sources. name: Knowledge Sources - description: Link knowledge sources to an agent. name: Agent Knowledge Sources - description: Workspace CRUD for HTTP/DB/Custom tools. name: HTTP Tools - description: Read/write the agent's model selection + capabilities. name: Agent Model - description: Discover trigger types available for Native MCP toolkits. name: Native MCP Triggers - description: Discover and toggle capability features. name: Agent Features - description: Hub access settings. name: Hub Access - description: Read conversation history and delete conversations. name: Conversations - description: Send messages to a published agent. name: Messages - description: Workspace CRUD for External MCP servers. name: External MCPs - description: Hub billing — plans, coupons, credit packages. name: Billing - description: External links shown in the hub menu. name: Hub External Links - description: Link Native MCP (Composio) instances to an agent. name: Agent Native MCPs - description: Manage AI agents in the workspace bound to the API key. name: Agents - description: Read published version snapshots and restore. name: Agent Versions - description: Read/rename/delete workspace skills. name: Skills - description: Manage hub end-customers (client workspaces). name: Clients - description: Hub domain (subdomain) management. name: Hub Domain - description: Read/write the agent's prompt context. name: Agent Prompt - description: Scheduled / trigger-based runs of an agent. name: Agent Automations - description: Link HTTP/DB/Custom tools to an agent. name: Agent HTTP Tools - description: Hub identity, branding, logos and overall configuration. name: Hub - description: Discover AI models available to this workspace. name: AI Models - description: Discover channel types and their config schemas. name: Channel Types - description: Connect agents to messaging surfaces. name: Agent Channels - description: Link workspace-registered External MCP servers to an agent. name: Agent External MCPs - description: Workspace-scoped public API (API key authentication) name: Public API - description: Dynamic-prompt variable definitions. name: Agent Variables - description: Link sub-agents as delegation targets. name: Agent Sub-agents paths: /public/api/v1/agents/{agentPublicId}/messages: post: tags: - Messages summary: Send agent message (sync) description: >- Synchronously sends a message to the agent's published version and blocks until the agent finishes (or `timeoutSeconds` expires). Auto-creates a conversation when `conversationId` is omitted. Response includes token usage and cost. operationId: sendMessage parameters: - description: Agent public ID in: path name: agentPublicId required: true schema: format: uuid type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SendPublicAgentMessageDTO' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Validation failed / unsupported media type '401': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Missing or invalid API key '404': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Agent or conversation not found '408': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Agent did not finish within timeoutSeconds '422': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Agent not published, conversation paused, attachment too large, etc. '429': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Workspace over monthly operation limit '502': content: application/json: schema: $ref: '#/components/schemas/PublicMessageResponseDTO' description: Upstream (gennia-agents) failure security: - workspaceApiKey: [] components: schemas: SendPublicAgentMessageDTO: description: Body for sending a message to an agent (sync or streaming). properties: attachments: description: Optional attachments to include with this message (max 10). items: $ref: '#/components/schemas/PublicAttachmentDTO' maxItems: 10 minItems: 0 type: array content: description: Message text. May be empty when at least one attachment is provided. example: Hi, can you summarize my latest invoices? maxLength: 32000 minLength: 0 type: string conversationId: description: >- Continue this conversation. Omit to create a new conversation or reuse one for the externalUserId. example: 9c3a4d22-1a8d-4b3f-9b1e-7a0f0c4f3e21 format: uuid type: string externalUserId: description: >- Stable end-user identifier. Auto-generated UUID if omitted on a new conversation. example: user_42 maxLength: 255 minLength: 0 type: string isTest: description: >- Only honored when CREATING a new conversation. true excludes the conversation from the Studio inbox. Ignored when continuing an existing conversation. example: false type: boolean metadata: additionalProperties: type: object description: >- Arbitrary JSON metadata; stored on the conversation (first message only). type: object timeoutSeconds: description: >- Sync-only: max wall-clock seconds to block before returning 408. Ignored by the stream endpoint. example: 60 format: int32 maximum: 300 minimum: 1 type: integer type: object PublicMessageResponseDTO: properties: conversation: $ref: '#/components/schemas/PublicConversationDTO' durationMs: format: int64 type: integer message: $ref: '#/components/schemas/PublicMessageDTO' type: object PublicAttachmentDTO: properties: base64: type: string filename: maxLength: 512 minLength: 0 type: string mediaType: maxLength: 255 minLength: 0 type: string url: maxLength: 2048 minLength: 0 type: string type: object PublicConversationDTO: properties: agentPublicId: format: uuid type: string channel: type: string externalUserId: type: string isEnded: type: boolean isPaused: type: boolean isTest: type: boolean lastMessageAt: format: date-time type: string messageCount: format: int64 type: integer metadata: additionalProperties: type: object type: object publicId: format: uuid type: string startedAt: format: date-time type: string type: object PublicMessageDTO: properties: content: type: string conversationPublicId: format: uuid type: string costOps: format: int32 type: integer costUsd: type: number model: type: string publicId: format: uuid type: string role: type: string sentAt: format: date-time type: string tokenUsage: $ref: '#/components/schemas/PublicTokenUsageDTO' type: object PublicTokenUsageDTO: properties: inputTokens: format: int32 type: integer outputTokens: format: int32 type: integer totalTokens: format: int32 type: integer type: object securitySchemes: workspaceApiKey: in: header name: X-Api-Key type: apiKey ````