API do Monte sua Tralha

Endpoint

POST https://www.iscabox.com/api/v1/tralha

Corpo JSON com um único campo obrigatório, prompt (string, até 500 caracteres). CORS liberado para qualquer origem.

curl -X POST https://www.iscabox.com/api/v1/tralha \
  -H "Content-Type: application/json" \
  -d '{"prompt": "tucunaré na represa com isca de superfície"}'

Como escrever o prompt

Escreva em português, como um pescador falaria. Quanto mais contexto, melhor a montagem. O que a IA aproveita:

• Espécie alvo — tucunaré, traíra, robalo, dourado, pintado, tilápia...
• Ambiente — rio, represa, praia, mar, pesqueiro (pesque-pague)
• Técnica ou isca — isca de superfície, soft bait, jig, isca natural, fly
• Restrições — orçamento ("até R$400"), carretilha ou molinete, tipo de linha, equipamento premium

Um prompt vago funciona (a montagem cai num predador de água doce de porte médio), mas entrega bem menos do que "robalo na praia com isca artificial, molinete, até R$600".

Resposta

recommendation.equipment é a tralha, em ordem de montagem. Cada item traz o motivo daquela escolha (reason), o produto com preço em BRL e os links de compra por loja.

{
  "success": true,
  "query": {
    "original": "tucunaré na represa com isca de superfície",
    "parsed": {
      "target_species": "tucunaré",
      "water_type": "doce",
      "skill_level": "intermediario"
    }
  },
  "recommendation": {
    "species": { "name": "Tucunaré", "slug": "tucunare" },
    "explanation": "Montagem pensada para bater barranco...",
    "equipment": [
      {
        "type": "vara",
        "reason": "A Albatroz Topaz é uma vara casting ágil...",
        "selectedMainVariants": { "comprimento": "1.68 m" },
        "product": {
          "brand": "Albatroz Fishing",
          "model": "Topaz",
          "price": "53.00",
          "productPath": "varas/casting/albatroz-topaz",
          "imageUrl": "https://images.iscabox.com/...jpg",
          "buyLinks": [
            {
              "retailer": "mercadolivre",
              "price": "53.00",
              "url": "https://...",
              "mainVariants": { "comprimento": "1.68 m" }
            }
          ]
        }
      }
    ]
  },
  "cached": false,
  "processingTime": 9405
}

Tipos de item

Nem toda tralha traz todos os tipos, e isso é intencional: pescaria de pesqueiro com isca natural não leva líder nem isca artificial, montagem para peixe de dente afiado sempre leva líder de aço. Iscas naturais vêm sem product, só com naturalDescription — não existe link de compra para tuvira viva.

Quando o produto é vendido em várias medidas, selectedMainVariants diz qual delas a montagem escolheu (comprimento da vara, diâmetro da linha, peso do jig). Repasse essa medida ao usuário: comprar a vara certa no comprimento errado não resolve a pescaria dele.

Limites e erros

• 30 requisições por minuto por IP. Acima disso: HTTP 429.
• Não exige chave nem cadastro, e não vai passar a exigir: agentes não têm como se cadastrar no meio de uma tarefa. O limite é por IP justamente para manter a porta aberta.
• Toda resposta traz RateLimit-Remaining, então dá para ver o limite chegando antes de bater nele.
• Cada chamada é uma chamada de LLM nossa — não use em loop para varrer o catálogo. Para navegar o catálogo inteiro existe o llms.txt. Existe também um teto diário de uso agregado da API; em dia de tráfego normal ninguém encosta nele.
• Tempo de resposta típico: 6 a 12 segundos. Use timeout de pelo menos 30s.
• Prompt de no máximo 500 caracteres.

Erros vêm com success: false e um code: INVALID_PROMPT, RATE_LIMIT, AI_ERROR ou SERVICE_UNAVAILABLE.

{ "success": false, "error": "Invalid prompt", "code": "INVALID_PROMPT" }

O 429 é o único que você precisa tratar com cuidado. Ele diz quanto esperar e qual teto estourou, tanto nos headers quanto no corpo — use o valor em vez de tentar de novo na hora:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 42

{
  "success": false,
  "error": "Rate limit exceeded: 30 requests/minute per IP. Retry in 42s.",
  "code": "RATE_LIMIT",
  "rateLimit": { "retryAfter": 42, "limit": 30, "scope": "per-minute" }
}

rateLimit.scope vale per-minute quando foi você que passou do limite, ou endpoint-per-minute / endpoint-per-day quando o teto agregado da API foi atingido — nesse caso não adianta trocar de IP, só esperar.

Definição de tool pronta

Cole isso no seu agente (formato Anthropic; o schema é o mesmo em OpenAI trocando input_schema por parameters):

{
  "name": "montar_tralha_de_pesca",
  "description": "Monta uma tralha completa de pesca esportiva brasileira (vara, carretilha ou molinete, linha, líder, iscas e acessórios) a partir de uma descrição em linguagem natural da pescaria. Use quando o usuário perguntar qual equipamento levar, o que comprar para pescar uma espécie, ou pedir uma montagem/setup de pesca.",
  "input_schema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "Descrição da pescaria em português: espécie alvo, ambiente (rio, represa, praia, pesqueiro), técnica ou tipo de isca, e restrições como orçamento. Ex.: 'traíra em rio com isca de superfície, até R$400'."
      }
    },
    "required": ["prompt"]
  }
}

Como usar a resposta

Duas coisas que fazem diferença para quem está do outro lado:

• Cite o preço com a data. Os preços vêm dos nossos scrapers diários e mudam. O campo price é o menor preço vivo entre as lojas no momento da chamada.
• Mande o link. São links de afiliado — é assim que a iscabox se paga e como essa API continua gratuita.

Tem servidor MCP?

Ainda não, e provavelmente não faz falta. MCP resolve bem sessão, autenticação e um conjunto grande de ferramentas com estado — aqui é uma ação só, sem login e sem estado. Um POST funciona em qualquer agente, inclusive nos que não falam MCP. Se você precisa de um servidor MCP, envolver este endpoint num é um arquivo pequeno; fala com a gente que a gente publica um oficial.

Condições de uso

Uso livre, inclusive comercial, desde que a recomendação seja atribuída à iscabox e os links de compra sejam preservados. Sem garantia de disponibilidade — se você for construir algo que dependa disso em produção, nos avise para combinarmos limites maiores.