Fullpilot API

Build powerful AI agents with structured workflows and real-world actions

API Access Requirements

The Fullpilot API is currently available only to select teams with a minimum spend and requires approval. Contact our team at support@fullpilot.com to request access.

The Fullpilot v1 API enables building sophisticated AI agents with structured workflows, allowing you to define explicit steps with clear inputs, outputs and success criteria - from text generation to form inputs and artifact creation.

With 2,000+ integrations, agents can take real actions by triggering automations, connecting to external tools, and executing precise multi-step processes, providing the building blocks for reliable, production-ready AI workflows whether you need research, analysis, content creation or task automation.

Create API Keys

Login to create an API key

How to use your API keys

Authentication

Include your API key in the Authorization header:

Authorization: Bearer fp_live_your_api_key_here

Base URL

https://www.fullpilot.com/api/v1/

Rate Limits

To ensure fair usage and system stability, the API enforces rate limits on all endpoints. These limits are designed to accommodate normal usage patterns while preventing abuse.

Standard Endpoints

100 requests per minute

Agent CRUD, run management, status checks

Agent Execution

20 runs per minute

Creating new agent runs, submitting input

Rate Limit Headers

Each API response includes rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1643723400

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your application to handle these gracefully.

Philosophy & How It Works

Our API follows a simple yet powerful approach to creating and managing AI agents. The process starts with agent creation, where you define how your agent should behave - whether it responds to specific triggers or runs on manual activation. During this setup phase, if your agent requires any integrations (like Slack or GitHub), you'll receive connection URLs to easily establish these connections.

Once configured, your agent is ready to run in our cloud infrastructure. You have complete control over its lifecycle - start it, stop it, or manually trigger new runs. The API provides straightforward CRUD operations that make it effortless to:

  • Create and configure new agents
  • Manage integration connections
  • Control agent execution states
  • Trigger manual agent runs
  • Monitor agent activity and performance

Pricing & Billing

API usage is billed to your account using the same pricing model as regular platform agents. You're charged for AI tokens consumed by your agents based on the models used in your agent steps (text generation, analysis, etc.). Different models have different token costs.

All API usage appears in your regular billing dashboard alongside platform usage. There are no additional API access fees. View current pricing details for specific token costs by model.

Example Flow

Here's a typical flow for working with agents through the API:

This flow demonstrates the key interactions with an agent through its lifecycle - from creation and setup, through execution and human interaction, to shutdown.

Available Endpoints

POST/api/v1/agents

Create agent

Create a new agent with the specified configuration.

Request body
configAgentConfig(object)Required

The agent configuration object.

Returns

Returns an APIAgent object wrapped in a standard response format. If external integrations are required, the agent will include status: "auth_required" with connection links. It is recommended to allow your user to open each connection link in a new tab to connect their accounts.

Example request
Response
GET/api/v1/agents/{agentId}/connections

Get connection URLs

Generate fresh connection URLs for required integrations. Useful for reconnecting expired integrations or helping users connect accounts.

Path parameters
agentIdstringRequired

The ID of the agent to get connection URLs for.

Returns

Returns fresh connection URLs for any required integrations that are not yet connected. If all integrations are connected, returns an empty list.

Use Cases
  • • Reconnect expired integrations
  • • Get fresh connection URLs after tokens expire
  • • Help users connect missing integrations
  • • Refresh connections without recreating the agent
Example request
Response - Missing connections
Response - All connected
GET/api/v1/agents

List all agents

Retrieve a paginated list of all your agents with optional filtering.

Query parameters
pagenumberOptional

Page number for pagination (default: 1)

limitnumberOptional

Number of agents per page (default: 10, max: 100)

statusstringOptional

Filter by agent status: ready, auth_required

Returns

Returns a paginated list of agents with metadata.

Example request
Response
GET/api/v1/agents/{agentId}

Get single agent

Retrieve details about a specific agent.

Path parameters
agentIdstringRequired

The ID of the agent to retrieve.

Returns

Returns the agent details including configuration and status.

Example request
Response
PUT/api/v1/agents/{agentId}

Update agent

Update an existing agent's configuration, tags, or other properties.

Path parameters
agentIdstringRequired

The ID of the agent to update.

Request body
configAgentConfigOptional

Updated agent configuration

tagsstring[]Optional

Updated tags (up to 10 tags)

Returns

Returns the updated agent object.

Example request
Response
DELETE/api/v1/agents/{agentId}

Delete agent

Permanently delete an agent and all its runs.

Path parameters
agentIdstringRequired

The ID of the agent to delete.

Returns

Returns confirmation of deletion.

Warning

This action cannot be undone. The agent and all its runs will be permanently deleted.

Example request
Response
POST/api/v1/agents/{agentId}/start

Start agent

Start an agent to make it active and able to receive triggers.

Path parameters
agentIdstringRequired

The ID of the agent to start.

Returns

Returns the updated agent with running status.

Note

Agents are created in a stopped state by default. You must start an agent before it can receive triggers and execute runs.

Example request
Response
POST/api/v1/agents/{agentId}/stop

Stop agent

Stop an agent to prevent it from receiving new triggers.

Path parameters
agentIdstringRequired

The ID of the agent to stop.

Returns

Returns the updated agent with stopped status.

Important

Stopping an agent will prevent new triggers from starting runs, but existing runs will continue to completion.

Example request
Response
POST/api/v1/agents/{agentId}/pause

Pause agent

Temporarily pause an agent. It can be resumed later.

Path parameters
agentIdstringRequired

The ID of the agent to pause.

Returns

Returns the updated agent with paused status.

Note

Paused agents can be resumed with the start endpoint. Like stopping, pausing prevents new triggers but allows existing runs to complete.

Example request
Response
POST/api/v1/agents/{agentId}/runs

Create agent run

Trigger a new agent run and get the run ID for tracking.

Path parameters
agentIdstringRequired

The ID of the agent to run.

Request body
trigger_dataobjectOptional

Optional data to pass to the agent run.

Returns

Returns the run ID and agent details when successful.

Example request
Response
GET/api/v1/agents/{agentId}/runs

List agent runs

Retrieve a paginated list of all runs for a specific agent.

Path parameters
agentIdstringRequired

The ID of the agent whose runs to retrieve.

Query parameters
pagenumberOptional

Page number for pagination (default: 1)

limitnumberOptional

Number of runs per page (default: 10, max: 100)

statusstringOptional

Filter by run status: running, completed, failed, waiting-for-input

Returns

Returns a paginated list of agent runs with metadata.

Example request
Response
GET/api/v1/agents/{agentId}/runs/{runId}

Get agent run

Check the status of a specific agent run (for polling).

Path parameters
agentIdstringRequired

The ID of the agent.

runIdstringRequired

The ID of the run to retrieve.

Returns

Returns the current status and details of the agent run.

Polling Tip

Use is_in_progress: true to determine if you should continue polling. Poll every 2-5 seconds while the run is in progress.

Example request
Response
POST/api/v1/agents/{agentId}/runs/{runId}/input

Submit user input

Submit user input to continue an agent run that is waiting for input.

Path parameters
agentIdstringRequired

The ID of the agent.

runIdstringRequired

The ID of the run that is waiting for input.

Request body
input_dataobjectRequired

The user input data matching the expected form fields from the automation step.

Returns

Returns confirmation that the input was submitted and the agent will continue.

Important

This endpoint only works when the run status is waiting-for-input. Check the run status first before submitting input.

Example request
Response
Example: Run waiting for input

When polling shows the run is waiting for input:

PUT/api/v1/agents/{agentId}/runs/{runId}

Update agent run

Update or cancel an agent run.

Path parameters
agentIdstringRequired

The ID of the agent.

runIdstringRequired

The ID of the run to update.

Request body
actionstringRequired

Action to perform: "cancel"

Returns

Returns the updated run object.

Note

Only running or waiting-for-input runs can be cancelled. Completed or failed runs cannot be modified.

Example request
Response
DELETE/api/v1/agents/{agentId}/runs/{runId}

Delete agent run

Permanently delete an agent run and its history.

Path parameters
agentIdstringRequired

The ID of the agent.

runIdstringRequired

The ID of the run to delete.

Returns

Returns confirmation of deletion.

Warning

This action cannot be undone. The run and all its logs will be permanently deleted.

Example request
Response

AgentConfig Structure

The AgentConfig is an object that defines the complete structure of an agent. Here's the object structure:

Object Structure
Field Details
Core Properties
namestringRequired

Display name for the agent

descriptionstringOptional

Description of what the agent does

defaultModelstringOptional

Default AI model for generate-text steps

Triggers
triggersConfigTrigger[]Required

Array of triggers that start the agent. Supported types:

manualTriggered manually via API or UI
webhookTriggered by external webhook calls
cronTriggered on schedule (cron expression)
integrationTriggered by external service events
continuousRuns continuously with optional delay
Steps
stepsStepConfig[]Required

Array of steps to execute. Supported types:

generate-textAI text generation with specified prompt
generate-artifactGenerate HTML/JS artifacts (reports, code)
formCollect user input with custom fields

APIAgent Type

The agent object returned by the API. This represents the core agent data structure.

APIAgent Structure
API Response

The API returns this APIAgent object wrapped in a standard response format:

Status Examples

Agents have two status fields: status (configuration readiness) and operational_status (running state).

Ready to Use (status: "ready")

When the agent doesn't require external integrations (note: operational_status defaults to "stopped"):

Authentication Required (status: "auth_required")

When the agent uses external services that need account connections: