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

200

{
  "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."
    }
  ]
}

400

{
  "error": "Invalid prompt: 'ai' query parameter is required",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

403

{
  "error": "Cross-site requests are not allowed for this endpoint",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

404

{
  "error": "Workspace or session not found",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

409

{
  "error": "Session directory conflict: directory does not match session origin",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

SDK

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"
});

curl -X GET "https://api.hoody.com/api/v1/agent/prompt?ai=Summarize%20the%20last%20three%20commits&sessionID=5f9b3a2e1c8d4f0001a2b3c4&wait=true" \
  -H "Authorization: Bearer <token>"

---

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

{
  "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

200

{
  "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..."
    }
  ]
}

400

{
  "error": "Invalid request: 'parts' must be a non-empty array",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

404

{
  "error": "Workspace or session not found",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

409

{
  "error": "Session directory conflict: directory does not match session origin",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

SDK

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"
});

curl -X POST "https://api.hoody.com/api/v1/agent/prompt" \
  -H "Authorization: Bearer <token>" \
  -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

{
  "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

200

{
  "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."
    }
  ]
}

400

{
  "error": "Invalid request: 'parts' must be a non-empty array",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

404

{
  "error": "Workspace or session not found",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

409

{
  "error": "Session directory conflict: directory does not match session origin",
  "sessionID": "5f9b3a2e1c8d4f0001a2b3c4",
  "status": "failed"
}

SDK

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"
});

curl -X POST "https://api.hoody.com/api/v1/agent/prompt/sync" \
  -H "Authorization: Bearer <token>" \
  -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
  }'

Tip

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.