AgentPlatform Register Log in

API Reference

Overview

The AgentPlatform API lets you manage agents, view runs, and monitor usage programmatically. The API follows REST conventions and returns JSON responses.

The full OpenAPI specification is available at /api/v1/openapi.json. You can also browse the interactive Swagger UI at /api/v1/docs.

Authentication

All API requests require a Bearer token. Generate an API key in Settings → API Keys. 

Authorization: Bearer your-api-key

When creating an API key, you can set an expiration: 30 days, 60 days, 90 days, 1 year, or never. The key's last used timestamp is displayed on the API Keys settings page so you can identify unused keys.

Each API key has scopes that control what it can access:

  • agents:read — list and view agents
  • agents:write — create, update, and delete agents
  • runs:read — view agent run history
  • connections:read — list calendar connections
  • usage:read — view usage statistics
  • signals:write — send signals to agents
  • notifications:read — list and view notifications
  • notifications:write — mark notifications as read
  • webhooks:read — list and view webhook endpoints
  • webhooks:write — create, update, and delete webhooks
  • mcp:read — list and view MCP server configs
  • mcp:write — create, update, and delete MCP servers
  • credentials:read — list and view credentials
  • credentials:write — create and revoke credentials
  • audit_logs:read — list audit log entries
  • mcp:tools — access the MCP server endpoint

Base URL

https://your-domain.com/api/v1

Endpoints

Agents

Method Path Description
GET /agents List all agents
POST /agents Create an agent
GET /agents/:id Get agent details
PATCH /agents/:id Update an agent
DELETE /agents/:id Delete an agent
POST /agents/:id/pause Pause an agent
POST /agents/:id/resume Resume an agent
POST /agents/:id/signals Send a signal

Runs

Method Path Description
GET /agents/:agent_id/runs List runs for an agent
GET /runs/:id Get run details

Notifications

Method Path Description
GET /notifications List notifications
GET /notifications/:id Get notification details
POST /notifications/:id/read Mark notification as read
POST /notifications/read-all Mark all notifications as read

Webhooks

Method Path Description
GET /webhooks List webhook endpoints
POST /webhooks Create a webhook
GET /webhooks/:id Get webhook details
PATCH /webhooks/:id Update a webhook
DELETE /webhooks/:id Delete a webhook

MCP Servers

Method Path Description
GET /mcp-servers List MCP server configs
POST /mcp-servers Create an MCP server
GET /mcp-servers/:id Get MCP server details
PATCH /mcp-servers/:id Update an MCP server
DELETE /mcp-servers/:id Delete an MCP server

Credentials

Method Path Description
GET /credentials List credentials
POST /credentials Create a credential
GET /credentials/:id Get credential details
POST /credentials/:id/revoke Revoke a credential

Approvals (HITL)

Method Path Description
GET /approvals List pending approval requests
GET /approvals/:id Get approval request details
POST /approvals/:id/approve Approve a request (resumes agent)
POST /approvals/:id/reject Reject a request

Display Messages

Method Path Description
GET /agents/:agent_id/messages List display messages for an agent
GET /runs/:run_id/messages List display messages for a run

Audit Logs

Method Path Description
GET /audit-logs List audit log entries

Other

Method Path Description
GET /connections List calendar connections
GET /usage Get usage statistics

Signals

A signal is an event that triggers an agent to run. You can send signals programmatically via the API to trigger agent execution on demand. 

curl -X POST \
        -H "Authorization: Bearer your-api-key" \
        -H "Content-Type: application/json" \
        -d '{"type": "custom_event", "payload": {"key": "value"}}' \
        https://your-domain.com/api/v1/agents/:id/signals

For a no-code alternative, use Inbound Webhooks to trigger agents from external services without writing code.

Example: List Agents

curl -H "Authorization: Bearer your-api-key" \
        https://your-domain.com/api/v1/agents

Response:

{"data": [{"id": "abc123", "name": "Daily Weather", "type": "weather_check", "status": "idle", "schedule": "0 7 * * *"}]}

Example: Create Agent

curl -X POST \
        -H "Authorization: Bearer your-api-key" \
        -H "Content-Type: application/json" \
        -d '{"name": "NYC Weather", "type": "weather_check", "config": {"location": "New York"}}' \
        https://your-domain.com/api/v1/agents

Rate Limiting

API requests are rate-limited per API key. Current limits are returned in response headers: 

X-RateLimit-Limit: 100
        X-RateLimit-Remaining: 97
        X-RateLimit-Reset: 1709654400

If you exceed the limit, you'll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

MCP Server

AgentPlatform exposes a Model Context Protocol (MCP) server at /mcp. External MCP clients like Claude Desktop or Cursor can connect to use your platform tools (calendar, email, weather) directly.

Create an API key with the mcp:tools scope in Settings → API Keys, then configure your MCP client: 

URL: https://your-domain.com/mcp
          Authorization: Bearer your-mcp-api-key

You can also connect external MCP servers to give your agents additional tools. Configure them in Settings → MCP Servers .

Related Guides