---
title: "Execute Agent"
method: POST
path: "/api/v1/execute"
tags: ["execute"]
---

# Execute Agent

`POST /api/v1/execute`

## Request

- Base URL: `https://api.gnosari.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gnosari.com/api/v1/execute`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-AUTH-TOKEN`

Execute an agent with a message and return the complete response.

This endpoint provides a synchronous (non-streaming) way to run agents,
perfect for AI helper features like "Improve with AI" buttons.

The agent can be identified by:
- Numeric ID: "123"
- Identifier string: "my-helper-agent"
- URI format: "agent://my-helper-agent"

Optional features:
- **context**: Variables to inject into the message template using {{variable}} syntax
- **response_format**: JSON schema to parse structured output from the response

Returns:
    ExecuteAgentResponse with the agent's complete response and metadata

Raises:
    400: User must have an account
    404: Agent not found
    500: Execution failed

## Request body

- ExecuteAgentRequest: Request schema for agent execution. Supports flexible agent identification and optional structured output.
  - `agent_ref` string, required: Agent ID, identifier, or URI (e.g., '123', 'my-agent', 'agent://my-agent')
  - `message` string, required: Message/prompt to send to the agent
  - `response_format` object, nullable: Optional JSON schema for structured output parsing
  - `context` object, nullable: Optional context variables for template rendering (e.g., {{variable}})

## Response `200`

Successful Response

- ExecuteAgentResponse: Response schema for agent execution. Contains the complete agent response with metadata.
  - `success` boolean, required: Whether execution completed successfully
  - `content` string, required: The agent's response content
  - `structured_output` object, nullable: Parsed structured output if response_format was provided
  - `agent_name` string, required: Name of the executed agent
  - `agent_id` integer, required: ID of the executed agent
  - `execution_time_ms` integer, required: Execution time in milliseconds

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gnosari/apis/gnosari-api.md) · [All operations](https://skmtc.dev/gnosari/apis/gnosari-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gnosari/apis/gnosari-api/revisions/f299cf53ae5f?raw)