API Overview

The AgenFleet REST API gives you programmatic access to your agents, sessions, metrics, and webhooks. Use it to integrate AgenFleet into your own systems, automate fleet management, or build products on top of the platform.

Base URL

https://api.agenfleet.ai/v1

All endpoints are versioned under /v1. Breaking changes will be introduced under a new version prefix with at least 90 days of notice.

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer <your-api-key>

Generating an API key

Go to Settings → API Keys in the portal
Click Generate New Key
Give the key a name and select a permission scope (read-only or read-write)
Copy the key immediately — it is only shown once

API key scopes

Scope	What it allows
`read`	GET requests only — list and retrieve agents, sessions, metrics
`read-write`	Full access — create, update, delete agents, send messages, manage cron jobs

Request format

All request bodies must be JSON with Content-Type: application/json:

POST /v1/sessions
Content-Type: application/json
Authorization: Bearer <key>

{
  "agentId": "agent_01jq8...",
  "name": "Q1 Research"
}

Response format

All responses return JSON. Successful responses use 2xx status codes. The response shape depends on the endpoint — see individual endpoint documentation for schemas.

Single resource:

{
  "id": "agent_01jq8...",
  "name": "Nova",
  "status": "online",
  "createdAt": "2026-01-15T09:00:00Z"
}

List response:

{
  "data": [ ... ],
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Error format

All errors return a consistent JSON body:

{
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "No agent found with id agent_01jq8abc",
    "statusCode": 404
  }
}

Error codes

HTTP status	Code	Description
400	`VALIDATION_ERROR`	Request body failed schema validation
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Valid key but insufficient scope
404	`NOT_FOUND`	Resource does not exist or belongs to another tenant
409	`CONFLICT`	Resource already exists (e.g., duplicate agent name)
429	`RATE_LIMITED`	Too many requests — see rate limits below
500	`INTERNAL_ERROR`	Platform error — contact support with the request ID

Rate limits

Plan	Requests per minute	Requests per hour
Foundation	30	500
Operational	120	5,000
Enterprise	600	50,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1742220060

When rate limited, the response is 429 Too Many Requests. The X-RateLimit-Reset header contains the Unix timestamp when the limit resets.

Pagination

List endpoints support cursor-based pagination via limit and offset query parameters:

GET /v1/agents?limit=20&offset=40

Parameter	Default	Max	Description
`limit`	20	100	Number of results to return
`offset`	0	—	Number of results to skip

Idempotency

For POST requests that create resources, you can supply an Idempotency-Key header to safely retry requests without creating duplicates:

Idempotency-Key: a8f3b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c

Duplicate requests with the same key within 24 hours return the original response without creating a new resource.

API changelog

Version	Date	Changes
v1.0	2026-01-01	Initial release — agents, sessions, metrics
v1.1	2026-02-15	Added webhooks, activity log endpoint
v1.2	2026-03-01	Added cron job management endpoints