API Reference
Agents

Agents API

Complete REST API reference for managing agents, invoking pipelines, and working with versions and executions.

Endpoints

MethodEndpointDescription
GET/agentsList all agents
POST/agentsCreate a new agent
GET/agents/:idGet agent by ID
PATCH/agents/:idUpdate an agent
DELETE/agents/:idDelete an agent
POST/agents/:id/invokeInvoke an agent
POST/agents/:id/activateActivate an agent
POST/agents/:id/deactivateDeactivate an agent
POST/agents/:id/duplicateDuplicate an agent
GET/agents/:id/executionsList executions
GET/agents/:id/executions/:execIdGet execution detail
GET/agents/:id/versionsList versions
POST/agents/:id/versionsSave a version
POST/agents/:id/versions/:idx/rollbackRollback to version
GET/agents/:id/exportExport agent JSON
POST/agents/importImport agent JSON
GET/agents/templatesList available templates
GET/agents/:id/cost-estimateGet cost estimate
GET/agents/:id/audit-logGet audit log
POST/agents/:id/scheduleSet schedule
DELETE/agents/:id/scheduleRemove schedule

List Agents

curl https://api.almyty.com/agents \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "Research Agent",
      "description": "Searches and summarizes information",
      "status": "active",
      "pipeline": {
        "nodes": [...],
        "edges": [...]
      },
      "totalExecutions": 42,
      "createdAt": "2026-03-01T10:00:00Z",
      "updatedAt": "2026-03-20T14:30:00Z"
    }
  ]
}

Create Agent

curl -X POST https://api.almyty.com/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "description": "Description of what this agent does",
    "pipeline": {
      "nodes": [
        { "id": "input_1", "type": "input", "data": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } } },
        { "id": "llm_1", "type": "llm_call", "data": { "providerId": "prov-id", "userPromptTemplate": "{{input.message}}" } },
        { "id": "output_1", "type": "output", "data": { "mapping": "{{nodes.llm_1.output}}" } }
      ],
      "edges": [
        { "id": "e1", "source": "input_1", "target": "llm_1" },
        { "id": "e2", "source": "llm_1", "target": "output_1" }
      ]
    }
  }'

Invoke Agent

curl -X POST https://api.almyty.com/agents/{id}/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "message": "What is the capital of France?" },
    "options": {
      "timeout": 30000,
      "trace": true
    }
  }'

Parameters

ParameterTypeRequiredDescription
inputobjectYesInput data matching the agent's input schema
options.timeoutnumberNoExecution timeout in milliseconds
options.tracebooleanNoInclude node-by-node execution trace

Response

{
  "output": "The capital of France is Paris.",
  "executionId": "exec-uuid",
  "duration": 1250,
  "tokensUsed": 85,
  "trace": [
    {
      "nodeId": "input_1",
      "type": "input",
      "duration": 1,
      "output": { "message": "What is the capital of France?" }
    },
    {
      "nodeId": "llm_1",
      "type": "llm_call",
      "duration": 1245,
      "output": "The capital of France is Paris.",
      "tokensUsed": 85
    },
    {
      "nodeId": "output_1",
      "type": "output",
      "duration": 1,
      "output": "The capital of France is Paris."
    }
  ]
}

Get Executions

curl "https://api.almyty.com/agents/{id}/executions?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Query Parameters

ParameterTypeDefaultDescription
limitinteger20Number of executions to return
offsetinteger0Offset for pagination
statusstring—Filter by status: success, failed, running
triggerstring—Filter by trigger: manual, webhook, schedule

Save Version

curl -X POST https://api.almyty.com/agents/{id}/versions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "changelog": "Added error handling branch"
  }'

Rollback

curl -X POST https://api.almyty.com/agents/{id}/versions/{versionIndex}/rollback \
  -H "Authorization: Bearer $TOKEN"

Replaces the agent's current pipeline with the snapshot from the specified version.

LLM ProvidersOpenAI Compatible