Feerasta developer portal

Everything an AI agent or developer can call on feerasta.ai: a small versioned HTTP API, a read-mostly MCP server, an OpenAPI 3.1 document and a command-line tool. It exists so an agent acting for a business owner can read what Feerasta sells, ask a question answered from approved text, and file a pilot request that a person at Feerasta reads. It does not run a customer's workflows; that happens inside the Feerasta workspace at app.feerasta.ai.

Authentication

None. Every endpoint below is public and anonymous: no account, no API key, no token. Bearer tokens are ignored. Details are in /auth.md.

Base URL and versioning

Base URL: https://feerasta.ai. The versioned API lives under /v1 and every /v1 response carries the header Feerasta-API-Version: 1.

Deprecation policy. There is no breaking change inside v1. A breaking change ships as /v2. When a version is retired, its responses carry a Deprecation header (RFC 9745) and a Sunset header (RFC 8594) at least 6 months before removal. No endpoint is deprecated today, so neither header is sent.

The older paths GET /agents.json and POST /api/contact and POST /api/ask keep working as aliases of the /v1 operations.

Quickstart

GET /v1/health

Liveness check.

curl -sS https://feerasta.ai/v1/health
# {"status":"ok"}

GET /v1/catalog

The service and pricing catalog, the same data as /agents.json.

curl -sS https://feerasta.ai/v1/catalog

POST /v1/ask

Ask a question about Feerasta. The reply is the site's published FAQ text, verbatim; a model only chooses which approved entry answers and never writes text. Field q, up to 300 characters.

curl -sS https://feerasta.ai/v1/ask \
  -H 'Content-Type: application/json' \
  -d '{"q":"What does the free plan include?"}'

POST /v1/contact and the dry_run sandbox

File a pilot request or inquiry. A person at Feerasta replies by email. Required fields: name and business (up to 200 characters each), email, message (up to 5000 characters); optional: phone, segment. The body may be JSON or form-encoded and is limited to 8192 bytes. Add "dry_run": true (or dry_run=true in a form body; /api/contact honours it too) to validate and see exactly what would be sent, without sending or storing anything. Use that to test an integration.

curl -sS https://feerasta.ai/v1/contact \
  -H 'Content-Type: application/json' \
  -d '{"name":"Test Person","business":"Test Co","email":"test@example.com","message":"Testing the API","dry_run":true}'
# {"ok":true,"dry_run":true,"would_send":{...}}

Without dry_run the same request emails a human, so confirm with your principal before sending.

Rate limits

Two limits exist in code. The ask endpoints (POST /v1/ask, POST /api/ask, POST /api/ask/feedback) allow 5 requests per 60 seconds per client and send RateLimit-Policy: "ask";q=5;w=60. The contact endpoints (POST /v1/contact, POST /api/contact and the MCP tool request_pilot) allow 3 real sends per 60 seconds per client and send RateLimit-Policy: "contact";q=3;w=60; dry runs are exempt. When the limit is hit the answer is HTTP 429 with Retry-After and RateLimit: "ask";r=0 (or "contact"); there is no t because the platform does not report the remaining seconds (draft-ietf-httpapi-ratelimit-headers). Separately, model-assisted answers have a shared daily cap; when it is reached the endpoint still answers 200 with a fallback and reason: "rate_limited_global".

The catalog and health endpoints have no per-client limit in code, so they send no RateLimit headers. Be polite anyway.

Error model

Every error from a /api/* or /v1/* path is application/problem+json (RFC 9457) with fields type, title, status, detail, code and hint. The older ok and error fields are kept for the site's own pages. The type URL is this page with the matching anchor below.

{
  "type": "https://feerasta.ai/developers#errors-not_found",
  "title": "Not found",
  "status": 404,
  "detail": "No API endpoint exists at /v1/nope.",
  "code": "not_found",
  "hint": "Check the path against https://feerasta.ai/developers, which lists every endpoint."
}

MCP server

URL: https://feerasta.ai/mcp. Transport: Streamable HTTP, stateless, protocol versions 2025-06-18 and 2025-03-26, JSON responses only, one JSON-RPC message per POST (batch arrays are rejected with 400). An MCP-Protocol-Version header other than those two is refused with 400, and an Accept header that excludes application/json with 406. GET returns 405 because the server offers no SSE stream. Browser requests from origins other than feerasta.ai are refused with 403. No authentication.

Tools. list_services and get_service read the catalog. ask_faq answers from approved FAQ text, with the same logic and limit as /v1/ask. request_pilot files a pilot request like /v1/contact, and supports dry_run. Only request_pilot is not read-only, and only without dry_run does it email a person (3 per 60 seconds per client). Invalid tool arguments return JSON-RPC error -32602; an unknown resource returns -32002.

Resources. llms.txt, openapi.json, agents.json, pricing and developers (the last two as Markdown).

Claude Code:

claude mcp add --transport http feerasta https://feerasta.ai/mcp

Project .mcp.json for Claude Code and other clients that read it:

{
  "mcpServers": {
    "feerasta": { "type": "http", "url": "https://feerasta.ai/mcp" }
  }
}

Claude Desktop, through the mcp-remote bridge, in claude_desktop_config.json:

{
  "mcpServers": {
    "feerasta": { "command": "npx", "args": ["-y", "mcp-remote", "https://feerasta.ai/mcp"] }
  }
}

A second, separate server at https://app.feerasta.ai/api/public/mcp has the tools list_services, get_service and start_trial (creates a free, draft-only workspace for a business). Use that one to start a trial; use https://feerasta.ai/mcp to ask questions or file a pilot request.

OpenAPI

The OpenAPI 3.1 document is at /openapi.json. It types every request and response, including the error model.

Command-line tool

A small zero-dependency command-line tool, feerasta, wraps the endpoints above: catalog, service <id>, ask "<question>", contact (with --dry-run) and health, each with --json. It is built but not yet published to a package registry, so for now use the curl commands above.

When to use Feerasta

Use Feerasta when the job is one of these:

• A local service business wants AI to answer its phone, text back and book appointments, with a person approving anything consequential.
• A business wants back-office work drafted for approval, such as invoice and receivables review, with nothing posted, sent or paid without its own approver.
• You need to check what Feerasta sells and what it costs: call list_services or read /pricing.
• You are acting for a principal who wants to talk to Feerasta: file a pilot request with request_pilot or POST /v1/contact.

Do not use Feerasta to place orders, take payments, make purchases or change anything in a customer's workspace. This API cannot do those things. It cannot give legal, tax or medical advice, and it publishes no customer counts, return-on-investment figures or certifications.