REST API

Subagents

A subagent is a scoped AI agent deployed with a single prompt. Each one is an expert in its domain with unlimited tools.

All endpoints require an Authorization: Bearer <api_key> header.

Deploy a subagent

POST /v1/subagents

Deploys a new subagent with access to tools matching its domain.

Request body

Example request

curl -X POST https://api.ploton.ai/v1/subagents \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "crm-agent",
    "prompt": "Handle CRM tasks. Connect Salesforce, HubSpot, and Pipedrive. Manage OAuth, pull contacts, sync deals, export data."
  }'

Example response

{
  "id": "crm-agent",
  "tools_available": 14,
  "status": "deployed",
  "created_at": "2025-06-15T10:00:00Z"
}

Get a subagent

GET /v1/subagents/:subagent_id

Returns a subagent by ID.

Example request

curl https://api.ploton.ai/v1/subagents/crm-agent \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "id": "crm-agent",
  "prompt": "Handle CRM tasks. Connect Salesforce, HubSpot, and Pipedrive. Manage OAuth, pull contacts, sync deals, export data.",
  "tools_available": 14,
  "status": "deployed",
  "created_at": "2025-06-15T10:00:00Z"
}

List subagents

GET /v1/subagents

Returns your deployed subagents, paginated.

Query parameters

Example request

curl "https://api.ploton.ai/v1/subagents?limit=10" \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "data": [
    {
      "id": "crm-agent",
      "tools_available": 14,
      "status": "deployed",
      "created_at": "2025-06-15T10:00:00Z"
    },
    {
      "id": "billing-agent",
      "tools_available": 9,
      "status": "deployed",
      "created_at": "2025-06-15T10:05:00Z"
    }
  ],
  "has_more": false
}

Update a subagent

PATCH /v1/subagents/:subagent_id

Updates a subagent’s prompt. Tool availability is recalculated based on the new prompt.

Example request

curl -X PATCH https://api.ploton.ai/v1/subagents/crm-agent \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Handle CRM tasks. Connect Salesforce, HubSpot, Pipedrive, and Zoho. Manage OAuth, pull contacts, sync deals, export data, manage pipelines."
  }'

Example response

{
  "id": "crm-agent",
  "tools_available": 16,
  "status": "deployed",
  "updated_at": "2025-06-16T09:00:00Z"
}

Delete a subagent

DELETE /v1/subagents/:subagent_id

Deletes a subagent. Tasks already running on this subagent will complete, but no new tasks can be routed to it.

Example request

curl -X DELETE https://api.ploton.ai/v1/subagents/crm-agent \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "id": "crm-agent",
  "status": "deleted",
  "deleted_at": "2025-06-16T09:05:00Z"
}

Tasks

A task is a unit of work routed to a subagent. You create one, the subagent runs it.

Create a task

POST /v1/tasks

Creates a task and routes it to a subagent for execution.

Request body

Example request

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Pull all contacts from user_123'\''s CRM account created in the last 30 days. Return name, email, and company.",
    "sub_agent": "crm-agent",
    "user_id": "user_123",
    "metadata": {
      "source": "lead_enrichment_pipeline"
    }
  }'

Example response

{
  "id": "task_8xK2mP",
  "status": "running",
  "sub_agent": "crm-agent",
  "created_at": "2025-06-15T14:22:00Z",
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Error responses

Get a task

GET /v1/tasks/:task_id

Returns a task by ID. Includes the result if the task is done, or the error if it failed.

Path parameters

Example request

curl https://api.ploton.ai/v1/tasks/task_8xK2mP \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response (complete)

{
  "id": "task_8xK2mP",
  "status": "complete",
  "sub_agent": "crm-agent",
  "created_at": "2025-06-15T14:22:00Z",
  "completed_at": "2025-06-15T14:22:07Z",
  "result": {
    "contacts": [
      {
        "name": "Jane Smith",
        "email": "[email protected]",
        "company": "Acme Corp"
      },
      {
        "name": "Bob Chen",
        "email": "[email protected]",
        "company": "Globex Inc"
      }
    ]
  },
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Example response (failed)

{
  "id": "task_8xK2mP",
  "status": "failed",
  "sub_agent": "crm-agent",
  "created_at": "2025-06-15T14:22:00Z",
  "failed_at": "2025-06-15T14:22:04Z",
  "error": {
    "code": "auth_token_expired",
    "message": "The user's OAuth token has expired and automatic refresh failed.",
    "recoverable": true,
    "suggestion": "Prompt the user to re-authorize access"
  },
  "metadata": {
    "source": "lead_enrichment_pipeline"
  }
}

Error responses

List tasks

GET /v1/tasks

Returns tasks, paginated.

Query parameters

Example request

curl "https://api.ploton.ai/v1/tasks?status=complete&sub_agent=crm-agent&limit=5" \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "data": [
    {
      "id": "task_8xK2mP",
      "status": "complete",
      "sub_agent": "crm-agent",
      "created_at": "2025-06-15T14:22:00Z",
      "completed_at": "2025-06-15T14:22:07Z"
    },
    {
      "id": "task_3nL7pR",
      "status": "complete",
      "sub_agent": "billing-agent",
      "created_at": "2025-06-15T13:10:00Z",
      "completed_at": "2025-06-15T13:10:12Z"
    }
  ],
  "has_more": true
}

List responses omit result and error. Hit GET /v1/tasks/:task_id for the full object.

Cancel a task

POST /v1/tasks/:task_id/cancel

Cancels a pending, running, or waiting task. Returns 409 if the task already finished or failed.

Path parameters

Example request

curl -X POST https://api.ploton.ai/v1/tasks/task_8xK2mP/cancel \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "id": "task_8xK2mP",
  "status": "cancelled",
  "cancelled_at": "2025-06-15T14:22:05Z"
}

Error responses

Get a task trace

GET /v1/tasks/:task_id/trace

Returns the step-by-step execution trace for a task: what ran, in what order, and how long each step took.

Example request

curl https://api.ploton.ai/v1/tasks/task_8xK2mP/trace \
  -H "Authorization: Bearer $PLOTON_API_KEY"

Example response

{
  "task_id": "task_8xK2mP",
  "sub_agent": "crm-agent",
  "steps": [
    {
      "tool": "crm",
      "action": "authenticate",
      "status": "complete",
      "duration_ms": 120
    },
    {
      "tool": "crm",
      "action": "fetch_contacts",
      "status": "complete",
      "duration_ms": 890,
      "note": "Filtered to last 30 days, 47 contacts returned"
    },
    {
      "tool": "crm",
      "action": "format_response",
      "status": "complete",
      "duration_ms": 15
    }
  ],
  "total_duration_ms": 1025
}

Use traces to debug failures or find where time is going.

Next steps

• Webhooks — Event types and payload reference
• API Overview — Rate limits, error codes, pagination