Autenticación

Cada petición a la API de Pedra se autentica con una clave API enviada en el cuerpo JSON.

Conseguir una clave API

1. Regístrate en app.pedra.ai.
2. Abre Ajustes → API.
3. Copia tu clave. Es de larga duración y está vinculada a tu cuenta.

Para mayores cuotas, capacidad dedicada o precios enterprise, escribe a felix@pedra.ai.

¿Estás creando un agente? Puede conseguir una clave para la persona para la que trabaja por email, con su aprobación — mira Cuentas para agentes de IA.

Usar la clave

Pasa la clave como apiKey en el cuerpo JSON de cada petición. No hay autenticación por cabecera, flujo OAuth ni refresh de token — las claves son de larga duración y están vinculadas a tu cuenta.

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"
  }'

Mantener tu clave segura

• Nunca incluyas claves en código de cliente. Las llamadas deben originarse desde tu backend. Una clave incrustada en un bundle del navegador o una app móvil es prácticamente pública.
• Guarda las claves como variables de entorno. No en el control de versiones.
• Rota la clave inmediatamente si se filtra. Escríbenos — revocaremos la antigua y emitiremos una nueva.

Errores

Las claves faltantes o inválidas devuelven HTTP 404 con {"error": "User not found"} — Pedra busca la clave como un registro de usuario, así que una clave desconocida aparece como un usuario inexistente. Consulta Errores y límites para la lista completa de modos de fallo.

Cuentas para agentes de IA

Un agente de IA puede conseguir una clave API para la persona para la que trabaja — y crearle la cuenta de Pedra si no la tiene — sin que ninguno de los dos abra Ajustes. Es para agentes sin navegador de por medio: Claude Code, un script, el servidor MCP local, cualquier cosa que solo hable HTTP. La persona lo aprueba desde su bandeja de entrada; el agente nunca ve una contraseña.

Los conectores de ChatGPT y Claude no lo necesitan. Al conectar Pedra allí, la persona inicia sesión con OAuth, y los usuarios nuevos pueden crear su cuenta en esa misma pestaña. Mira Servidor MCP.

1. El agente llama a agent_signup con el email de la persona. Pedra le envía un enlace de confirmación, válido durante 30 minutos.
2. El agente le dice a la persona que revise su email. Abre el enlace: si es una cuenta nueva, indica a qué se dedica, elige idioma y una contraseña (8+ caracteres) y pulsa Create account and allow; si ya tiene cuenta, pulsa Allow. También puede rechazarlo. No se crea nada hasta que pulsa.
3. Mientras tanto, el agente consulta agent_signup_status cada 5 segundos. Una vez aprobado, la respuesta trae la apiKey — disponible durante 15 minutos tras la aprobación, así que guárdala. La clave en sí no caduca.

Para que no se use para crear cuentas gratuitas en masa ni para llenar bandejas de entrada: no existe ninguna cuenta sin un clic en el email, se rechazan los dominios de email desechables, las peticiones tienen límites por dirección y por IP, y la respuesta es la misma tanto si la dirección ya tiene cuenta como si no.

El flujo completo, con un bucle 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" }'

Solicitar acceso

No necesita apiKey. Inicia una solicitud y envía a la persona el enlace de confirmación. Devuelve un requestId para consultar el estado.

400 — el email no es válido, o code: "disposable_email" (usa una dirección permanente). 429 rate_limited — 3 solicitudes por hora por dirección, 10 al día por IP, más un tope diario global; el enlace ya enviado sigue funcionando. 503 unavailable — el registro por email no está disponible; la persona puede registrarse en app.pedra.ai y copiar una clave en Ajustes → API.

Respuesta

{
  "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 un registro de agente

No necesita apiKey. Devuelve uno de estos cuatro estados:

• pending — la persona aún no ha pulsado. Vuelve a consultar en 5 segundos.
• approved — con apiKey, email, newAccount, plan, creditsRemaining y appUrl. Una cuenta nueva empieza con los créditos de prueba gratis de Pedra. Si creditsRemaining es 0 también viene una note que indica que la persona puede conseguir créditos con un plan; transmíteselo. Las llamadas gratuitas, como listar propiedades, siempre funcionan.
• denied — la persona lo rechazó. Deja de consultar.
• expired — nadie pulsó en 30 minutos, o la clave no se recogió en los 15 minutos siguientes a la aprobación. Vuelve a empezar con agent_signup. Un requestId desconocido devuelve 404.

Respuesta

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