Agents API

The Agents API allows you to execute AI agents programmatically. Agents can operate in different modes to help with various tasks.

Base URL

https://dreamsolve.ai/api/v1

Authentication

All endpoints require authentication via the x-api-key header. See the API Overview for details.

---

Execute Agent

Execute an agent with the specified parameters.

POST /api/v1/agents/:agentId/execute

Path Parameters

Parameter	Type	Description
agentId	string	The agent ID to execute

Request Body

{
  "mode": "conversational",
  "userInput": "Help me plan my project",
  "nodeId": "123",
  "conversationId": "conv_456"
}

Field	Type	Required	Description
mode	string	No	Execution mode: conversational or node-assignment (default: conversational)
userInput	string	Yes	The user's input or prompt
nodeId	string	Conditional	Required for node-assignment mode
conversationId	string	No	Continue an existing conversation

Execution Modes

Mode	Description
conversational	General conversation with the agent
node-assignment	Agent works on a specific node (requires nodeId)

Response

{
  "executionId": "exec_789",
  "status": "completed",
  "output": "Here's my analysis of your project..."
}

Field	Type	Description
executionId	string	Unique execution identifier
status	string	Execution status
output	string	Agent's response (if completed)
error	string	Error message (if failed)

---

Get Execution Status

Check the status of an agent execution.

GET /api/v1/agents/executions/:executionId

Path Parameters

Parameter	Type	Description
executionId	string	The execution ID

Response

{
  "executionId": "exec_789",
  "agentId": "agent_123",
  "status": "completed",
  "output": "Agent response...",
  "startedAt": "2024-01-15T10:00:00Z",
  "completedAt": "2024-01-15T10:00:05Z"
}

Execution Status Values

Status	Description
pending	Execution queued
running	Agent is processing
completed	Execution finished successfully
failed	Execution encountered an error

---

Import Agent

Import an agent configuration.

POST /api/v1/agents/import

Request Body

{
  "name": "Custom Agent",
  "description": "My custom AI agent",
  "model": "claude-3-sonnet",
  "config": {},
  "prompt_template": "You are a helpful assistant..."
}

Response

{
  "id": "agent_new",
  "name": "Custom Agent",
  "description": "My custom AI agent",
  "created_at": "2024-01-15T10:00:00Z"
}

Status Code: 201 Created

---

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
404	Not Found - Agent not found
500	Internal Server Error

Example Error Response

{
  "error": "userInput is required and must be a non-empty string"
}

---

Example Usage

Execute a conversational agent

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "conversational",
    "userInput": "What are the best practices for project planning?"
  }' \
  https://dreamsolve.ai/api/v1/agents/agent_123/execute

Execute an agent on a specific node

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "node-assignment",
    "userInput": "Analyze this task and suggest subtasks",
    "nodeId": "task_456"
  }' \
  https://dreamsolve.ai/api/v1/agents/agent_123/execute