Skip to Content
API referenceAgents API

Agents API

This page is for developers who want to create, run and inspect agents from their own code. For example, your order system can start the support agent when a ticket arrives, or a script can roll an agent back to yesterday’s version. In the app, the same work is on Agents; see Agents.

Agents in the UI

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
GET/agents/:id/scheduleGet schedule, in plain words, with its next run
POST/agents/:id/scheduleSet schedule (every N minutes, a time of day on chosen days, or once a month; see Scheduling)
POST/agents/:id/schedule/previewDescribe a schedule and its next runs without saving it
GET/agents/:id/schedule/destinationsWhere a scheduled result can go
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.

Gateways APIProviders API