> ## 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. # List agent interactions > Lists an agent's permission prompts and ask_question questions, oldest first, with each one's form and answers. state filters by open, resolved, or canceled. ## OpenAPI ````yaml /api-reference/openapi.yaml get /orgs/{orgID}/projects/{projectID}/agents/{agentID}/interactions 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}/interactions: 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}$ get: tags: - Interactions summary: List agent interactions description: >- Lists an agent's permission prompts and ask_question questions, oldest first, with each one's form and answers. state filters by open, resolved, or canceled. operationId: listAgentInteractions parameters: - name: state in: query required: false schema: $ref: '#/components/schemas/AgentInteractionState' - name: include_subagents in: query required: false description: >- Also return interactions from every subagent beneath this agent. Resolve those against the subagent's own agent_id. schema: type: boolean - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/PageCursor' responses: '200': description: Agent interactions. content: application/json: schema: $ref: '#/components/schemas/ListAgentInteractionsResponse' '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' components: schemas: AgentInteractionState: type: string enum: - open - resolved - canceled x-enum-varnames: - AgentInteractionStateOpen - AgentInteractionStateResolved - AgentInteractionStateCanceled ListAgentInteractionsResponse: type: object additionalProperties: false required: - data - next_cursor properties: data: type: array items: $ref: '#/components/schemas/AgentInteraction' next_cursor: type: - string - 'null' AgentInteraction: type: object additionalProperties: false required: - id - org_id - project_id - agent_id - tool_call_id - interaction_kind - state - request - created_at properties: id: $ref: '#/components/schemas/AgentInteractionID' org_id: $ref: '#/components/schemas/OrganizationID' project_id: $ref: '#/components/schemas/ProjectID' agent_id: $ref: '#/components/schemas/AgentID' tool_call_id: $ref: '#/components/schemas/ToolCallID' description: >- The tool call that is waiting on this interaction — the guarded tool for a permission, or the ask_question call for a question. tool_name: type: string description: >- The tool whose invocation a permission interaction guards. Present only when interaction_kind is permission. agent_name: $ref: '#/components/schemas/AgentName' subagent_key: type: string description: >- Present when the interaction belongs to a subagent of the listed agent. interaction_kind: $ref: '#/components/schemas/AgentInteractionKind' state: $ref: '#/components/schemas/AgentInteractionState' request: $ref: '#/components/schemas/InteractionForm' resolution: $ref: '#/components/schemas/InteractionResolution' destination: $ref: '#/components/schemas/AgentInteractionDestination' description: >- Captured built-in integration destination. Absent for dashboard-only or older interactions; never reconstructed from the current agent selection. presentation_receipt: $ref: '#/components/schemas/InteractionPresentationReceipt' resolved_by_input_id: $ref: '#/components/schemas/AgentInputID' description: >- The agent input that resolved the interaction — the submitted response, the content input that superseded it, or the cancel control input. Absent on open interactions and on resolutions without an attributed input. The input's actor_id attributes the resolution. created_at: $ref: '#/components/schemas/Timestamp' resolved_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 AgentInteractionID: type: string pattern: ^int_[a-z2-7]{26}$ OrganizationID: type: string pattern: ^org_[a-z2-7]{26}$ ProjectID: description: Project ID (proj_...). type: string pattern: ^proj_[a-z2-7]{26}$ AgentID: type: string pattern: ^agt_[a-z2-7]{26}$ ToolCallID: type: string pattern: ^tcl_[a-z2-7]{26}$ AgentName: type: string maxLength: 64 x-omnara-unicode-normalization: NFC description: >- Agent name. Empty means the agent is unnamed; non-empty values use the ResourceName policy. AgentInteractionKind: type: string enum: - permission - question x-enum-varnames: - AgentInteractionKindPermission - AgentInteractionKindQuestion InteractionForm: type: object additionalProperties: false required: - title - questions properties: title: type: string minLength: 1 context: type: array items: $ref: '#/components/schemas/InteractionFormContextItem' questions: type: array minItems: 1 items: $ref: '#/components/schemas/InteractionFormQuestion' InteractionResolution: type: object additionalProperties: false required: - answers properties: answers: type: array minItems: 1 description: Answers in the same order as the interaction form's questions. items: $ref: '#/components/schemas/InteractionAnswer' AgentInteractionDestination: type: object additionalProperties: false required: - integration_kind - handler_key - integration_id - integration_target_id - conversation description: >- Immutable handler and destination captured when the interaction was created. Provider delivery and callbacks check current integration and handler authority. Dashboard/API resolution remains available independently. properties: integration_kind: $ref: '#/components/schemas/IntegrationKind' handler_key: type: string integration_id: $ref: '#/components/schemas/IntegrationID' integration_target_id: $ref: '#/components/schemas/IntegrationTargetID' conversation: $ref: '#/components/schemas/IntegrationConversation' InteractionPresentationReceipt: type: object additionalProperties: true description: >- Confirmed provider presentation metadata, when recorded. This is not an execution grant or a delivery guarantee. Absence does not prove a remote send failed. Customer-hosted presenters maintain their own delivery records. AgentInputID: type: string pattern: ^ain_[a-z2-7]{26}$ Timestamp: type: string format: date-time 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. InteractionFormContextItem: type: object additionalProperties: false required: - label - value properties: label: type: string minLength: 1 value: type: string minLength: 1 InteractionFormQuestion: type: object additionalProperties: false required: - prompt - options properties: prompt: type: string minLength: 1 multiple: type: boolean default: false x-go-type-skip-optional-pointer: true description: Whether the answer may select more than one option. options: type: array minItems: 1 items: $ref: '#/components/schemas/InteractionFormOption' InteractionAnswer: type: object additionalProperties: false required: - option_indices properties: option_indices: type: array minItems: 1 uniqueItems: true items: type: integer minimum: 0 text: type: string x-go-type-skip-optional-pointer: true description: Optional companion text when the selected option allows it. IntegrationKind: type: string description: >- Registered integration implementation; independent of the saved integration's name and immutable ID. enum: - slack_thread - discord_thread - github_pr x-enum-varnames: - IntegrationKindSlackThread - IntegrationKindDiscordThread - IntegrationKindGitHubPR IntegrationID: type: string pattern: ^itg_[a-z2-7]{26}$ IntegrationTargetID: type: string pattern: ^itgt_[a-z2-7]{26}$ IntegrationConversation: type: object additionalProperties: true x-go-type: json.RawMessage x-go-type-skip-optional-pointer: true description: >- One concrete provider address, validated by the integration's capabilities.subscription.conversation_schema. Slack uses channel_id and optional thread_ts; Discord uses channel_id for a channel or thread_id for a thread; GitHub uses repository_id and pull_request. Discord accepts optional parent channel_id and guild_id alongside thread_id and validates their ID format, but subscription creation does not verify them against Discord or retain them as routing restrictions. Only thread_id is retained in a canonical thread address and returned by create/list responses. No credentials or runtime state. InteractionFormOption: type: object additionalProperties: false required: - label properties: label: type: string minLength: 1 allows_text: type: boolean default: false x-go-type-skip-optional-pointer: true description: >- Whether the answer may include optional companion text for this option. parameters: PageLimit: name: limit in: query required: false schema: type: integer format: int32 minimum: 1 maximum: 100 default: 50 description: Maximum number of items to return in one page. PageCursor: name: cursor in: query required: false schema: type: string maxLength: 1024 description: >- Opaque pagination cursor from a previous response's next_cursor. Omit for the first page. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.