Team API Reference

REST API for programmatic team management. Use it to create, reset, repurpose, destroy, and execute commands on agents — all from your own scripts or integrations.

Getting an API Key

Only team owners can create and manage API keys. The flow lives in your subscriber dashboard.

Authentication

All /v1 endpoints require a Team API key. Pass it in the Authorization header:

Authorization: Bearer sctk_<prefix>_<secret>

You can also use the X-Team-Api-Key header instead.

Team Members

List Team Members

Retrieve all team members with their roles.

curl -s https://api.superclaws.io/v1/team/members \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Agents

List Available Roles

Return the role catalog — valid role_slug values for agent creation, reset, and repurpose. Use this endpoint to discover available roles before creating an agent.

curl -s https://api.superclaws.io/v1/roles \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Response includes slug, label, and description for each role:

{
  "roles": [
    {
      "slug": "generalist",
      "label": "Generalist",
      "description": "Handles broad cross-functional support across multiple business domains."
    },
    {
      "slug": "sales",
      "label": "Sales",
      "description": "Prospecting, outreach, pipeline management, closing deals."
    },
    ...
  ]
}

GET /v1/agents/:agent_id

Get details for a specific agent.

Response

{
  "agent": {
    "id": "uuid",
    "display_name": "My Assistant",
    "status": "active",
    "setup_step": "active",
    "bot_username": "MyAssistantBot",
    "assigned_user_id": "uuid",
    "assigned_email": "user@example.com",
    "instance_id": "uuid",
    "agent_id": "uuid",
    "provision_job_id": "uuid",
    "provisioning_needs_repair": false,
    "provisioning_failure_message": null,
    "is_managed_bot": false,
    "role_slugs": ["sales", "support"],
    "functionality_descriptor": "Handles customer inquiries",
    "callback_url": "https://your-domain.com/webhooks/agent-status",
    "notify_email": "admin@your-domain.com",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T11:00:00Z"
  }
}

List All Agents

Return all agents for your team.

curl -s https://api.superclaws.io/v1/agents \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Create an Agent

Create a new team agent. Requires a Telegram bot token from @BotFather.

You can optionally pass display_name, role_prompt, and role_slugs to customize the agent's personality from the start. The role_prompt is a natural language description that gets turned into a SOUL.md file defining the agent's behavior.

You can also optionally provide callback_url and notify_email to receive webhook and email notifications when provisioning completes:

curl -s -X POST https://api.superclaws.io/v1/agents \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_token":"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11","display_name":"Growth Agent","role_prompt":"handles marketing campaigns and lead generation","role_slugs":["marketing"],"callback_url":"https://your-server.com/webhooks/agent-status","notify_email":"dev@example.com"}' | jq .

curl -s -X POST https://api.superclaws.io/v1/agents \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_token":"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11","display_name":"Growth Agent","role_prompt":"handles marketing campaigns and lead generation","role_slugs":["marketing"]}' | jq .

Create a Managed Agent

Create a new team agent without a bot token. The system creates a Telegram bot on your behalf using the Managed Bots feature. You'll receive a deep link and QR code — the user must open the link in Telegram and tap confirm to complete bot creation.

You can optionally provide callback_url and notify_email to receive webhook and email notifications when provisioning completes:

curl -s -X POST https://api.superclaws.io/v1/agents \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"managed":true,"bot_username":"MyAgentBot","bot_name":"My Agent","callback_url":"https://your-server.com/webhooks/agent-status","notify_email":"dev@example.com"}' | jq .

curl -s -X POST https://api.superclaws.io/v1/agents \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"managed":true,"bot_username":"MyAgentBot","bot_name":"My Agent"}' | jq .

The response returns 202 Accepted with a creation link and QR code:

{
  "ok": true,
  "managed": true,
  "status": "awaiting_confirmation",
  "request_id": "a1b2c3d4-...",
  "creation_link": "https://t.me/newbot/ManagerBot/MyAgentBot?name=My+Agent",
  "qr_code": "data:image/png;base64,iVBOR...",
  "expires_at": "2026-04-23T12:00:00Z",
  "suggested_username": "MyAgentBot",
  "suggested_name": "My Agent"
}

Check Managed Request Status

Poll the status of a managed-bot creation request. Use the request_id returned by the managed agent creation endpoint.

curl -s https://api.superclaws.io/v1/agents/managed-requests/<REQUEST_ID> \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Request status values: pending | created | expired | cancelled | error

When the status is created, the agent object in the response contains the new agent's current provisioning state.

Get Agent Details

Retrieve details for a single agent by ID.

curl -s https://api.superclaws.io/v1/agents/<AGENT_ID> \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Approve Pairing

Approve pairing for an agent that is in the pairing setup step. Pass either pairingMessage (the full message from your bot) or pairingCommand (the extracted command). The command is validated and executed on the remote server before the agent is marked as active.

You can optionally provide callback_url and notify_email to receive webhook and email notifications when pairing completes:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/pairing-approve \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pairingMessage":"Your Telegram user ID is 123456789 and your pairing code is ABC123DEF456. To complete pairing, run: openclaw pairing approve telegram ABC123DEF456","callback_url":"https://your-server.com/webhooks/pairing","notify_email":"dev@example.com"}' | jq .

Or with the pre-extracted command:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/pairing-approve \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pairingCommand":"pairing approve telegram ABC123DEF456","callback_url":"https://your-server.com/webhooks/pairing","notify_email":"dev@example.com"}' | jq .

Without notifications:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/pairing-approve \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pairingMessage":"Your Telegram user ID is 123456789 and your pairing code is ABC123DEF456. To complete pairing, run: openclaw pairing approve telegram ABC123DEF456"}' | jq .

Or with the pre-extracted command:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/pairing-approve \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pairingCommand":"pairing approve telegram ABC123DEF456"}' | jq .

Assign an Agent

Assign an agent to a team member. Pass the user_id field from the /v1/team/members response to assign, or null to unassign.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/assign \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_user_id":"<USER_ID>"}' | jq .

To unassign:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/assign \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assigned_user_id":null}' | jq .

Reset Agent

Reset and reprovision an agent's server. The server is rebuilt from scratch with a fresh OpenClaw install and the agent is reprovisioned.

Non-managed agents require a bot_token (same as before).

Managed agents automatically reuse their stored bot token — do not pass bot_token. If you do pass one, it is silently ignored.

You can optionally pass role_prompt, role_slugs, and display_name to change the agent's personality during the reset. The role_prompt generates a new SOUL.md that is deployed during reprovisioning.

# Non-managed reset with new role
curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/reset \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bot_token":"123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11","role_prompt":"customer support agent that handles returns","role_slugs":["support"],"display_name":"Support Bot"}' | jq .

# Managed-bot reset (no token needed)
curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/reset \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_prompt":"sales outreach bot","role_slugs":["sales"]}' | jq .

The response includes soul_generation_mode indicating how SOUL.md was generated (moonshot for AI-generated, fallback for deterministic template).

Reboot Agent

Reboot an agent's server. The server powers off and back on — no data is lost.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/reboot \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Destroy Agent

Permanently destroy an agent and its server infrastructure. This action is immediate and irreversible.

• If the agent has no linked infrastructure, it is marked destroyed immediately.
• Otherwise, the agent is marked destroying and the server is queued for deletion.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/destroy \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

Execute a Command

Run an allowed openclaw command on the agent's server via SSH. Useful for restarting the gateway, checking status, or managing configuration.

Allowed command prefixes: gateway, webhooks, status, acp, browser, memory, pairing, plugins, config, gog.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/exec \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"gateway restart"}' | jq .

Response includes exit_code, stdout, and stderr.

Repurpose Agent

Change an agent's personality without rebuilding the server. This is a hot-swap — the agent picks up the new SOUL.md on the next gateway restart or workspace reload. No data is lost.

Pass role_prompt to define the new personality, role_slugs for role categories, and optionally display_name to rename the agent. Set reset_identity to true to also regenerate the IDENTITY.md file.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/repurpose \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_prompt":"friendly customer support agent that handles returns and complaints","role_slugs":["support"],"display_name":"Support Agent"}' | jq .

Repair Agent

Repair an agent's provisioning by re-running instance registration. This is useful when an agent's server has issues but you don't want to rebuild from scratch. The repair process restores missing files, updates model configurations, and fixes plugin issues.

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/repair \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq .

You can optionally provide a callback_url to receive a webhook notification when the repair completes (on both success and failure):

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/repair \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://your-server.com/webhooks/repair"}' | jq .

You can also optionally provide a notify_email to receive an email notification when the repair completes (on both success and failure):

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/repair \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify_email":"dev@example.com"}' | jq .

Or use both:

curl -s -X POST https://api.superclaws.io/v1/agents/<AGENT_ID>/repair \
  -H "Authorization: Bearer $SC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://your-server.com/webhooks/repair","notify_email":"dev@example.com"}' | jq .

The webhook payload includes agent_id, status (success or failed), and event_type (repair_complete):

{
  "agent_id": "uuid",
  "status": "success",
  "event_type": "repair_complete"
}

Poll the repair status using the status endpoint:

curl -s https://api.superclaws.io/v1/agents/<AGENT_ID>/repair-status \
  -H "Authorization: Bearer $SC_API_KEY" | jq .

Status values: idle | in_progress | success | failed

Dashboard Key Management

These routes are session-authenticated (dashboard login), not API-key authenticated. They require the team owner role.

List API Keys

curl -s https://api.superclaws.io/app/teams/<TEAM_ID>/api-keys \
  -H "Cookie: sc_session=<SESSION_COOKIE>" | jq .

Create an API Key

Returns the raw key once in the rawKey field — store it securely. It cannot be retrieved again.

curl -s -X POST https://api.superclaws.io/app/teams/<TEAM_ID>/api-keys \
  -H "Cookie: sc_session=<SESSION_COOKIE>" \
  -H "Content-Type: application/json" \
  -d '{"label":"CI Pipeline","role":"admin"}' | jq .

Revoke an API Key

curl -s -X DELETE https://api.superclaws.io/app/teams/<TEAM_ID>/api-keys/<KEY_ID> \
  -H "Cookie: sc_session=<SESSION_COOKIE>" | jq .

Permissions

• /v1 routes — any active Team API key for the team.
• Dashboard key management — team owner only (session auth).
• Agent management on /v1 — key needs admin or owner role. Currently all keys can access all endpoints; role enforcement can be tightened later.