Agents inside your app, in a few lines

Describe a task, the architect designs the agent, you launch it and wire its results into your product. Same architect, same prices and same dashboard as the website, through a REST API, an MCP server or a terminal.

One fa_live_… key, created in one click in the dashboard.
One card saved once, valid for every agent.
Deliverables in markdown and downloadable files, or a signed callback at the end of every run.

Create a key Connect your AI OpenAPI spec

Overview

Future Agent designs custom agents from a single sentence: a press review every morning, quote follow-ups, a PDF and Excel report sent by e-mail, a website. The public API gives your code access to the same flow.

Access	Address	For
REST API v1	`https://futureagent.app/api/v1`	Your application, scripts and automations.
MCP server	`https://futureagent.app/api/mcp`	Your AI coding tool: Claude Code, Cursor, Codex, VS Code.
CLI	`future-agent`	Your terminal and shell scripts.
OpenAPI 3.1 spec	/api/v1/openapi.json	Generate a client, import into Postman or Insomnia.

Every agent created through the API shows up in the account's dashboard with an API, MCP or CLI badge, and can be taken over by hand at any time. Responses are JSON, dates are ISO 8601 (UTC), amounts are in euro cents including VAT.

There is no extra charge for the API: an agent launched from your code costs the same as one launched from the website, and its price is always computed by the server.

Quickstart

Four calls stand between your brief and the first deliverable.

Create a key
Open Dashboard › Developers, create a key and copy it: it is shown only once. Keep it in an environment variable on your server.

Describe the agent

The architect designs the agent without blocking questions: it picks safe defaults, lists them in proposal.assumptions and returns the computed price.

Design an agent

export FUTURE_AGENT_API_KEY=fa_live_…

curl -s https://futureagent.app/api/v1/agents \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brief":"Every Monday, a PDF summary of the Google reviews for my restaurant"}'

Response 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Here is the proposed agent. Launch it to start next Monday.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Google reviews digest",
    "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
    "objective": "Track the restaurant's online reputation without spending time on it.",
    "kind": "automation",
    "language": "en",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Every Monday at 8:00"
    },
    "steps": [
      {
        "title": "Read new reviews",
        "description": "Collects the reviews posted since the last run."
      },
      {
        "title": "Write the report",
        "description": "Average rating, recurring themes, reviews to handle first."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "2-page PDF report"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Send the report by e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Never reply publicly to a review."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Week of October 5\n\nAverage rating: 4.6 (12 new reviews)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "€29/month",
      "rationale": "Weekly web research and a PDF report."
    },
    "assumptions": [
      "Delivered by e-mail to [email protected], Mondays at 8:00 (Paris time)."
    ],
    "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Send the report by e-mail.",
      "connected": true
    }
  ]
}

3
Launch it
Show the price to the user, then pass the confirmed amount as expectedMonthlyCents. With a saved card, the agent starts right away with a 7-day trial. Without one, the response contains checkoutUrl, a payment page to open once.
Launch the agent
```
curl -s -X POST https://futureagent.app/api/v1/agents/agt_8f2k1x/launch \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedMonthlyCents": 2900}'
```

Run it and read the result

Run now

curl -s -X POST https://futureagent.app/api/v1/agents/agt_8f2k1x/runs \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"inputs": {"city": "Lyon"}}'

Read the run

curl -s https://futureagent.app/api/v1/runs/run_3m9q7d -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "id": "run_3m9q7d",
  "agentId": "agt_8f2k1x",
  "status": "succeeded",
  "trigger": "manual",
  "createdAt": "2026-10-05T06:00:00.000Z",
  "startedAt": "2026-10-05T06:00:00.000Z",
  "finishedAt": "2026-10-05T06:02:41.000Z",
  "durationMs": 161000,
  "summary": "12 new reviews, average rating 4.6.",
  "output": "## Week of October 5\n\nAverage rating: 4.6…",
  "files": [
    {
      "id": "art_7c4n2b",
      "name": "google-reviews-week-41.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "createdAt": "2026-10-05T06:02:40.000Z",
      "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
    }
  ],
  "error": null,
  "inputRequest": null
}

Authentication

Every request carries the Authorization: Bearer fa_live_… header. A key belongs to an account (never an anonymous visitor) and never grants more than that account: its limits, each agent's budget and its safeguards still apply.

Key scopes
Scope	What it allows
`agents:read`	Read agents, their state and their proposals.
`agents:write`	Design agents, answer the architect, message an agent, start from a template.
`agents:launch`	Launch an agent, which starts its subscription with the saved card.
`runs:read`	Read runs, deliverables and files.
`runs:write`	Run an agent and answer its requests during a run.
`templates:read`	Browse the template library.
`webhooks:write`	Configure webhooks.
`account:read`	Read the account, the saved card and the remaining quotas.

By default a key has every scope. Untick agents:launch for a key that designs and runs agents but can never start a subscription.
The secret is shown only at creation. The dashboard then shows only its prefix (fa_live_a1b2c3d4) and when it was last used.
Revoke a key from the dashboard: it stops working immediately (unauthorized error).
Message language: Accept-Language header (fr or en) or the locale field. Defaults to the account's language.
Opaque prefixed ids: agt_… (agent), run_… (run), art_… (file), whk_… (webhook).

The API accepts browser calls (open CORS), but a key in a web page is a published key. Call the API from your server.

Agent lifecycle

Design, complete, launch, run, collect. Each step has its call, and each response tells you what to do next.

1. Design: direct or conversation mode

POST /agents { brief } runs the architect in direct mode (the default): it designs without waiting for answers, with safe choices (nothing sent to a third party without a known recipient, delivery in the dashboard), and returns only the questions that have no safe default. Pass what you already know in answers and the apps to use in connectors.

Conversation mode continues the same design: the chatId you received, answers in answers, or a free message in message.

Answer the architect

curl -s https://futureagent.app/api/v1/agents \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"conversation","chatId":"chat_5t1w0z","answers":{"restaurant":"Le Comptoir"},"message":"Fridays at 5pm instead, and in Excel."}'

Design status field
status	Meaning	Next step
`needs_answers`	Questions are still open (`questions`).	Answer in conversation mode.
`needs_connections`	An app must be connected (`connectors[].connectUrl`).	Have the user open the link, then read the proposal again.
`proposed`	The proposal is ready and the agent exists (`agentId`).	Show the price, then launch.
`preview_ready`	Website: the preview is built (`previewUrl`).	Show it, then launch.

2. Connect apps

When the agent needs Gmail, Google Sheets, Slack or another app, each unconnected connector carries a connectUrl: a signed link to open in a browser, connected in one click. Then GET /agents/:id/proposal reads the state again without a new call to the architect.

3. Proposal and price

The proposal describes the agent: name, readable schedule (schedule.humanReadable), steps, deliverables, rules, connectors, per-run input form (perRunInputs) and a sample deliverable. The price (price.monthlyCents, price.formatted) is computed by the server from difficulty and frequency; you never set it.

4. Launch: the card, once

POST /agents/:id/launch starts the agent according to the account's actual offer: included in the plan, welcome offer, first agent free, or a 7-day trial followed by a charge to the card already saved, with no new payment page. A card added once (Dashboard › Billing or Developers) covers every agent, whether it comes from the website, WhatsApp, the API, MCP or the CLI.

Response: active agent

{
  "status": "active",
  "agentId": "agt_8f2k1x",
  "mode": "trial",
  "trialEndsAt": "2026-10-12T09:12:00.000Z",
  "firstRunId": null,
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "€29/month",
    "rationale": "Weekly web research and a PDF report."
  }
}

Response: no saved card

{
  "status": "checkout_required",
  "agentId": "agt_8f2k1x",
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_…",
  "firstChargeAt": "2026-10-12T09:12:00.000Z",
  "amountCents": 2900
}

Always pass expectedMonthlyCents, the price the user saw. If it no longer matches the actual price, nothing is launched or charged: you get conflict with the new amount.

Response 409

{
  "error": {
    "code": "conflict",
    "message": "The price changed: €39/month. Show this price to the user, then launch again with an updated \"expectedMonthlyCents\".",
    "docs": "https://futureagent.app/dashboard/developpeurs#erreur-conflict",
    "details": {
      "monthlyCents": 3900,
      "expectedMonthlyCents": 2900
    }
  }
}

Designing never changes an agent that is already launched. A new version proposed by the architect applies only on the next launch call (updated: true).

5. Run with inputs

A launched agent runs on its schedule. POST /agents/:id/runs runs it right now: inputs fills its perRunInputs form (file fields take art_… ids), instructions adds a one-off instruction, test: true makes a trial run that never triggers linked agents. The 202 response returns runId. If a run is already in progress, its id comes back with alreadyRunning: true.

6. Read the result and files

GET /runs/:id returns the status (queued, running, succeeded, failed, skipped, needs_input), the summary, the full deliverable in markdown (output) and files with a signed downloadUrl, valid for 7 days and downloadable without a key. Add ?log=1 for the readable step log.

In needs_input, the agent is waiting for information or a connection (inputRequest.fields, inputRequest.connection). Answer with POST /runs/:id/answer: a resume run starts, and its id is resumedRunId.

Answer an agent during a run

curl -s -X POST https://futureagent.app/api/v1/runs/run_3m9q7d/answer \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values": {"recipient": "[email protected]"}}'

// Server side only: the key must never reach the browser.
const API = "https://futureagent.app/api/v1";

export async function fa<T>(path: string, init: RequestInit = {}): Promise<T> {
  const res = await fetch(`${API}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.FUTURE_AGENT_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error.message), body.error);
  return body as T;
}

// Run an agent and wait for its deliverable.
export async function runAndWait(agentId: string, inputs: Record<string, string> = {}) {
  const { runId } = await fa<{ runId: string }>(`/agents/${agentId}/runs`, {
    method: "POST",
    headers: { "Idempotency-Key": crypto.randomUUID() },
    body: JSON.stringify({ inputs }),
  });
  let delay = 3000;
  for (;;) {
    const run = await fa<{ status: string; output: string | null; files: { name: string; downloadUrl: string }[] }>(`/runs/${runId}`);
    if (!["queued", "running"].includes(run.status)) return run;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 30_000);
  }
}

Signed webhooks

Instead of polling the API, receive a signed POST at the end of every run.

PUT /webhook { url } registers your application's address for the whole account, or for a single agent with agentId. The whsec_… signing secret is returned only at creation or with rotateSecret: true: store it right away. url: null deletes the webhook.

curl -s -X PUT https://futureagent.app/api/v1/webhook \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/hooks/future-agent", "events": ["run.finished", "run.needs_input"]}'

Events
Event	When
`run.finished`	A run ends (succeeded, failed or skipped). The body contains the full run.
`run.needs_input`	A run is waiting for an answer or a connection.
`agent.activated`	An agent was just launched (for example after payment).
`agent.paused`	An agent was paused.

Headers: Future-Agent-Signature: t=<unix>,v1=<hex> (copied to X-FutureAgent-Signature), Future-Agent-Event, Future-Agent-Delivery.
v1 = HMAC-SHA256 of the text <t>.<raw body> with your secret. During a rotation, several v1= values may appear: accept any valid one.
Reject a timestamp more than 300 seconds away from your clock: it is a replay.
Answer 2xx within 10 seconds, then do the work. At most three attempts: immediately, after 30 seconds, after 5 minutes.
Future-Agent-Delivery is the same on every attempt: skip an id you already handled.
Public https addresses only (http only to localhost in development), no private address, no redirect followed. After 20 consecutive failures, the webhook is disabled. At most 50 webhooks per account.

run.finished delivery body

{
  "id": "evt_9w3e5r",
  "event": "run.finished",
  "createdAt": "2026-10-05T06:02:42.000Z",
  "agentId": "agt_8f2k1x",
  "run": {
    "id": "run_3m9q7d",
    "agentId": "agt_8f2k1x",
    "status": "succeeded",
    "trigger": "manual",
    "createdAt": "2026-10-05T06:00:00.000Z",
    "startedAt": "2026-10-05T06:00:00.000Z",
    "finishedAt": "2026-10-05T06:02:41.000Z",
    "durationMs": 161000,
    "summary": "12 new reviews, average rating 4.6.",
    "output": "## Week of October 5\n\nAverage rating: 4.6…",
    "files": [
      {
        "id": "art_7c4n2b",
        "name": "google-reviews-week-41.pdf",
        "mimeType": "application/pdf",
        "size": 184320,
        "createdAt": "2026-10-05T06:02:40.000Z",
        "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
      }
    ],
    "error": null,
    "inputRequest": null
  }
}

// app/api/future-agent/webhook/route.ts (Next.js, Node.js)
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret: string, body: string, header: string | null, toleranceSeconds = 300) {
  if (!header) return false;
  const parts = header.split(",").map((p) => p.trim());
  const t = Number(parts.find((p) => p.startsWith("t="))?.slice(2));
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${body}`).digest("hex"));
  return parts.filter((p) => p.startsWith("v1=")).some((p) => {
    const got = Buffer.from(p.slice(3));
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

export async function POST(request: Request) {
  const body = await request.text(); // raw body: verify BEFORE JSON.parse
  if (!verify(process.env.FUTURE_AGENT_WEBHOOK_SECRET!, body, request.headers.get("future-agent-signature"))) {
    return new Response("invalid signature", { status: 400 });
  }
  const event = JSON.parse(body);
  // Future-Agent-Delivery is the same on every attempt: skip an id you already handled.
  if (event.event === "run.finished" && event.run?.status === "succeeded") {
    // event.run.output (markdown), event.run.files[].downloadUrl (signed links)
  }
  return new Response(null, { status: 204 });
}

Without a webhook, poll GET /runs/:id every 3 to 5 seconds with a growing interval, as in the minimal client above. Over MCP, run_agent can wait up to 55 seconds for the run to finish (waitSeconds).

API reference

Base: https://futureagent.app/api/v1. Every response is JSON with Cache-Control: no-store. This reference is generated from the OpenAPI specification.

GET/api/v1/agentsScope agents:read

List agents

The account's agents, newest first, across every channel (website, WhatsApp, API, MCP, CLI).

Parameters
Name	Type	Description
`status`"draft" \| "awaiting_payment" \| "active" \| "paused" \| "error"query, optional	"draft" \| "awaiting_payment" \| "active" \| "paused" \| "error"	Filter by status.
`source`"web" \| "whatsapp" \| "api" \| "mcp" \| "cli"query, optional	"web" \| "whatsapp" \| "api" \| "mcp" \| "cli"	Filter by creation channel.
`limit`integerquery, optional	integer	Items per page.
`cursor`stringquery, optional	string	`nextCursor` value from the previous page.

Request

curl -s "https://futureagent.app/api/v1/agents?status=active&limit=20" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "data": [
    {
      "id": "agt_8f2k1x",
      "name": "Google reviews digest",
      "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
      "kind": "automation",
      "status": "active",
      "source": "api",
      "schedule": {
        "type": "schedule",
        "cron": "0 8 * * 1",
        "timezone": "Europe/Paris",
        "humanReadable": "Every Monday at 8:00"
      },
      "price": {
        "monthlyCents": 2900,
        "billedMonthlyCents": 2900,
        "currency": "eur",
        "formatted": "€29/month",
        "rationale": "Weekly web research and a PDF report."
      },
      "billingMode": "trial",
      "nextRunAt": "2026-10-12T06:00:00.000Z",
      "lastRunAt": "2026-10-05T06:00:00.000Z",
      "createdAt": "2026-10-01T09:12:00.000Z",
      "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x"
    }
  ],
  "nextCursor": null
}

Possible errors: 401, 403, 429

POST/api/v1/agentsScope agents:write

Design an agent

Direct mode (default): design without blocking questions from brief. Conversation mode: continue a design with chatId. Nothing is charged at this step.

ParametersBody variants: direct | conversation
Name	Type	Description
`Idempotency-Key`stringheader, optional	string	Same key = same resource for 24 h.
`mode`"direct" \| "conversation"body, optional	"direct" \| "conversation"	"direct" (default) or "conversation".
`brief`stringbody, optional	string	The task, in one or two sentences (direct mode).
`answers`objectbody, optional	object	Answers you already know: question id (or label) → value.
`connectors`string[]body, optional	string[]	Apps to use if possible (gmail, googlesheets, slack…).
`locale`"fr" \| "en"body, optional	"fr" \| "en"	Language of the agent and messages: fr or en.
`idempotencyKey`stringbody, optional	string	Same key = same design for 24 h.
`chatId`stringbody, optional	string	Conversation to continue (conversation mode).
`message`stringbody, optional	string	Free message to the architect (conversation mode).

Request

curl -s -X POST "https://futureagent.app/api/v1/agents" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Idempotency-Key: 8d1c5e0a-brief-1" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Every Monday at 8am, a PDF summary of my restaurant'\''s Google reviews, sent to [email protected]",
    "connectors": [
      "gmail"
    ],
    "answers": {
      "city": "Lyon"
    }
  }'

Response 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Here is the proposed agent. Launch it to start next Monday.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Google reviews digest",
    "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
    "objective": "Track the restaurant's online reputation without spending time on it.",
    "kind": "automation",
    "language": "en",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Every Monday at 8:00"
    },
    "steps": [
      {
        "title": "Read new reviews",
        "description": "Collects the reviews posted since the last run."
      },
      {
        "title": "Write the report",
        "description": "Average rating, recurring themes, reviews to handle first."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "2-page PDF report"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Send the report by e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Never reply publicly to a review."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Week of October 5\n\nAverage rating: 4.6 (12 new reviews)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "€29/month",
      "rationale": "Weekly web research and a PDF report."
    },
    "assumptions": [
      "Delivered by e-mail to [email protected], Mondays at 8:00 (Paris time)."
    ],
    "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Send the report by e-mail.",
      "connected": true
    }
  ]
}

Possible errors: 400, 401, 403, 404, 409, 429

GET/api/v1/agents/{id}Scope agents:read

Get an agent

Readable state, schedule, price, connectors, per-run input form, pending request and this month's usage level.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.

Request

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "id": "agt_8f2k1x",
  "name": "Google reviews digest",
  "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
  "kind": "automation",
  "status": "active",
  "source": "api",
  "schedule": {
    "type": "schedule",
    "cron": "0 8 * * 1",
    "timezone": "Europe/Paris",
    "humanReadable": "Every Monday at 8:00"
  },
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "€29/month",
    "rationale": "Weekly web research and a PDF report."
  },
  "billingMode": "trial",
  "nextRunAt": "2026-10-12T06:00:00.000Z",
  "lastRunAt": "2026-10-05T06:00:00.000Z",
  "createdAt": "2026-10-01T09:12:00.000Z",
  "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x",
  "objective": "Track the restaurant's online reputation without spending time on it.",
  "state": {
    "code": "ready",
    "label": "Next run Monday at 8:00",
    "action": null
  },
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Send the report by e-mail.",
      "connected": true
    }
  ],
  "capabilities": [
    "web_research",
    "files",
    "email"
  ],
  "outputs": [
    {
      "format": "pdf",
      "description": "2-page PDF report"
    }
  ],
  "perRunInputs": [
    {
      "id": "city",
      "label": "City",
      "type": "text",
      "required": false,
      "placeholder": "Lyon"
    }
  ],
  "pendingInput": null,
  "usage": "normal",
  "publicUrl": null,
  "webhook": true
}

Possible errors: 401, 403, 404

GET/api/v1/agents/{id}/proposalScope agents:read

Read the design

Latest design state, by agent id or chatId, without a new call to the architect.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.

Request

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x/proposal" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Here is the proposed agent. Launch it to start next Monday.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Google reviews digest",
    "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
    "objective": "Track the restaurant's online reputation without spending time on it.",
    "kind": "automation",
    "language": "en",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Every Monday at 8:00"
    },
    "steps": [
      {
        "title": "Read new reviews",
        "description": "Collects the reviews posted since the last run."
      },
      {
        "title": "Write the report",
        "description": "Average rating, recurring themes, reviews to handle first."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "2-page PDF report"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Send the report by e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Never reply publicly to a review."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Week of October 5\n\nAverage rating: 4.6 (12 new reviews)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "€29/month",
      "rationale": "Weekly web research and a PDF report."
    },
    "assumptions": [
      "Delivered by e-mail to [email protected], Mondays at 8:00 (Paris time)."
    ],
    "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Send the report by e-mail.",
      "connected": true
    }
  ]
}

Possible errors: 401, 403, 404

POST/api/v1/agents/{id}/launchScope agents:launch

Launch an agent

Starts the agent according to the account's offer. With a saved card: status: "active". Without one: status: "checkout_required" and a checkoutUrl to open once.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`expectedMonthlyCents`integerbody, optional	integer	Monthly price incl. VAT confirmed by the user, in cents. If it differs from the actual price: 409, nothing is charged.
`returnUrl`stringbody, optional	string	Reserved: accepted, currently ignored.

Request

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/launch" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedMonthlyCents": 2900
  }'

Response 200

{
  "status": "active",
  "agentId": "agt_8f2k1x",
  "mode": "trial",
  "trialEndsAt": "2026-10-12T09:12:00.000Z",
  "firstRunId": null,
  "price": {
    "monthlyCents": 2900,
    "billedMonthlyCents": 2900,
    "currency": "eur",
    "formatted": "€29/month",
    "rationale": "Weekly web research and a PDF report."
  }
}

Possible errors: 401, 402, 403, 404, 409, 429

GET/api/v1/agents/{id}/runsScope runs:read

List runs

The agent's runs, newest first, without the log.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`status`"queued" \| "running" \| "succeeded" \| "failed" \| "skipped" \| "needs_input"query, optional	"queued" \| "running" \| "succeeded" \| "failed" \| "skipped" \| "needs_input"	Filter by status.
`limit`integerquery, optional	integer	Items per page.
`cursor`stringquery, optional	string	`nextCursor` value from the previous page.

Request

curl -s "https://futureagent.app/api/v1/agents/agt_8f2k1x/runs?limit=10" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "data": [
    {
      "id": "run_3m9q7d",
      "agentId": "agt_8f2k1x",
      "status": "succeeded",
      "trigger": "manual",
      "createdAt": "2026-10-05T06:00:00.000Z",
      "startedAt": "2026-10-05T06:00:00.000Z",
      "finishedAt": "2026-10-05T06:02:41.000Z",
      "durationMs": 161000,
      "summary": "12 new reviews, average rating 4.6.",
      "output": "## Week of October 5\n\nAverage rating: 4.6…",
      "files": [
        {
          "id": "art_7c4n2b",
          "name": "google-reviews-week-41.pdf",
          "mimeType": "application/pdf",
          "size": 184320,
          "createdAt": "2026-10-05T06:02:40.000Z",
          "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
        }
      ],
      "error": null,
      "inputRequest": null
    }
  ],
  "nextCursor": null
}

Possible errors: 401, 403, 404

POST/api/v1/agents/{id}/runsScope runs:write

Run an agent

Starts a background run and answers 202 with runId. An idempotent replay or a run already in progress answers 200.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`Idempotency-Key`stringheader, optional	string	Same key = same run for 24 h.
`inputs`objectbody, optional	object	Values of the `perRunInputs` form (id → value; files: `art_…` ids).
`instructions`stringbody, optional	string	One-off instruction for this run.
`test`booleanbody, optional	boolean	Trial run: never triggers linked agents.
`idempotencyKey`stringbody, optional	string	Same key = same run for 24 h.

Request

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/runs" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "city": "Lyon"
    }
  }'

Response 202

{
  "runId": "run_3m9q7d",
  "status": "queued",
  "agentId": "agt_8f2k1x",
  "replayed": false
}

Possible errors: 400, 401, 402, 403, 404, 409, 429

POST/api/v1/agents/{id}/messagesScope agents:write

Message an agent

Like the agent's conversation in the dashboard: adjust its behavior, ask a question, hand it a file. Returns its reply, and runId if a run starts.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`text`stringbody, required	string	Message text.
`attachments`string[]body, optional	string[]	Files already uploaded (`art_…`).

Request

curl -s -X POST "https://futureagent.app/api/v1/agents/agt_8f2k1x/messages" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Add the Paris restaurant too."
  }'

Response 200

{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "kind": "text",
      "text": "Add the Paris restaurant too.",
      "createdAt": "2026-10-05T06:00:00.000Z"
    },
    {
      "id": "msg_2",
      "role": "agent",
      "kind": "text",
      "text": "Noted: I'll add the Paris restaurant from the next run.",
      "createdAt": "2026-10-05T06:00:00.000Z"
    }
  ],
  "runId": null
}

Possible errors: 400, 401, 403, 404, 429

GET/api/v1/runs/{id}Scope runs:read

Get a run

Status, summary, markdown deliverable, files with signed links (7 days), readable error and pending request.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`log`"1" \| "true"query, optional	"1" \| "true"	1 = include the readable step log.

Request

curl -s "https://futureagent.app/api/v1/runs/run_3m9q7d?log=1" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "id": "run_3m9q7d",
  "agentId": "agt_8f2k1x",
  "status": "succeeded",
  "trigger": "manual",
  "createdAt": "2026-10-05T06:00:00.000Z",
  "startedAt": "2026-10-05T06:00:00.000Z",
  "finishedAt": "2026-10-05T06:02:41.000Z",
  "durationMs": 161000,
  "summary": "12 new reviews, average rating 4.6.",
  "output": "## Week of October 5\n\nAverage rating: 4.6…",
  "files": [
    {
      "id": "art_7c4n2b",
      "name": "google-reviews-week-41.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "createdAt": "2026-10-05T06:02:40.000Z",
      "downloadUrl": "https://futureagent.app/api/files/art_7c4n2b?sig=…"
    }
  ],
  "error": null,
  "inputRequest": null,
  "log": [
    {
      "at": "2026-10-05T06:02:40.000Z",
      "level": "info",
      "message": "PDF report saved."
    }
  ]
}

Possible errors: 401, 403, 404

POST/api/v1/runs/{id}/answerScope runs:write

Answer a run

Answers a run in needs_input. A resume run starts: resumedRunId. Alias: POST /runs/{id}/input.

Parameters
Name	Type	Description
`id`stringpath, required	string	Id: `agt_…` for an agent, `run_…` for a run.
`values`objectbody, required	object	Field id (`inputRequest.fields`) → value.

Request

curl -s -X POST "https://futureagent.app/api/v1/runs/run_3m9q7d/answer" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "recipient": "[email protected]"
    }
  }'

Response 202

{
  "runId": "run_3m9q7d",
  "resumedRunId": "run_4p0s8e"
}

Possible errors: 400, 401, 403, 404, 409

GET/api/v1/templatesScope templates:read

Search templates

Library templates, with their computed price and the personal questions the architect will ask.

Parameters
Name	Type	Description
`q`stringquery, optional	string	Free text search.
`category`stringquery, optional	string	Category.
`secteur`stringquery, optional	string	Sector (e.g. restauration) or "tous".
`metier`stringquery, optional	string	Job (e.g. comptabilite).
`kind`stringquery, optional	string	automation, project or chain.
`limit`integerquery, optional	integer	Items per page.
`cursor`stringquery, optional	string	`nextCursor` value from the previous page.

Request

curl -s "https://futureagent.app/api/v1/templates?q=press%20review&limit=5" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "data": [
    {
      "slug": "revue-de-presse",
      "name": "Daily press review",
      "summary": "Today's articles on your topics, summarized and sent every morning.",
      "category": "Monitoring",
      "kind": "automation",
      "sectors": [
        "tous"
      ],
      "roles": [
        "direction"
      ],
      "connectors": [
        "gmail"
      ],
      "price": {
        "monthlyCents": 1900,
        "billedMonthlyCents": 1900,
        "currency": "eur",
        "formatted": "€19/month"
      },
      "questions": [
        "Which topics should it follow?"
      ],
      "url": "https://futureagent.app/en/bibliotheque/revue-de-presse"
    }
  ],
  "nextCursor": null
}

Possible errors: 401, 403

POST/api/v1/templates/{slug}/agentsScope agents:write

Start from a template

Designs an agent from a template: the architect only needs its personal questions.

Parameters
Name	Type	Description
`slug`stringpath, required	string	Template slug, as returned by `GET /templates`.
`Idempotency-Key`stringheader, optional	string	Same key = same resource for 24 h, no duplicate.
`step`integerbody, optional	integer	Agent within a chain of linked agents (0 by default).
`answers`objectbody, optional	object	Answers to the template's questions.
`locale`"fr" \| "en"body, optional	"fr" \| "en"	fr or en.
`idempotencyKey`stringbody, optional	string	Same key = same design for 24 h.

Request

curl -s -X POST "https://futureagent.app/api/v1/templates/revue-de-presse/agents" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "topic": "electric bikes"
    }
  }'

Response 201

{
  "status": "proposed",
  "chatId": "chat_5t1w0z",
  "agentId": "agt_8f2k1x",
  "message": "Here is the proposed agent. Launch it to start next Monday.",
  "proposal": {
    "chatId": "chat_5t1w0z",
    "agentId": "agt_8f2k1x",
    "name": "Google reviews digest",
    "summary": "Summarizes the restaurant's new Google reviews every week in a PDF sent to the team.",
    "objective": "Track the restaurant's online reputation without spending time on it.",
    "kind": "automation",
    "language": "en",
    "schedule": {
      "type": "schedule",
      "cron": "0 8 * * 1",
      "timezone": "Europe/Paris",
      "humanReadable": "Every Monday at 8:00"
    },
    "steps": [
      {
        "title": "Read new reviews",
        "description": "Collects the reviews posted since the last run."
      },
      {
        "title": "Write the report",
        "description": "Average rating, recurring themes, reviews to handle first."
      }
    ],
    "capabilities": [
      "web_research",
      "files",
      "email"
    ],
    "outputs": [
      {
        "format": "pdf",
        "description": "2-page PDF report"
      }
    ],
    "connectors": [
      {
        "toolkit": "gmail",
        "name": "Gmail",
        "reason": "Send the report by e-mail.",
        "connected": true
      }
    ],
    "perRunInputs": [],
    "rules": [
      "Never reply publicly to a review."
    ],
    "delivery": {
      "channel": "email",
      "target": "[email protected]",
      "format": "pdf"
    },
    "exampleOutput": "## Week of October 5\n\nAverage rating: 4.6 (12 new reviews)…",
    "price": {
      "monthlyCents": 2900,
      "billedMonthlyCents": 2900,
      "currency": "eur",
      "formatted": "€29/month",
      "rationale": "Weekly web research and a PDF report."
    },
    "assumptions": [
      "Delivered by e-mail to [email protected], Mondays at 8:00 (Paris time)."
    ],
    "dashboardUrl": "https://futureagent.app/en/dashboard/agents/agt_8f2k1x"
  },
  "questions": [],
  "connectors": [
    {
      "toolkit": "gmail",
      "name": "Gmail",
      "reason": "Send the report by e-mail.",
      "connected": true
    }
  ]
}

Possible errors: 400, 401, 403, 404, 429

GET/api/v1/webhooksScope webhooks:write

List webhooks

The account's webhooks, with the date and status of the last delivery and the number of consecutive failures.

Request

curl -s "https://futureagent.app/api/v1/webhooks" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "data": [
    {
      "id": "whk_2j6v9c",
      "url": "https://app.example.com/hooks/future-agent",
      "agentId": null,
      "events": [
        "run.finished",
        "run.needs_input"
      ],
      "active": true,
      "lastDeliveryAt": "2026-10-05T06:00:00.000Z",
      "lastStatus": 204,
      "failures": 0
    }
  ]
}

Possible errors: 401, 403

PUT/api/v1/webhooksScope webhooks:write

Set a webhook

Creates or updates the account's webhook, or an agent's with agentId. url: null deletes it. Alias: PUT /webhook.

Parameters
Name	Type	Description
`url`string \| nullbody, required	string \| null	Public https address, or null to delete.
`agentId`stringbody, optional	string	A single agent; absent: the whole account.
`events`("run.finished" \| "run.needs_input" \| "agent.activated" \| "agent.paused")[]body, optional	("run.finished" \| "run.needs_input" \| "agent.activated" \| "agent.paused")[]	Events to receive (all by default).
`rotateSecret`booleanbody, optional	boolean	New secret: the old one stops working.

Request

curl -s -X PUT "https://futureagent.app/api/v1/webhook" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/hooks/future-agent",
    "events": [
      "run.finished",
      "run.needs_input"
    ]
  }'

Response 200

{
  "deleted": false,
  "id": "whk_2j6v9c",
  "url": "https://app.example.com/hooks/future-agent",
  "agentId": null,
  "events": [
    "run.finished",
    "run.needs_input"
  ],
  "active": true,
  "secret": "whsec_…"
}

Possible errors: 400, 401, 403, 404

DELETE/api/v1/webhooksScope webhooks:write

Delete a webhook

Deletes the account's webhook, or an agent's with ?agentId=.

Parameters
Name	Type	Description
`agentId`stringquery, optional	string	Agent concerned.

Request

curl -s -X DELETE "https://futureagent.app/api/v1/webhooks?agentId=agt_8f2k1x" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "deleted": true,
  "agentId": "agt_8f2k1x"
}

Possible errors: 401, 403, 404

GET/api/v1/accountScope account:read

Get the account

Plan, saved card (last 4 digits), what the next launch will be, number of agents, storage and remaining quotas.

Request

curl -s "https://futureagent.app/api/v1/account" \
  -H "Authorization: Bearer $FUTURE_AGENT_API_KEY"

Response 200

{
  "user": {
    "id": "usr_1a2b3c",
    "name": "Alex Morgan",
    "email": "[email protected]"
  },
  "plan": {
    "id": "libre",
    "name": "Free"
  },
  "card": {
    "saved": true,
    "brand": "visa",
    "last4": "4242"
  },
  "nextLaunch": {
    "kind": "trial",
    "trialDays": 7
  },
  "agents": {
    "total": 3,
    "active": 2
  },
  "usage": "normal",
  "storage": {
    "usedBytes": 52428800,
    "quotaBytes": 1073741824,
    "level": "low"
  },
  "limits": {
    "requestsPerMinute": 120,
    "createsPerDay": {
      "limit": 50,
      "used": 2
    },
    "runsPerDay": {
      "limit": 300,
      "used": 14
    },
    "messagesPerDay": {
      "limit": 300,
      "used": 0
    },
    "launchesPerDay": {
      "limit": 50,
      "used": 1
    }
  },
  "billingUrl": "https://futureagent.app/en/dashboard/facturation",
  "dashboardUrl": "https://futureagent.app/en/dashboard"
}

Possible errors: 401, 403

MCP server

Give your AI coding tool what it needs to design, launch, run and integrate your agents, without writing the calls yourself.

Address: https://futureagent.app/api/mcp. Stateless Streamable HTTP transport, Authorization: Bearer fa_live_… on every request. The server exposes 15 tools, readable guides (future-agent://guide/lifecycle, typescript, python, webhooks, errors, setup) and an integrate_agent prompt. Tool errors come back with the same body as the REST API, so the AI can adapt.

Set up your tool

Claude CodeIn a terminal, at the root of your project:

Claude Code

claude mcp add --transport http future-agent https://futureagent.app/api/mcp \
  --header "Authorization: Bearer fa_live_…"

CursorIn ~/.cursor/mcp.json (or .cursor/mcp.json for one project):

Cursor

{
  "mcpServers": {
    "future-agent": {
      "url": "https://futureagent.app/api/mcp",
      "headers": {
        "Authorization": "Bearer fa_live_…"
      }
    }
  }
}

CodexIn ~/.codex/config.toml, with the key in the FUTURE_AGENT_API_KEY variable:

Codex

# export FUTURE_AGENT_API_KEY=fa_live_…
[mcp_servers.future-agent]
url = "https://futureagent.app/api/mcp"
bearer_token_env_var = "FUTURE_AGENT_API_KEY"

VS CodeIn .vscode/mcp.json: VS Code asks for the key on first start and stores it encrypted.

VS Code

{
  "inputs": [
    {
      "type": "promptString",
      "id": "future-agent-key",
      "description": "Future Agent API key",
      "password": true
    }
  ],
  "servers": {
    "future-agent": {
      "type": "http",
      "url": "https://futureagent.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:future-agent-key}"
      }
    }
  }
}

The 15 tools

Tool	Purpose	Scope
`create_agent`	Design an agent from a brief (direct or conversation mode).	`agents:write`
`answer_architect`	Answer the architect's questions or send it a message.	`agents:write`
`get_proposal`	Read the design state again, without a new call to the architect.	`agents:read`
`launch_agent`	Launch the agent at the confirmed price (saved card, otherwise a payment link).	`agents:launch`
`list_agents`	List the account's agents, across every channel.	`agents:read`
`get_agent`	Read an agent: state, schedule, price, input form, pending request.	`agents:read`
`run_agent`	Run now, optionally waiting up to 55 seconds.	`runs:write`
`get_run`	Read a run: status, deliverable, files, log.	`runs:read`
`list_runs`	List an agent's runs.	`runs:read`
`message_agent`	Message an existing agent, as in its dashboard conversation.	`agents:write`
`answer_input_request`	Answer an agent waiting for information during a run.	`runs:write`
`list_templates`	Search the template library.	`templates:read`
`create_from_template`	Design an agent from a template.	`agents:write`
`set_webhook`	Register, change or delete the signed webhook.	`webhooks:write`
`get_account`	Read the plan, the saved card and the remaining quotas.	`account:read`

Sample conversation
- You: Create a Future Agent agent that sends me a PDF summary of my restaurant's Google reviews every Monday, and show the latest report in my Next.js app.
- AI: calls create_agent, gets the proposal "Google reviews digest, every Monday at 8:00, €29/month" with its assumptions, then asks you to confirm the price.
- You: That price works.
- AI: calls launch_agent with expectedMonthlyCents: 2900 (free trial, saved card), then set_webhook to your route, reads the webhooks guide and writes the route that verifies the signature and stores the report.
- AI: starts a trial with run_agent (test: true, waitSeconds: 55) and checks that the route receives the deliverable.

The AI asks for your approval before launching: the confirmed price goes into expectedMonthlyCents. For a key that can never start a subscription, remove the agents:launch scope.

CLI

The same flow from your terminal: npm install -g future-agent.

Commands

# Log in (hidden input)
future-agent login --base-url https://futureagent.app
future-agent whoami

# Design, launch, run
future-agent agents create "Every Monday, a PDF summary of the Google reviews for my restaurant" --connector gmail
future-agent agents launch agt_8f2k1x --expect-cents 2900
future-agent agents run agt_8f2k1x --input city=Lyon --wait --download --out ./reports

# Follow up
future-agent agents list --source cli
future-agent agents status run_3m9q7d --wait
future-agent agents logs run_3m9q7d
future-agent agents answer run_3m9q7d --value [email protected]

# Library and webhooks
future-agent templates list "press review" --secteur restauration
future-agent webhook set https://app.example.com/hooks/future-agent --event run.finished

Command	Purpose
`login`, `whoami`	Save the key (0600 file under `~/.config/future-agent`), show the account and quotas.
`agents create`	Design from a brief (`--answer`, `--connector`) or continue (`--chat`).
`agents launch`	Launch (`--expect-cents`, `--open` to open the payment page when needed).
`agents run`	Run (`--input`, `--wait`, `--download`, `--out`).
`agents list \| get \| runs \| status \| logs \| files`	Follow agents, runs, logs and files.
`agents message \| answer`	Message an agent, answer a request during a run.
`templates list \| use`	Search the template library and start from a template.
`webhook set \| delete`	Configure the signed webhook.
`mcp`	Stdio bridge to the MCP server, for tools that only start local servers.

Common options: --json (raw response), --idempotency-key, --lang fr|en, --no-color. Exit codes: 0 success, 1 API or network error, 2 usage error. Variables: FUTURE_AGENT_API_KEY, FUTURE_AGENT_BASE_URL.

Limits and quotas

120 requests per minute per key. Per account and per rolling 24 hours, across all keys (twenty keys do not give twenty times the quota):

Action	Account without a launched agent	Account with a launched agent
Designs (brief or template)	10	50
Runs	30	300
Messages to agents	60	300
Launches	10	50

30 manual runs per agent per 24 hours.
Account daily limits also apply (messages to the architect, website builds), as does each agent's monthly usage limit (budget_exhausted, with a link to the right plan).
Beyond that: a 429 error with the Retry-After header and retryAfterSeconds. GET /account returns the remaining quotas.
MCP server: at most 20 JSON-RPC messages per batch, request body up to 1 MB.

Error codes

An error always has the same shape: a stable code, a sentence that says what to do, a link to its documentation and, when relevant, details.

Error body

{
  "error": {
    "code": "invalid_request",
    "message": "…",
    "docs": "…",
    "retryAfterSeconds": 12,
    "details": { "fields": { "brief": "…" } }
  }
}

401unauthorized: Missing, invalid or revoked key: send a valid key.
403forbidden: The key lacks the required scope (details.scope) or the resource belongs to another account.
404not_found: Unknown id for this account: check it with GET /agents.
400invalid_request: Fix the fields listed in details.fields.
409conflict: Incompatible state (agent not launched yet, run already finished, price changed): read the resource again.
429rate_limited: Too many requests per minute: wait retryAfterSeconds.
429quota_exceeded: The account's daily quota for this action is reached: retry after retryAfterSeconds.
429limit_reached: The account's daily limit is reached (messages to the architect, builds): try again later.
402payment_required: A card is needed: have the user open details.checkoutUrl once, and it will cover every agent.
402budget_exhausted: The agent reached its monthly usage limit: details.raiseUrl offers the right plan.
413storage_full: Storage is full: delete files or change plan.
403account_required: A full account is required (not anonymous, not blocked).
501not_implemented: This action is not available yet.
500internal_error: Unexpected error: try again in a moment.

Idempotency

The network drops, a request goes out twice: the Idempotency-Key header (or the idempotencyKey field) prevents the duplicate. Same API key, same action and same value within 24 hours: the resource already created comes back instead of a new one.

Accepted by POST /agents, POST /agents/:id/runs and POST /templates/:slug/agents. Up to 200 characters.
A replayed run answers 200 with replayed: true instead of 202.
Use an id from your own domain (order number, event id) or a UUID generated once per operation, never a timestamp.
POST /agents/:id/launch is safe to retry: an agent that is already active is not launched again.

Best practices

Keep the key server side, one key per application, with only the scopes it needs. Revoke it at the slightest doubt.
Always confirm the price with the user and pass it as expectedMonthlyCents.
Never invent a recipient, an e-mail address or a credential: ask the user and pass the answer in answers.
Prefer webhooks to polling; verify the signature on the raw body and deduplicate with Future-Agent-Delivery.
Honor Retry-After on a 429 error and space out polling (3 seconds, then longer).
Download the files you need: signed links expire after 7 days.
Test with test: true: a trial run never triggers linked agents.
Show an agent's state.label and state.action: they tell the user what is expected (connect an app, answer).

Frequently asked questions

Does the API cost extra?

No, there is no extra charge for the API, the MCP server or the CLI. You pay for the agents you launch, at the same price as on the website, with the same free trial.

Where do agents created through the API show up?

In the account's dashboard, like any other agent, with an API, MCP or CLI badge. You can edit them, pause them or message them from the dashboard.

Can an AI launch an agent and pay without my approval?

Launching uses the saved card, which is why the tools ask to confirm the price and pass it as expectedMonthlyCents. To rule it out entirely, create a key without the agents:launch scope: it will design and run agents, but never start a subscription.

Is the CLI available on npm?

Yes: npm install -g future-agent, then future-agent login.

Can I receive a webhook on localhost?

The server only delivers to a public https address. For local development, expose your route through an https tunnel, or poll GET /runs/:id.

Does the API expose compute costs or the AI model used?

No. Responses contain prices, durations, run counts and a usage level, never an internal cost or a model name.

Which language does the agent work in?

The one requested by the locale field or the Accept-Language header (French or English), otherwise the account's language.

Ready to wire up your first agent?

Create a key, paste the MCP config or send the first curl call. Your agent shows up in your dashboard right away.

Create a key Design an agent on the website

Overview

Quickstart

Create a key

Describe the agent

Launch it

Run it and read the result

Authentication

Agent lifecycle

1. Design: direct or conversation mode

2. Connect apps

3. Proposal and price

4. Launch: the card, once

5. Run with inputs

6. Read the result and files

Signed webhooks

API reference

MCP server

Set up your tool

The 15 tools

Sample conversation

CLI

Limits and quotas

Error codes

Idempotency

Best practices

Frequently asked questions

Ready to wire up your first agent?