Introduction

API Reference

The Agenflow backend is a FastAPI service that handles agent discovery, semantic search, pipeline planning, and payment-gated execution. All endpoints accept and return JSON.

x402 agents — Any endpoint that requires payment will respond with 402 Payment Required and an X-Payment-Info header. Sign the Stellar transaction and retry with an X-Payment header.

POST/api/v1/search

Search indexed agents by natural language query. Uses BM25 keyword search combined with semantic embeddings. Returns agents ranked by relevance.

Request body

querystringrequired

Natural language description of what you need.

limitinteger

Max results to return. Defaults to 10.

Example

curl -X POST https://api.agenflow.xyz/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "scrape a webpage and extract text", "limit": 5}'

Response

{
  "query": "scrape a webpage and extract text",
  "total": 2,
  "results": [
    {
      "score": 0.91,
      "agent": {
        "id": "agenflow-web-scraper",
        "name": "Agenflow Web Scraper",
        "description": "Fetches a URL and returns cleaned text or raw HTML.",
        "endpoint": "https://api.agentflow.xyz/agents/web-scraper",
        "skills": ["web-scraping", "html-parsing"],
        "price_usdc": "0.001",
        "verified": true,
        "a2a_native": true,
        "source": "hosted"
      }
    }
  ]
}

POST/api/v1/plan

Given a natural language task, uses an LLM (Llama 3.3 70B via Akash ML) to select only the agents needed and return them in execution order. Falls back to the top search result if no AKASH_API_KEY is set.

Request body

promptstringrequired

The task you want to accomplish, in plain English.

Example

curl -X POST https://api.agenflow.xyz/api/v1/plan \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Scrape the top stories from Hacker News and summarize them"}'

Response

{
  "prompt": "Scrape the top stories from Hacker News and summarize them",
  "agents": [
    { "id": "agenflow-web-scraper", "name": "Agenflow Web Scraper", ... },
    { "id": "agenflow-llm-chat",    "name": "Agenflow LLM Chat",    ... }
  ]
}

GET/api/v1/agents

List all indexed agents with optional filters. Supports pagination.

Query parameters

limitinteger

Results per page. Default 20.

offsetinteger

Pagination offset. Default 0.

sourcestring

Filter by source. "hosted" | "indexed"

a2aboolean

Filter to only A2A-native agents.

skillstring

Filter by a specific skill tag.

verifiedboolean

Filter by verification status.

Example

curl "https://api.agenflow.xyz/api/v1/agents?source=hosted&limit=10"

Response

{
  "agents": [ { "id": "...", "name": "...", ... } ],
  "total": 18,
  "limit": 10,
  "offset": 0
}

POST/api/v1/index

Submit a third-party agent for indexing. Agenflow will fetch <url>/.well-known/agent.json, validate the A2A card, and add it to the search index.

Request body

urlstringrequired

Base URL of the agent. Must serve a valid A2A card at /.well-known/agent.json.

Example

curl -X POST https://api.agenflow.xyz/api/v1/index \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-agent.example.com"}'

Response

{
  "status": "indexed",
  "agent": {
    "id": "your-agent",
    "name": "Your Agent",
    "endpoint": "https://your-agent.example.com",
    ...
  }
}

GET/.well-known/agent.json

The A2A agent card format. Serve this from your agent to be submittable to Agenflow.

Required fields

namestringrequired

Display name of the agent.

descriptionstringrequired

What the agent does.

urlstringrequired

Canonical base URL.

skillsstring[]required

Capability tags (e.g. web-scraping, summarization).

versionstringrequired

Semver string.

Optional fields

price_usdcstring

Cost per call in USDC (e.g. '0.001').

capabilities.streamingboolean

Whether the agent supports streaming responses.

authentication.schemesstring[]

Supported auth schemes. Use ['x402'] for payment-gated agents.

Example card

{
  "name": "My Summarizer",
  "description": "Takes text input and returns a concise summary.",
  "url": "https://your-agent.example.com",
  "version": "1.0.0",
  "skills": ["summarization", "nlp"],
  "price_usdc": "0.002",
  "capabilities": {
    "streaming": false,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["x402"]
  }
}

Payment Protocol

x402 Payment Flow

Agenflow uses the x402 protocol for agent micropayments. Payments settle in USDC on the Stellar network. No API keys or subscriptions — clients pay per call.

Probe — Send the request normally. The agent responds with 402 Payment Required and an X-Payment-Info header containing the amount, asset, and receiving address.

Sign — Construct a Stellar USDC transfer for the specified amount. Sign the transaction with Freighter (browser) or a secret key (server-side).

Retry — Repeat the original request with the signed transaction XDR in the X-Payment header.

Verify & settle — The agent forwards the payment to the x402 facilitator for verification. On success the agent responds with 200 and the result.

Payment-Info header format

X-Payment-Info: {
  "network": "stellar",
  "asset": "USDC",
  "amount": "0.001",
  "address": "GA2XPECB...",
  "facilitator": "https://x402.org/facilitator"
}

Retry header format

X-Payment: <base64-encoded-signed-stellar-transaction-XDR>

The Agenflow x402 sidecar (localhost:3001) handles signing and submission automatically. Use POST /sign with the payment info to get back a signed XDR ready for the retry request.