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.
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:
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
/api/v1/agents
Create agent
Create a new agent with the specified configuration.
Request body
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
/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
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
/api/v1/agents
List all agents
Retrieve a paginated list of all your agents with optional filtering.
Query parameters
Page number for pagination (default: 1)
Number of agents per page (default: 10, max: 100)
Filter by agent status: ready, auth_required
Returns
Returns a paginated list of agents with metadata.
Example request
Response
/api/v1/agents/{agentId}
Get single agent
Retrieve details about a specific agent.
Path parameters
The ID of the agent to retrieve.
Returns
Returns the agent details including configuration and status.
Example request
Response
/api/v1/agents/{agentId}
Update agent
Update an existing agent's configuration, tags, or other properties.
Path parameters
The ID of the agent to update.
Request body
Updated agent configuration
Updated tags (up to 10 tags)
Returns
Returns the updated agent object.
Example request
Response
/api/v1/agents/{agentId}
Delete agent
Permanently delete an agent and all its runs.
Path parameters
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
/api/v1/agents/{agentId}/start
Start agent
Start an agent to make it active and able to receive triggers.
Path parameters
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
/api/v1/agents/{agentId}/stop
Stop agent
Stop an agent to prevent it from receiving new triggers.
Path parameters
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
/api/v1/agents/{agentId}/pause
Pause agent
Temporarily pause an agent. It can be resumed later.
Path parameters
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
/api/v1/agents/{agentId}/runs
Create agent run
Trigger a new agent run and get the run ID for tracking.
Path parameters
The ID of the agent to run.
Request body
Optional data to pass to the agent run.
Returns
Returns the run ID and agent details when successful.
Example request
Response
/api/v1/agents/{agentId}/runs
List agent runs
Retrieve a paginated list of all runs for a specific agent.
Path parameters
The ID of the agent whose runs to retrieve.
Query parameters
Page number for pagination (default: 1)
Number of runs per page (default: 10, max: 100)
Filter by run status: running, completed, failed, waiting-for-input
Returns
Returns a paginated list of agent runs with metadata.
Example request
Response
/api/v1/agents/{agentId}/runs/{runId}
Get agent run
Check the status of a specific agent run (for polling).
Path parameters
The ID of the agent.
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
/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
The ID of the agent.
The ID of the run that is waiting for input.
Request body
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:
/api/v1/agents/{agentId}/runs/{runId}
Update agent run
Update or cancel an agent run.
Path parameters
The ID of the agent.
The ID of the run to update.
Request body
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
/api/v1/agents/{agentId}/runs/{runId}
Delete agent run
Permanently delete an agent run and its history.
Path parameters
The ID of the agent.
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
Display name for the agent
Description of what the agent does
Default AI model for generate-text steps
Triggers
Array of triggers that start the agent. Supported types:
manual
Triggered manually via API or UIwebhook
Triggered by external webhook callscron
Triggered on schedule (cron expression)integration
Triggered by external service eventscontinuous
Runs continuously with optional delaySteps
Array of steps to execute. Supported types:
generate-text
AI text generation with specified promptgenerate-artifact
Generate HTML/JS artifacts (reports, code)form
Collect user input with custom fieldsAPIAgent 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: