Skip to Content
almyty docs — v1
API ReferenceAgents API

Agents API

This is the HTTP API reference. For UI walkthroughs, see Getting Started and the feature guides above.

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.

AnalyticsAPIs