Skip to content Skip to content Skip to content
Home › Developers › Agents API
// Agents API — /v1/agents

Agents API reference

Create, call, deploy, and monetise AI agents. All calls go to https://api.forcedream.ai/v1. L828 earnings split fires automatically on every POST /call.

78% earnings [L828-FLOOR] WORM-sealed responses REST + JSON · Auth: Bearer
// Authentication
curl https://api.forcedream.ai/v1/agents \
  -H "Authorization: Bearer fd_live_your_key_here"
# Free: fd_free_ · Pro: fd_live_ · Enterprise: fd_ent_
# Get key: forcedream.ai/app/settings/api-keys
import forcedream
client = forcedream.Client(api_key="fd_live_...")
# Or: set FD_API_KEY env var — client reads it automatically
import { ForceDreamClient } from '@forcedream/sdk'
const client = new ForceDreamClient({ apiKey: 'fd_live_...' })
// Endpoints

POST /v1/agents — Create agent

Create a new agent with archetype, pricing, markets, and WORM configuration.

curl -X POST https://api.forcedream.ai/v1/agents \
  -H "Authorization: Bearer $FD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"payment-agent","archetype":"payment_handler","price_per_call":0.10,"markets":["GB","NG","KE"],"worm_sealed":true}'
{"id":"ag_01HX9kB...","name":"payment-agent","archetype":"payment_handler","price_per_call":0.10,"markets":["GB","NG","KE"],"status":"created","worm_hash":"sha256:a3f9...","created_at":"2026-05-02T10:00:00Z"}

POST /v1/agents/{id}/call — Call agent

Invoke a published agent. Triggers the L828 platform rules split automatically — 78% credited to agent owner.

curl -X POST https://api.forcedream.ai/v1/agents/payment-agent/call \
  -H "Authorization: Bearer $CALLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"amount":10.00,"currency":"GBP","recipient":"07712345678"}}'
{"output":{"status":"processed","ref":"tx_8k2x..."},"worm_hash":"sha256:b8c1...","earnings_credited_gbp":0.08,"L828":"enforced","agent_id":"payment-agent"}

POST /v1/agents/{id}/deploy — Deploy canary

Deploy a new agent version using canary rollout. Auto-rolls back if error rate exceeds rollback_threshold.

curl -X POST https://api.forcedream.ai/v1/agents/payment-agent/deploy \
  -H "Authorization: Bearer $FD_API_KEY" \
  -d '{"strategy":"canary","rollback_threshold":0.05,"initial_traffic_pct":5}'
{"deployment_id":"dep_9z1m...","status":"deploying","traffic_pct":5,"rollback_threshold":0.05,"worm_sealed":true,"stages":["dev","staging","shadow","5%","25%","100%"]}

GET /v1/agents/{id}/earnings — Get earnings

Retrieve earnings balance, call history, and WORM-sealed split breakdown for a specific agent.

curl https://api.forcedream.ai/v1/agents/payment-agent/earnings \
  -H "Authorization: Bearer $FD_API_KEY"
{"agent_id":"payment-agent","balance_gbp":800.00,"calls_total":10000,"worm_entries":10000,"split":{"creator_pct":80,"ops_pct":17.5,"investment_pct":2.5},"withdrawable_gbp":800.00}

POST /v1/agents/{id}/publish — Publish to marketplace

List an agent on the ForceDream Marketplace. Accessible by all authenticated callers. Powered-by badge auto-added.

curl -X POST https://api.forcedream.ai/v1/agents/payment-agent/publish \
  -H "Authorization: Bearer $FD_API_KEY" \
  -d '{"title":"Payment Handler — 14 African Markets","category":"payments","description":"PawaPay + MTN + M-Pesa. WORM-sealed. FX-locked."}'
{"marketplace_url":"marketplace.forcedream.ai/agents/payment-agent","status":"listed","badge":"Built with ForceDream Studio","worm_sealed":true}

GET /v1/worm/verify/{hash} — Verify WORM entry

Verify any WORM-sealed event by its SHA-256 hash. Works for config changes, deployments, and earnings splits.

curl https://api.forcedream.ai/v1/worm/verify/sha256:a3f9c8d2 \
  -H "Authorization: Bearer $FD_API_KEY"
{"valid":true,"event_type":"earnings_split","agent_id":"payment-agent","gross_gbp":0.10,"creator_gbp":0.08,"ops_gbp":0.0175,"investment_gbp":0.0025,"timestamp":"2026-05-02T10:01:15Z"}

GET /v1/user/dashboard — User dashboard

Returns authenticated user stats: agent count, 30-day earnings, API calls, workspace count.

curl https://api.forcedream.ai/v1/user/dashboard \
  -H "Authorization: Bearer $FD_API_KEY"
{"user":{"name":"Jane Dev","email":"jane@company.com","plan":"pro"},"agent_count":8,"earnings_30d_pence":80000,"api_calls_30d":10000,"workspace_count":2}

DELETE /v1/agents/{id} — Delete agent

Permanently deletes an agent. WORM-logs the deletion event. All future calls return 404. Irreversible.

curl -X DELETE https://api.forcedream.ai/v1/agents/payment-agent \
  -H "Authorization: Bearer $FD_API_KEY"
{"deleted":true,"agent_id":"payment-agent","worm_hash":"sha256:d4e8...","deleted_at":"2026-05-02T11:00:00Z","note":"Deletion WORM-sealed — all historical data preserved"}
Full OpenAPI spec: /api/v1/openapi.json · Rate limits: Free 10 req/s · Pro 100 req/s · Enterprise unlimited · Error format: {"error":{"code":"...","message":"...","status":4xx}}