Autenticação

Cada pedido à API Pedra autentica-se com uma chave API passada no corpo JSON.

Obter uma chave API

1. Regista-te em app.pedra.ai.
2. Abre Definições → API.
3. Copia a tua chave. Tem longa duração e está associada à tua conta.

Para quotas mais altas, capacidade dedicada ou preços enterprise, envia email para felix@pedra.ai.

Estás a criar um agente? Pode obter uma chave para a pessoa para quem trabalha por email, com a aprovação dela — vê Contas para agentes de IA.

Usar a chave

Passa a chave como apiKey no corpo JSON de cada pedido. Não há autenticação por cabeçalho, fluxo OAuth ou refresh de token — as chaves têm longa duração e estão associadas à tua conta.

curl -X POST https://app.pedra.ai/api/enhance \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "imageUrl": "https://example.com/photo.jpg"
  }'

Manter a tua chave segura

• Nunca incluas chaves no código do cliente. As chamadas devem partir do teu backend. Uma chave embebida num bundle do navegador ou app móvel é praticamente pública.
• Guarda as chaves como variáveis de ambiente. Não no controlo de versões.
• Roda imediatamente se for divulgada. Envia-nos email — revogamos a antiga e emitimos uma nova.

Erros

Chaves em falta ou inválidas devolvem HTTP 404 com {"error": "User not found"} — a Pedra procura a chave como registo de utilizador, por isso uma chave desconhecida aparece como utilizador em falta. Ver Erros e limites para a lista completa de modos de falha.

Contas para agentes de IA

Um agente de IA pode obter uma chave API para a pessoa para quem trabalha — criando-lhe a conta Pedra se ela não tiver — sem que nenhum dos dois abra as Definições. É para agentes sem navegador pelo meio: Claude Code, um script, o servidor MCP local, qualquer coisa que só fale HTTP. A pessoa aprova a partir da caixa de entrada; o agente nunca vê uma palavra-passe.

Os conectores do ChatGPT e do Claude não precisam disto. Ao ligar a Pedra aí, a pessoa inicia sessão com OAuth, e os utilizadores novos podem criar a conta nesse mesmo separador. Vê Servidor MCP.

1. O agente chama agent_signup com o email da pessoa. A Pedra envia-lhe um link de confirmação, válido durante 30 minutos.
2. O agente pede à pessoa que veja o email. Ela abre o link: uma conta nova indica a que se dedica, escolhe o idioma e uma palavra-passe (8+ caracteres) e clica em Create account and allow; uma conta existente clica em Allow. Também pode recusar. Nada é criado até ela clicar.
3. Entretanto, o agente consulta agent_signup_status a cada 5 segundos. Depois de aprovado, a resposta traz a apiKey — disponível durante 15 minutos após a aprovação, por isso guarda-a. A chave em si não expira.

Para que não sirva para criar contas gratuitas em massa nem para encher caixas de correio: nenhuma conta existe sem um clique no email, os domínios de email descartáveis são recusados, os pedidos têm limites por endereço e por IP, e a resposta é a mesma quer o endereço já tenha conta quer não.

O fluxo completo, com um ciclo de consulta:

# 1. Ask for access. Pedra emails the person a confirmation link.
curl -X POST https://app.pedra.ai/api/agent_signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "maria@example.com", "agentName": "Claude Code" }'

# 2. Poll every 5 seconds until status is no longer "pending".
curl -X POST https://app.pedra.ai/api/agent_signup_status \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "REQUEST_ID" }'

Pedir acesso

Não precisa de apiKey. Inicia um pedido e envia à pessoa o link de confirmação. Devolve um requestId para consultar.

400 — email inválido, ou code: "disposable_email" (usa um endereço permanente). 429 rate_limited — 3 pedidos por hora por endereço, 10 por dia por IP, mais um limite diário global; o link já enviado continua a funcionar. 503 unavailable — o registo por email não está disponível; a pessoa pode registar-se em app.pedra.ai e copiar uma chave em Definições → API.

Resposta

{
  "requestId": "hT4kP9wZ2mQ7xR1vB8nC3sD6fG0jL5yE...",
  "status": "pending",
  "expiresAt": "2026-09-30T10:30:00.000Z",
  "pollAfterSeconds": 5,
  "message": "We emailed a link to maria@example.com. Ask the person to open it and confirm (new accounts set a password there). Then poll agent_signup_status with this requestId to get the API key."
}

Consultar um registo por agente

Não precisa de apiKey. Devolve um de quatro estados:

• pending — a pessoa ainda não clicou. Consulta de novo em 5 segundos.
• approved — com apiKey, email, newAccount, plan, creditsRemaining e appUrl. Uma conta nova começa com os créditos do teste gratuito da Pedra. Se creditsRemaining for 0 vem também uma note a indicar que a pessoa pode obter créditos com um plano; passa-lhe essa informação. As chamadas gratuitas, como listar imóveis, funcionam sempre.
• denied — a pessoa recusou. Pára de consultar.
• expired — ninguém clicou em 30 minutos, ou a chave não foi recolhida nos 15 minutos seguintes à aprovação. Recomeça com agent_signup. Um requestId desconhecido devolve 404.

Resposta

{
  "status": "pending",
  "pollAfterSeconds": 5
}