Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.firstflow.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Base URL

https://api.firstflow.app
Local development default: http://localhost:3002

​
Authentication

All API requests require a bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Find your API key in the Dashboard under Agent → Settings → API Keys.

​
Response envelope

Every response is wrapped in a consistent envelope: 
{
  "meta": {
    "statusCode": 200,
    "message": "OK"
  },
  "data": { ... }
}
Errors use the same structure with a 4xx or 5xx status code: 
{
  "meta": {
    "statusCode": 404,
    "message": "Experience not found"
  }
}

​
Rate limits

PlanRequests / minute
Free60
Pro600
EnterpriseUnlimited
Requests that exceed the limit receive a 429 Too Many Requests response.

​
Key endpoints

MethodPathDescription
GET/agents/:agentId/configSDK config fetch — experiences, audience memberships, and settings
GET/agents/:agentId/experiencesList all experiences for an agent
GET/agents/:agentId/experiences/:idGet a single experience
POST/agents/:agentId/experiencesCreate an experience
PATCH/agents/:agentId/experiences/:idUpdate an experience
DELETE/agents/:agentId/experiences/:idDelete an experience
POST/agents/:agentId/experiences/:id/logic-webhookReport a matched logic webhook action (idempotent)
GET/agents/:agentId/experiences/:id/analyticsExperience analytics

​
Experience object

{
  "id": "exp_abc123",
  "agentId": "agent_xyz",
  "name": "Onboarding Tour",
  "type": "tour",
  "status": "active",
  "settings": {
    "triggers": [
      { "when": "chat_opens", "conditions": [] }
    ],
    "audience": { "type": "all" },
    "device": "all",
    "frequency": { "type": "once" },
    "schedule": { "start_type": "now", "expiration_type": "none" },
    "priority": 0,
    "placement": "inlineStack"
  },
  "flow": { "nodes": [...], "edges": [...] },
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T12:00:00Z"
}
The flow field contains the full editor graph. The API also persists a flowRuntime field — a stripped version used by the SDK — derived automatically from flow on each save.

​
SDK config endpoint

The SDK calls this endpoint on mount: 
GET /agents/:agentId/config
Response includes:
  • All active experiences (with flow graphs and settings)
  • Current user’s segment memberships (if userId is provided in the JWT)
  • Agent widget UI and SDK settings
The SDK evaluates eligibility client-side from this response — no per-user API calls are made at render time.

​
Dashboard API

The Dashboard (Next.js frontend) proxies API calls through internal routes at frontend/src/app/api/**. These are not part of the public API surface and are subject to change.