Portal de programadores da Feerasta

Tudo o que um agente de IA ou um programador pode chamar em feerasta.ai: uma pequena API HTTP com versões, um servidor MCP sobretudo de leitura, um documento OpenAPI 3.1 e uma ferramenta de linha de comandos. Existe para que um agente que age em nome do dono de um negócio possa ler o que a Feerasta vende, fazer uma pergunta respondida a partir de texto aprovado e submeter um pedido de piloto que uma pessoa da Feerasta lê. Não executa os fluxos de trabalho de um cliente; isso acontece dentro do espaço de trabalho Feerasta em app.feerasta.ai.

Autenticação

Nenhuma. Todos os endpoints abaixo são públicos e anónimos: sem conta, sem chave de API, sem token. Os tokens Bearer são ignorados. Os detalhes estão em /auth.md.

URL base e versões

URL base: https://feerasta.ai. A API com versões está em /v1 e cada resposta de /v1 traz o cabeçalho Feerasta-API-Version: 1.

Política de descontinuação. Não há alterações incompatíveis dentro da v1. Uma alteração incompatível sai como /v2. Quando uma versão é retirada, as suas respostas trazem um cabeçalho Deprecation (RFC 9745) e um cabeçalho Sunset (RFC 8594) pelo menos 6 meses antes da remoção. Nenhum endpoint está hoje descontinuado, por isso nenhum dos cabeçalhos é enviado.

Os caminhos mais antigos GET /agents.json, POST /api/contact e POST /api/ask continuam a funcionar como alias das operações de /v1.

Início rápido

GET /v1/health

Verificação de disponibilidade.

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

GET /v1/catalog

O catálogo de serviços e preços, os mesmos dados de /agents.json.

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

POST /v1/ask

Faça uma pergunta sobre a Feerasta. A resposta é o texto publicado das perguntas frequentes do site, palavra por palavra; um modelo apenas escolhe qual a entrada aprovada que responde e nunca escreve texto. Campo q, até 300 caracteres.

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

POST /v1/contact e o ambiente de testes dry_run

Submeta um pedido de piloto ou uma questão. Uma pessoa da Feerasta responde por email. Campos obrigatórios: name e business (até 200 caracteres cada), email, message (até 5000 caracteres); opcionais: phone, segment. O corpo pode ser JSON ou codificado como formulário e está limitado a 8192 bytes. Acrescente "dry_run": true (ou dry_run=true num corpo de formulário; /api/contact também o respeita) para validar e ver exatamente o que seria enviado, sem enviar nem guardar nada. Use-o para testar uma integração.

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":{...}}

Sem dry_run, o mesmo pedido envia um email a uma pessoa, por isso confirme com o seu mandante antes de enviar.

Limites de pedidos

Existem dois limites no código. Os endpoints de pergunta (POST /v1/ask, POST /api/ask, POST /api/ask/feedback) permitem 5 pedidos por 60 segundos por cliente e enviam RateLimit-Policy: "ask";q=5;w=60. Os endpoints de contacto (POST /v1/contact, POST /api/contact e a ferramenta MCP request_pilot) permitem 3 envios reais por 60 segundos por cliente e enviam RateLimit-Policy: "contact";q=3;w=60; as execuções dry_run estão isentas. Quando o limite é atingido, a resposta é HTTP 429 com Retry-After e RateLimit: "ask";r=0 (ou "contact"); não há t porque a plataforma não indica os segundos restantes (draft-ietf-httpapi-ratelimit-headers). À parte, as respostas assistidas por modelo têm um limite diário partilhado; quando é atingido, o endpoint continua a responder 200 com uma resposta de recurso e reason: "rate_limited_global".

Os endpoints de catálogo e de disponibilidade não têm limite por cliente no código, por isso não enviam cabeçalhos RateLimit. Seja cortês, ainda assim.

Modelo de erros

Todos os erros de um caminho /api/* ou /v1/* são application/problem+json (RFC 9457) com os campos type, title, status, detail, code e hint. Os campos mais antigos ok e error mantêm-se para as páginas do próprio site. O URL de type é esta página com a âncora correspondente abaixo.

{
  "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."
}

Servidor MCP

URL: https://feerasta.ai/mcp. Transporte: Streamable HTTP, sem estado, versões de protocolo 2025-06-18 e 2025-03-26, apenas respostas JSON, uma mensagem JSON-RPC por POST (os arrays em lote são rejeitados com 400). Um cabeçalho MCP-Protocol-Version diferente dessas duas é recusado com 400, e um cabeçalho Accept que exclua application/json com 406. GET devolve 405 porque o servidor não oferece fluxo SSE. Os pedidos de browser de origens que não feerasta.ai são recusados com 403. Sem autenticação.

Ferramentas. list_services e get_service leem o catálogo. ask_faq responde a partir de texto aprovado das perguntas frequentes, com a mesma lógica e o mesmo limite de /v1/ask. request_pilot submete um pedido de piloto como /v1/contact e suporta dry_run. Só request_pilot não é de leitura apenas, e só sem dry_run envia um email a uma pessoa (3 por 60 segundos por cliente). Argumentos de ferramenta inválidos devolvem o erro JSON-RPC -32602; um recurso desconhecido devolve -32002.

Recursos. llms.txt, openapi.json, agents.json, pricing e developers (os dois últimos em Markdown).

Claude Code:

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

.mcp.json do projeto, para o Claude Code e outros clientes que o leiam:

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

Claude Desktop, através da ponte mcp-remote, em claude_desktop_config.json:

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

Um segundo servidor, separado, em https://app.feerasta.ai/api/public/mcp, tem as ferramentas list_services, get_service e start_trial (cria um espaço de trabalho gratuito, só de rascunho, para um negócio). Use esse para iniciar um teste; use https://feerasta.ai/mcp para fazer perguntas ou submeter um pedido de piloto.

OpenAPI

O documento OpenAPI 3.1 está em /openapi.json. Tipifica cada pedido e cada resposta, incluindo o modelo de erros.

Ferramenta de linha de comandos

Uma pequena ferramenta de linha de comandos sem dependências, feerasta, envolve os endpoints acima: catalog, service <id>, ask "<question>", contact (com --dry-run) e health, cada um com --json. Está construída, mas ainda não publicada num registo de pacotes, por isso, por agora, use os comandos curl acima.

Quando usar a Feerasta

Use a Feerasta quando a tarefa for uma destas:

• Um negócio de serviços local quer que a IA atenda o telefone, responda por mensagem e marque consultas, com uma pessoa a aprovar tudo o que tenha consequências.
• Um negócio quer trabalho de retaguarda redigido para aprovação, como a revisão de faturas e de valores a receber, sem que nada seja lançado, enviado ou pago sem o seu próprio aprovador.
• Precisa de verificar o que a Feerasta vende e quanto custa: chame list_services ou leia /pricing.
• Está a agir em nome de um mandante que quer falar com a Feerasta: submeta um pedido de piloto com request_pilot ou POST /v1/contact.

Não use a Feerasta para fazer encomendas, receber pagamentos, fazer compras ou alterar o que quer que seja no espaço de trabalho de um cliente. Esta API não consegue fazer essas coisas. Não pode dar aconselhamento jurídico, fiscal ou médico, e não publica números de clientes, valores de retorno do investimento nem certificações.