Skip to main content
Fleece AI — the gold ram mascotFleece AI
Book a demoGet started free
DocumentationAPI Reference
REST API v1.0

API Reference

The Fleece AI REST API lets you manage agents, trigger flows, and retrieve execution results programmatically. API access requires a **Pro plan or higher**.

Base URL
https://fleeceai.app/api/v1
Authentication

Bearer token via API key

Required plan

Pro, Business, or Enterprise

Authentication

All API requests require a valid API key in the Authorization header.

Getting your API key

  1. Log in to your Fleece AI dashboard
  2. Go to Settings > API Keys
  3. Click Create New API Key and give it a name
  4. Copy the key immediately — it is shown only once

Using the key

Include your API key as a Bearer token in the Authorization header of every request:

# Example with cURL
curl -H "Authorization: Bearer flc_your_key_here" \
https://fleeceai.app/api/v1/agents

Keep your key secure

Never expose your API key in client-side code, public repositories, or browser requests. Use environment variables and server-side calls only.

Key limits per plan

Starter
No access
Pro
5 keys
Business
10 keys
Enterprise
25 keys

Rate Limits

API requests are rate-limited per plan to ensure fair usage.

PlanRequests / dayBurst / minute
Pro5,00060
Business50,000300
EnterpriseCustomCustom

When rate-limited, the API returns 429 Too Many Requests with the following headers:

Retry-After: 30
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1741564800

Errors

All errors return a JSON body with an error field.

StatusMeaningExample
400Bad Request — invalid or missing parameters{"error":"name is required"}
401Unauthorized — missing or invalid API key{"error":"Unauthorized"}
403Forbidden — plan limit or feature restriction{"error":"API access requires Pro plan or higher","upgrade":true}
404Not Found — resource does not exist or you don't own it{"error":"Not found"}
409Conflict — e.g. flow is already running{"error":"Flow is already running"}
429Too Many Requests — rate limit exceeded{"error":"Rate limit exceeded"}
500Internal Server Error — unexpected failure{"error":"Internal server error"}

Agents

Create, list, and execute AI agents

get/agents

List agents

Returns all agents belonging to the authenticated user.

Response 200

data
array
total
integer
get/agents/{agentId}

Get agent details

Returns full details for a single agent, including capabilities, model configuration, and metrics.

Path Parameters

agentId
string (uuid)required

UUID of the agent

Response 200

id
string (uuid)
name
string
Example: "Email Triager"
description
string
Example: "Categorizes and summarizes incoming emails"
type
string [general | email | calendar | documents | data | social | custom]
icon
string

Emoji or icon identifier

Example: "📧"
model
string
Example: "gpt-5.2"
provider
string
Example: "openai"
capabilities
array

List of skill identifiers assigned to this agent

Example: ["email-assistant","summarizer"]
isActive
boolean
totalTasksCompleted
integer
Example: 142
totalTasksFailed
integer
Example: 3
averageExecutionTime
integer

Average execution time in seconds

Example: 12
lastActiveAt
string (date-time)
createdAt
string (date-time)
updatedAt
string (date-time)
post/agents/{agentId}/execute

Execute an agent

Send a message to an agent and receive its response. The agent will use its configured tools and integrations to complete the task. Checked against your plan's monthly message quota; the agent's model does not change what a call counts for.

Path Parameters

agentId
string (uuid)required

UUID of the agent to execute

Request Body

taskrequired
string

The instruction or task to send to the agent

Example: "Summarize my last 5 emails and flag anything urgent"
timezone
string

IANA timezone for time-aware tasks

Example: "Europe/Paris"
Example
{
  "task": "Summarize my last 5 emails and flag anything urgent"
}

Response 200

id
string (uuid)

Execution ID

agentId
string (uuid)
status
string [completed | failed]
result
string

The agent's response text

toolCalls
array

Tools invoked during execution

tokensUsed
integer
Example: 1523
durationMs
integer

Execution duration in milliseconds

Example: 4200
error
string

Error message if status is `failed`

Flows

Manage automated workflows and their execution history

get/flows

List flows

Returns all flows belonging to the authenticated user.

Response 200

data
array
total
integer
get/flows/{flowId}

Get flow details

Returns full details for a single flow, including schedule, integrations, and run statistics.

Path Parameters

flowId
string (uuid)required

UUID of the flow

Response 200

id
string (uuid)
title
string
Example: "Weekly Gmail Summary to Slack"
description
string
Example: "Every Monday at 9 AM, summarize unread emails and post to #general"
icon
string
Example: "📊"
cronExpression
string
Example: "0 9 * * 1"
scheduleDescription
string
Example: "Every Monday at 9:00 AM"
timezone
string
Example: "Europe/Paris"
mode
string [auto | always_ask]

`auto` runs without intervention, `always_ask` requires approval before each execution

status
string [active | paused | error | draft]
model
string
Example: "gpt-5.2"
integrations
array

Connected services used by this flow

isRunning
boolean

Whether the flow is currently executing

estimatedHumanMinutes
integer

Estimated time a human would take (minutes) — used for Time Saved metrics

Example: 15
lastRunAt
string (date-time)
nextRunAt
string (date-time)
totalRuns
integer
Example: 87
totalFailures
integer
Example: 2
createdAt
string (date-time)
updatedAt
string (date-time)
post/flows/{flowId}/trigger

Trigger a flow

Manually trigger a flow execution outside its cron schedule. Creates a new flow run and starts execution immediately. The flow must be in `active` status.

Path Parameters

flowId
string (uuid)required

UUID of the flow to trigger

Response 200

id
string (uuid)
flowId
string (uuid)
status
string [pending | approved | running | completed | failed | skipped]
startedAt
string (date-time)
completedAt
string (date-time)
durationMs
integer

Execution time in milliseconds

Example: 8340
resultSummary
string

Human-readable summary of the run outcome

resultData
object

Structured result data (varies by flow)

toolCalls
array
tokensUsed
integer
errorMessage
string

Error details if status is `failed`

createdAt
string (date-time)
get/flows/{flowId}/runs

List flow runs

Returns the execution history for a specific flow, ordered by most recent first.

Path Parameters

flowId
string (uuid)required

UUID of the flow

Query Parameters

limit
integer

Number of runs to return (default 50, max 100)

Default: 50

Response 200

data
array
total
integer
flowId
string (uuid)
get/flows/{flowId}/runs/{runId}

Get flow run details

Returns full details for a single flow run, including tool calls, result data, and error messages.

Path Parameters

flowId
string (uuid)required
runId
string (uuid)required

UUID of the flow run

Response 200

id
string (uuid)
flowId
string (uuid)
status
string [pending | approved | running | completed | failed | skipped]
startedAt
string (date-time)
completedAt
string (date-time)
durationMs
integer

Execution time in milliseconds

Example: 8340
resultSummary
string

Human-readable summary of the run outcome

resultData
object

Structured result data (varies by flow)

toolCalls
array
tokensUsed
integer
errorMessage
string

Error details if status is `failed`

createdAt
string (date-time)

API Keys

Create and manage API keys for authentication

get/keys

List API keys

Returns all API keys for the authenticated user. Only the key prefix is returned — full keys are never retrievable after creation.

Response 200

Array of objects:
id
string (uuid)
name
string
Example: "My Production Key"
keyPrefix
string

First 12 characters of the key

Example: "flc_a1b2c3d4"
isActive
boolean
lastUsedAt
string (date-time) | null
expiresAt
string (date-time) | null
createdAt
string (date-time)
post/keys

Create an API key

Generates a new API key. The full plaintext key is returned **only in this response** — store it securely. Subsequent requests only show the prefix.

Request Body

namerequired
string

A label to identify this key (e.g. "Production", "CI/CD")

Example: "My Production Key"

Response 200

id
string (uuid)
name
string
key
string

Full plaintext API key — shown **only once**. Store it securely.

Example: "flc_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4"
keyPrefix
string
Example: "flc_a1b2c3d4"
createdAt
string (date-time)
delete/keys/{keyId}

Delete an API key

Permanently revokes an API key. Any application using this key will immediately lose access.

Path Parameters

keyId
string (uuid)required

UUID of the API key to delete

Response 200

success
boolean
Example: true

Quick Start

Get started in minutes with these code examples.

cURL — list your agents

curl -s \
  -H "Authorization: Bearer flc_your_key_here" \
  https://fleeceai.app/api/v1/agents | jq .

JavaScript / TypeScript

const FLEECE_API_KEY = process.env.FLEECE_API_KEY;
const BASE_URL = "https://fleeceai.app/api/v1";

// List all agents
const agents = await fetch(`${BASE_URL}/agents`, {
  headers: { Authorization: `Bearer ${FLEECE_API_KEY}` },
}).then(r => r.json());

console.log(`Found ${agents.length} agents`);

// Execute an agent
const result = await fetch(`${BASE_URL}/agents/${agents[0].id}/execute`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${FLEECE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: "Summarize my latest emails",
  }),
}).then(r => r.json());

console.log(result);

Python

import os
import requests

API_KEY = os.environ["FLEECE_API_KEY"]
BASE = "https://fleeceai.app/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List flows
flows = requests.get(f"{BASE}/flows", headers=headers).json()
print(f"Found {len(flows)} flows")

# Trigger a flow
run = requests.post(
    f"{BASE}/flows/{flows[0]['id']}/trigger",
    headers=headers,
).json()
print(f"Run created: {run['id']} — status: {run['status']}")

OpenAPI Specification

Download the full OpenAPI 3.1 spec to generate client libraries, import into Postman, or use with any OpenAPI-compatible tool.

Download openapi.json

Ready to build?

Create your API key in Settings and start integrating Fleece AI into your applications.

Get ProContact Sales
API Reference | Fleece AI