# Agent: Prompt **Page:** api/agent/prompt [Download Raw Markdown](./api/agent/prompt.md) --- {/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */} # Agent: Prompt Submit prompts to AI agents and receive responses synchronously, asynchronously via SSE, or via a fully blocking synchronous call. Use these endpoints when you need to send a user or system message to an agent and consume the resulting message stream or final response. Cross-site (browser) requests are blocked on the GET variant — use the POST endpoint from web clients. --- ## `GET /api/v1/agent/prompt` Submit a prompt via query string. Returns an SSE stream by default, or a JSON response if `wait=true`. Cross-site requests are blocked. ### Parameters | Name | In | Type | Required | Description | |------|-----|------|----------|-------------| | `ai` | query | string | Yes | The prompt text to send to the agent | | `sessionID` | query | string | No | Existing session ID (24-character hex) to continue the conversation | | `providerID` | query | string | No | Override the model provider ID | | `modelID` | query | string | No | Override the model ID | | `endpoint` | query | string | No | Override the provider endpoint URL | | `baseURL` | query | string | No | Override the base URL for the request | | `apiKey` | query | string | No | API key for the model provider | | `key` | query | string | No | Alternative API key parameter | | `wait` | query | string | No | If `true`, returns a JSON response instead of an SSE stream | | `autoApprove` | query | string | No | Automatically approve tool/permission prompts | | `agent` | query | string | No | Agent identifier to use for this prompt | | `system` | query | string | No | System prompt override | | `workspace` | query | string | No | Workspace ID to scope the prompt to | | `directory` | query | string | No | Working directory for the agent | ### Response ```json { "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "messageID": "msg_01HXYZABCDEF", "status": "completed", "info": { "id": "msg_01HXYZABCDEF", "role": "assistant", "finish": "stop" }, "parts": [ { "type": "text", "text": "Here is the answer to your prompt." } ] } ``` ```json { "error": "Invalid prompt: 'ai' query parameter is required", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Cross-site requests are not allowed for this endpoint", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Workspace or session not found", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Session directory conflict: directory does not match session origin", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ### SDK ```ts const result = await client.agent.prompt.agentPromptGet({ ai: "Summarize the last three commits in this repository.", sessionID: "5f9b3a2e1c8d4f0001a2b3c4", providerID: "anthropic", modelID: "claude-sonnet-4-20250514", wait: "true" }); ``` ```bash curl -X GET "https://api.hoody.com/api/v1/agent/prompt?ai=Summarize%20the%20last%20three%20commits&sessionID=5f9b3a2e1c8d4f0001a2b3c4&wait=true" \ -H "Authorization: Bearer " ``` --- ## `POST /api/v1/agent/prompt` Submit a prompt to an AI agent. Returns an SSE stream by default, or a JSON response if `wait=true`. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `parts` | array | Yes | Message parts. Each part has `type` (currently `"text"`) and `text` | | `sessionID` | string | No | Existing session ID (24-character hex) to continue the conversation | | `model` | object | No | Model selection: `{ providerID, modelID }` | | `model.providerID` | string | No | Model provider identifier (required when `model` is set) | | `model.modelID` | string | No | Model identifier (required when `model` is set) | | `endpoint` | string | No | Override the provider endpoint URL | | `apiKey` | string | No | API key for the model provider | | `wait` | boolean | No | If `true`, returns a JSON response instead of an SSE stream | | `autoApprove` | boolean | No | Automatically approve tool/permission prompts | | `agent` | string | No | Agent identifier to use for this prompt | | `system` | string | No | System prompt override | | `workspace` | string | No | Workspace ID to scope the prompt to | | `directory` | string | No | Working directory for the agent | ```json { "parts": [ { "type": "text", "text": "Refactor the authentication module to use async/await." } ], "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "model": { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" }, "wait": true, "autoApprove": false, "agent": "build", "system": "You are a senior TypeScript engineer.", "workspace": "ws_01HXYZABCDEF", "directory": "/Users/me/projects/app" } ``` ### Response ```json { "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "messageID": "msg_01HXYZABCDEF", "status": "completed", "info": { "id": "msg_01HXYZABCDEF", "role": "assistant", "finish": "stop" }, "parts": [ { "type": "text", "text": "I've refactored the auth module. The key changes were..." } ] } ``` ```json { "error": "Invalid request: 'parts' must be a non-empty array", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Workspace or session not found", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Session directory conflict: directory does not match session origin", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ### SDK ```ts const result = await client.agent.prompt.agentPrompt({ parts: [ { type: "text", text: "Refactor the authentication module to use async/await." } ], sessionID: "5f9b3a2e1c8d4f0001a2b3c4", model: { providerID: "anthropic", modelID: "claude-sonnet-4-20250514" }, wait: true, agent: "build", workspace: "ws_01HXYZABCDEF", directory: "/Users/me/projects/app" }); ``` ```bash curl -X POST "https://api.hoody.com/api/v1/agent/prompt" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "parts": [ { "type": "text", "text": "Refactor the authentication module to use async/await." } ], "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "model": { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" }, "wait": true }' ``` --- ## `POST /api/v1/agent/prompt/sync` Submit a prompt and wait for the full response. The server blocks until the agent finishes execution and returns the complete output. ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `parts` | array | Yes | Message parts. Each part has `type` (currently `"text"`) and `text` | | `sessionID` | string | No | Existing session ID (24-character hex) to continue the conversation | | `model` | object | No | Model selection: `{ providerID, modelID }` | | `model.providerID` | string | No | Model provider identifier (required when `model` is set) | | `model.modelID` | string | No | Model identifier (required when `model` is set) | | `endpoint` | string | No | Override the provider endpoint URL | | `apiKey` | string | No | API key for the model provider | | `wait` | boolean | No | Reserved flag for the synchronous variant | | `autoApprove` | boolean | No | Automatically approve tool/permission prompts | | `agent` | string | No | Agent identifier to use for this prompt | | `system` | string | No | System prompt override | | `workspace` | string | No | Workspace ID to scope the prompt to | | `directory` | string | No | Working directory for the agent | ```json { "parts": [ { "type": "text", "text": "Write unit tests for the billing service." } ], "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "model": { "providerID": "openai", "modelID": "gpt-4o" }, "autoApprove": true, "agent": "build", "workspace": "ws_01HXYZABCDEF", "directory": "/Users/me/projects/billing" } ``` ### Response ```json { "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "messageID": "msg_01HXYZGHIJKL", "status": "completed", "info": { "id": "msg_01HXYZGHIJKL", "role": "assistant", "finish": "stop" }, "parts": [ { "type": "text", "text": "I've added 14 unit tests covering invoice creation, tax calculation, refunds, and edge cases." } ] } ``` ```json { "error": "Invalid request: 'parts' must be a non-empty array", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Workspace or session not found", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ```json { "error": "Session directory conflict: directory does not match session origin", "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "status": "failed" } ``` ### SDK ```ts const result = await client.agent.prompt.agentPromptSync({ parts: [ { type: "text", text: "Write unit tests for the billing service." } ], sessionID: "5f9b3a2e1c8d4f0001a2b3c4", model: { providerID: "openai", modelID: "gpt-4o" }, autoApprove: true, agent: "build", workspace: "ws_01HXYZABCDEF", directory: "/Users/me/projects/billing" }); ``` ```bash curl -X POST "https://api.hoody.com/api/v1/agent/prompt/sync" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "parts": [ { "type": "text", "text": "Write unit tests for the billing service." } ], "sessionID": "5f9b3a2e1c8d4f0001a2b3c4", "model": { "providerID": "openai", "modelID": "gpt-4o" }, "autoApprove": true }' ``` The `/sync` variant is convenient for batch jobs and one-shot scripts where you do not need streaming output. For interactive UIs, prefer the standard `POST /api/v1/agent/prompt` and consume the SSE stream to render tokens as they arrive.