> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a result for a ready custom tool call > Only ready custom tool calls accept externally supplied results. The first accepted result completes the call. Any later submission, or a result for a non-custom tool call, returns 409. ## OpenAPI ````yaml /api-reference/openapi.yaml post /orgs/{orgID}/projects/{projectID}/agents/{agentID}/tool-calls/{toolCallID}/result openapi: 3.1.2 info: title: Omnara API version: 0.1.0 description: Public HTTP API contract for Omnara. servers: - url: https://api.omnara.com/v1 description: Hosted Omnara - url: /api/v1 description: Self-hosted Omnara, relative to the deployment origin security: - bearerAuth: [] - browserSessionCookie: [] tags: - name: Agents description: >- Launch agents, send inputs, manage the input backlog, and work with tool calls. externalDocs: description: Guide url: https://docs.omnara.com/agents/overview - name: Interactions description: List and resolve the approvals and questions that pause an agent. externalDocs: description: Guide url: https://docs.omnara.com/events/interactions - name: Actors description: Attribute agent inputs and interaction responses to external users. externalDocs: description: Guide url: >- https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution - name: Events description: Read or stream the agent timeline, list turns, and download artifacts. externalDocs: description: Guide url: https://docs.omnara.com/events/streaming - name: Configs and Profiles description: >- Create agent configs, manage reusable launch profiles, and set up integrations. externalDocs: description: Guide url: https://docs.omnara.com/agents/configuration - name: Integrations description: >- Connect project integrations, route conversations, and manage launch settings. externalDocs: description: Guide url: https://docs.omnara.com/integrations/overview - name: Models description: Configure model providers and models, and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/organization/model-providers - name: Machines description: Register machines, control project access, and manage daemon tokens. externalDocs: description: Guide url: https://docs.omnara.com/machines/connect - name: Machine Pools description: Define machine pools and grant projects access to them. externalDocs: description: Guide url: https://docs.omnara.com/machines/pools - name: Secrets description: >- Manage secret ownership and versions, and inspect or grant project availability. externalDocs: description: Guide url: https://docs.omnara.com/organization/secrets - name: Skills description: Manage versioned skill ownership and load skill instructions on demand. externalDocs: description: Guide url: https://docs.omnara.com/tools/skills - name: Organizations and Projects description: Create organizations and projects and manage membership. externalDocs: description: Guide url: https://docs.omnara.com/organization/members - name: Users and API Keys description: >- The authenticated user, personal and organization API keys, and invitations. externalDocs: description: Guide url: https://docs.omnara.com/api/authentication - name: Machine Daemon description: Routes the Omnara machine daemon uses to connect a machine. paths: /orgs/{orgID}/projects/{projectID}/agents/{agentID}/tool-calls/{toolCallID}/result: parameters: - name: orgID in: path description: Organization ID (org_...). required: true schema: type: string pattern: ^org_[a-z2-7]{26}$ - name: projectID in: path description: Project ID (proj_...). required: true schema: type: string pattern: ^proj_[a-z2-7]{26}$ - name: agentID in: path description: Agent ID (agt_...). required: true schema: type: string pattern: ^agt_[a-z2-7]{26}$ - name: toolCallID in: path description: Tool call ID (tcl_...). required: true schema: $ref: '#/components/schemas/ToolCallID' post: tags: - Agents summary: Submit a result for a ready custom tool call description: >- Only ready custom tool calls accept externally supplied results. The first accepted result completes the call. Any later submission, or a result for a non-custom tool call, returns 409. operationId: submitToolCallResult requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitToolCallResultRequest' responses: '201': description: Custom tool result accepted and tool call completed. content: application/json: schema: $ref: '#/components/schemas/SubmitToolCallResultResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '503': $ref: '#/components/responses/ServiceUnavailable' 4XX: $ref: '#/components/responses/ClientError' 5XX: $ref: '#/components/responses/ServerError' security: - bearerAuth: [] - browserSessionCookie: [] csrfHeader: [] components: schemas: ToolCallID: type: string pattern: ^tcl_[a-z2-7]{26}$ SubmitToolCallResultRequest: type: object additionalProperties: false required: - outcome - content_blocks properties: outcome: type: string enum: - succeeded - failed description: Whether the custom tool call succeeded or failed. content_blocks: type: array description: >- At most 20 inline media blocks per submission, each holding up to 10 MiB of decoded media and up to 24 MiB decoded across the submission. Non-media blocks may hold up to 1 MiB combined. The whole request body is capped at 48 MiB. items: $ref: '#/components/schemas/SubmitToolResultContentBlock' SubmitToolCallResultResponse: type: object additionalProperties: false required: - tool_call - tool_result properties: tool_call: $ref: '#/components/schemas/ToolCall' tool_result: $ref: '#/components/schemas/ToolResult' SubmitToolResultContentBlock: description: >- Submission accepts inline media. The persisted response exposes that media as a `media_ref` block. oneOf: - $ref: '#/components/schemas/TextContentBlock' - $ref: '#/components/schemas/InlineMediaContentBlock' - $ref: '#/components/schemas/StructuredDataContentBlock' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContentBlock' media: '#/components/schemas/InlineMediaContentBlock' structured_data: '#/components/schemas/StructuredDataContentBlock' ToolCall: description: A model-emitted tool call together with its current lifecycle state. type: object additionalProperties: false required: - id - agent_id - turn_id - provider_call_id - name - input - type - state - created_at properties: id: $ref: '#/components/schemas/ToolCallID' agent_id: $ref: '#/components/schemas/AgentID' turn_id: $ref: '#/components/schemas/AgentTurnID' provider_call_id: type: string name: type: string input: $ref: '#/components/schemas/ToolInput' type: $ref: '#/components/schemas/ToolCallType' state: $ref: '#/components/schemas/ToolCallState' outcome: $ref: '#/components/schemas/ToolCallOutcome' completed_at: $ref: '#/components/schemas/Timestamp' created_at: $ref: '#/components/schemas/Timestamp' ToolResult: type: object additionalProperties: false required: - event_id - agent_id - tool_call_id - outcome - content_blocks - created_at properties: event_id: $ref: '#/components/schemas/AgentEventID' agent_id: $ref: '#/components/schemas/AgentID' tool_call_id: $ref: '#/components/schemas/ToolCallID' outcome: $ref: '#/components/schemas/ToolCallOutcome' content_blocks: type: array items: $ref: '#/components/schemas/ToolResultContentBlock' created_at: $ref: '#/components/schemas/Timestamp' Error: type: object additionalProperties: false required: - error - code properties: error: type: string description: Human-readable error message. Do not match on it programmatically. current_digest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: >- Current file digest for file_content_conflict or expected_digest_required; absent if the file no longer exists. A replacement must be confirmed before retrying with this digest. issues: type: array description: >- Field-level problems when a submitted document (such as an agent config source) failed validation. Absent for errors that are not about a specific field. items: $ref: '#/components/schemas/AgentConfigErrorIssue' code: type: string description: Stable error code for programmatic handling. x-go-type: ErrorCode x-extensible-enum: - invalid_request - unauthorized - forbidden - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - gone - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited - internal_error - service_unavailable - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - managed_work_admission_denied - pending_work - not_wake_capable - daemon_runtime_unregistered - validation_failed - csrf_check_failed - authentication_unavailable ClientErrorCode: type: string description: >- Stable error code carried by 4XX statuses. Subset of the Error code enum whose statuses are client errors. x-extensible-enum: - invalid_request - validation_failed - unauthorized - forbidden - csrf_check_failed - not_found - conflict - file_content_conflict - file_read_only - expected_digest_required - not_a_file - idempotency_key_conflict - agent_backlog_full - state_transition_conflict - pending_work - not_wake_capable - gone - daemon_runtime_unregistered - request_too_large - unsupported_media_type - unprocessable - upstream_unavailable - rate_limited ServerErrorCode: type: string description: >- Stable error code carried by 5XX statuses. Subset of the Error code enum whose statuses are server errors. x-extensible-enum: - internal_error - service_unavailable - authentication_unavailable TextContentBlock: type: object additionalProperties: false required: - type - text properties: type: type: string enum: - text text: type: string metadata: $ref: '#/components/schemas/ContentBlockMetadata' InlineMediaContentBlock: type: object description: >- Files that pass validation are stored as artifacts. Model input always includes the artifact ID, whether or not the file contents can be sent directly. Text media must contain valid UTF-8 and is sent as text. Images and PDFs are sent directly when supported by the configured provider and model; unsupported combinations are rejected. Other binary documents are sent directly only to OpenAI Responses models with file input support. Chat Completions and Anthropic Messages receive the artifact ID and the filename, if provided, instead of the contents of those documents. additionalProperties: false required: - type - media_type - data properties: type: type: string enum: - media media_type: type: string enum: - image/png - image/jpeg - image/gif - image/webp - application/pdf - text/plain - text/markdown - text/csv - text/tab-separated-values - text/x-iif - application/msword - application/rtf - application/vnd.oasis.opendocument.text - application/vnd.apple.pages - application/vnd.apple.keynote - application/vnd.apple.iwork - application/vnd.ms-powerpoint - application/vnd.ms-excel - >- application/vnd.openxmlformats-officedocument.wordprocessingml.document - >- application/vnd.openxmlformats-officedocument.presentationml.presentation - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet filename: type: string maxLength: 255 data: type: string format: byte minLength: 1 description: >- Base64-encoded file bytes. For text media types, the decoded bytes must be valid UTF-8. metadata: $ref: '#/components/schemas/ContentBlockMetadata' StructuredDataContentBlock: type: object additionalProperties: false required: - type - value properties: type: type: string enum: - structured_data value: $ref: '#/components/schemas/JSONBlob' metadata: $ref: '#/components/schemas/ContentBlockMetadata' AgentID: type: string pattern: ^agt_[a-z2-7]{26}$ AgentTurnID: type: string pattern: ^trn_[a-z2-7]{26}$ ToolInput: description: Non-null JSON object containing the arguments emitted for a tool call. type: object additionalProperties: true x-go-type: json.RawMessage x-go-type-skip-optional-pointer: true ToolCallType: description: >- Identifies who manages execution. Built-in and MCP calls are platform-managed; custom calls wait for an external consumer to submit their result. type: string enum: - built_in - custom - mcp x-enum-varnames: - ToolCallTypeBuiltIn - ToolCallTypeCustom - ToolCallTypeMCP ToolCallState: description: >- Current lifecycle state. awaiting_authorization has not evaluated its permission mode; awaiting_permission has an open authorization prompt; ready is authorized and eligible to run; running has an active worker; waiting has durable work that will complete the call independently; completed is terminal and includes outcome and completed_at. Custom calls remain ready until a consumer submits their result. type: string enum: - awaiting_authorization - awaiting_permission - ready - running - waiting - completed x-enum-varnames: - ToolCallStateAwaitingAuthorization - ToolCallStateAwaitingPermission - ToolCallStateReady - ToolCallStateRunning - ToolCallStateWaiting - ToolCallStateCompleted ToolCallOutcome: description: Terminal outcome, present only when state is completed. type: string enum: - succeeded - failed - denied - canceled x-enum-varnames: - ToolCallOutcomeSucceeded - ToolCallOutcomeFailed - ToolCallOutcomeDenied - ToolCallOutcomeCanceled Timestamp: type: string format: date-time AgentEventID: type: string pattern: ^evt_[a-z2-7]{26}$ ToolResultContentBlock: oneOf: - $ref: '#/components/schemas/TextContentBlock' - $ref: '#/components/schemas/MediaRefContentBlock' - $ref: '#/components/schemas/StructuredDataContentBlock' discriminator: propertyName: type mapping: text: '#/components/schemas/TextContentBlock' media_ref: '#/components/schemas/MediaRefContentBlock' structured_data: '#/components/schemas/StructuredDataContentBlock' AgentConfigErrorIssue: type: object additionalProperties: false required: - path - message properties: path: type: string description: >- JSON Pointer (RFC 6901) to the offending field in the submitted document. An empty string refers to the whole document. message: type: string description: Human-readable description of the problem with this field. line: type: integer minimum: 1 description: >- 1-based line of the offending field in the submitted source, when it can be located. column: type: integer minimum: 1 description: >- 1-based column of the offending field in the submitted source, when it can be located. ContentBlockMetadata: $ref: '#/components/schemas/Metadata' description: >- Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters. Keys beginning with `omnara_` are reserved for Omnara and may affect product behavior; use them only when intentionally invoking Omnara-defined behavior. JSONBlob: description: >- Public JSON payload whose shape is determined by the event or interaction kind. MediaRefContentBlock: type: object additionalProperties: false required: - type - artifact_id properties: type: type: string enum: - media_ref artifact_id: $ref: '#/components/schemas/ArtifactID' exclude_from_model_context: type: boolean description: >- Whether the referenced artifact is excluded from later model context. metadata: $ref: '#/components/schemas/ContentBlockMetadata' Metadata: type: object description: >- Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 characters, values must be strings of up to 512 characters. x-go-type: resourcemeta.Metadata x-go-type-import: path: github.com/omnara-ai/omnara/internal/resourcemeta x-go-type-skip-optional-pointer: true maxProperties: 16 propertyNames: minLength: 1 maxLength: 64 additionalProperties: type: string maxLength: 512 ArtifactID: type: string pattern: ^art_[a-z2-7]{26}$ responses: BadRequest: description: The request was invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Authentication is required or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The authenticated principal is not authorized. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found or is not visible. content: application/json: schema: $ref: '#/components/schemas/Error' Conflict: description: >- The request conflicts with current resource state or idempotency history. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: The service dependency required to satisfy the request is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' ClientError: description: >- Any other client error. The body carries the shared Error envelope restricted to client error codes; statuses with a dedicated response above are documented precisely. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ClientErrorCode' ServerError: description: >- Any other server error. The body carries the shared Error envelope restricted to server error codes. content: application/json: schema: type: object additionalProperties: false required: - error - code properties: error: type: string description: >- Human-readable error message. Do not match on it programmatically. code: $ref: '#/components/schemas/ServerErrorCode' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Omnara personal or organization access token description: An opaque Omnara personal or organization bearer token. browserSessionCookie: type: apiKey in: cookie name: __Host-omnara_session description: >- Browser session cookie. HTTPS deployments use __Host-omnara_session; local HTTP development uses omnara_session. csrfHeader: type: apiKey in: header name: X-Omnara-Csrf description: >- CSRF token header required for browser-session mutations. The value must match the session's CSRF cookie. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.