agent-swarm.devagent-swarm.dev

Agents

CRUD operations for agent profiles — create, configure, update, and manage swarm agents

GET
/api/agents

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Query Parameters

include?string
Value in"tasks"
fields?string
Value in"full" | "slim"

Response Body

application/json

curl -X GET "http://localhost:3013/api/agents"
{
  "agents": [
    {
      "id": "string",
      "name": "string",
      "isLead": false,
      "status": "idle",
      "description": "string",
      "role": "string",
      "capabilities": [],
      "claudeMd": "string",
      "soulMd": "string",
      "identityMd": "string",
      "setupScript": "string",
      "toolsMd": "string",
      "heartbeatMd": "string",
      "maxTasks": 1,
      "emptyPollCount": 0,
      "lastActivityAt": "2019-08-24T14:15:22Z",
      "provider": "claude",
      "harnessProvider": "claude",
      "credentialMissing": [
        "string"
      ],
      "credStatus": {
        "ready": true,
        "missing": [],
        "satisfiedBy": "env",
        "hint": null,
        "liveTest": null,
        "latestModel": null,
        "reportedAt": 0,
        "reportKind": "boot",
        "bedrock": null
      },
      "avatar": {
        "type": "lucide",
        "icon": "string",
        "color": "string"
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "lastUpdatedAt": "2019-08-24T14:15:22Z",
      "tasks": [],
      "capacity": {
        "current": 0,
        "max": 0,
        "available": 0
      }
    }
  ]
}
POST
/api/agents

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "http://localhost:3013/api/agents" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "enabledCapabilities": [
    "core"
  ]
}
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "enabledCapabilities": [
    "core"
  ]
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/agents/{id}

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Query Parameters

include?string
Value in"tasks"

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/agents/string"
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "tasks": [],
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PUT
/api/agents/{id}/activity

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Response Body

curl -X PUT "http://localhost:3013/api/agents/string/activity"
Empty
GET
/api/agents/{id}/credential-status

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/agents/string/credential-status"
{
  "agentId": "string",
  "name": "string",
  "status": "idle",
  "missing": [
    "string"
  ],
  "provider": "claude",
  "harnessProvider": "claude",
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "lastCheckedAt": "string"
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PUT
/api/agents/{id}/credential-status

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X PUT "http://localhost:3013/api/agents/string/credential-status" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PATCH
/api/agents/{id}/harness-provider

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X PATCH "http://localhost:3013/api/agents/string/harness-provider" \  -H "Content-Type: application/json" \  -d '{    "harness_provider": "claude"  }'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PUT
/api/agents/{id}/name

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X PUT "http://localhost:3013/api/agents/string/name" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PUT
/api/agents/{id}/profile

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X PUT "http://localhost:3013/api/agents/string/profile" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
PATCH
/api/agents/{id}/runtime

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X PATCH "http://localhost:3013/api/agents/string/runtime" \  -H "Content-Type: application/json" \  -d '{    "harness_provider": "claude"  }'
{
  "id": "string",
  "name": "string",
  "isLead": false,
  "status": "idle",
  "description": "string",
  "role": "string",
  "capabilities": [],
  "claudeMd": "string",
  "soulMd": "string",
  "identityMd": "string",
  "setupScript": "string",
  "toolsMd": "string",
  "heartbeatMd": "string",
  "maxTasks": 1,
  "emptyPollCount": 0,
  "lastActivityAt": "2019-08-24T14:15:22Z",
  "provider": "claude",
  "harnessProvider": "claude",
  "credentialMissing": [
    "string"
  ],
  "credStatus": {
    "ready": true,
    "missing": [],
    "satisfiedBy": "env",
    "hint": null,
    "liveTest": null,
    "latestModel": null,
    "reportedAt": 0,
    "reportKind": "boot",
    "bedrock": null
  },
  "avatar": {
    "type": "lucide",
    "icon": "string",
    "color": "string"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "lastUpdatedAt": "2019-08-24T14:15:22Z",
  "capacity": {
    "current": 0,
    "max": 0,
    "available": 0
  }
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/agents/{id}/setup-script

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Path Parameters

id*string

Response Body

application/json

application/json

curl -X GET "http://localhost:3013/api/agents/string/setup-script"
{
  "setupScript": "string",
  "globalSetupScript": "string"
}
{
  "error": "string",
  "property1": null,
  "property2": null
}
GET
/api/agents/credential-status

Authorization

bearerAuth
AuthorizationBearer <token>

API key via Authorization: Bearer <API_KEY>

In: header

Query Parameters

status?string
Value in"idle" | "busy" | "offline" | "waiting_for_credentials"

Response Body

application/json

curl -X GET "http://localhost:3013/api/agents/credential-status"
{
  "agents": [
    {
      "agentId": "string",
      "name": "string",
      "status": "idle",
      "missing": [
        "string"
      ],
      "provider": "claude",
      "harnessProvider": "claude",
      "credStatus": {
        "ready": true,
        "missing": [],
        "satisfiedBy": "env",
        "hint": null,
        "liveTest": null,
        "latestModel": null,
        "reportedAt": 0,
        "reportKind": "boot",
        "bedrock": null
      },
      "lastCheckedAt": "string"
    }
  ]
}

Active Sessions

Monitor and control active agent sessions running in the swarm

ApprovalRequests

Human-in-the-loop approval requests — review and respond to agent-escalated decisions