Autenticazione

Ogni richiesta all'API Pedra si autentica con una chiave API passata nel corpo JSON.

Ottenere una chiave API

1. Registrati su app.pedra.ai.
2. Apri Impostazioni → API.
3. Copia la tua chiave. Ha una lunga durata ed è legata al tuo account.

Per quote più alte, capacità dedicata o prezzi enterprise, scrivi a felix@pedra.ai.

Stai costruendo un agente? Può ottenere una chiave per la persona per cui lavora via email, con la sua approvazione — vedi Account per agenti IA.

Usare la chiave

Passa la chiave come apiKey nel corpo JSON di ogni richiesta. Non c'è autenticazione tramite header, flusso OAuth o refresh del token — le chiavi sono di lunga durata e legate al tuo account.

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

Mantenere la chiave al sicuro

• Non distribuire mai chiavi nel codice client. Le chiamate devono partire dal tuo backend. Una chiave incorporata in un bundle browser o in un'app mobile è di fatto pubblica.
• Memorizza le chiavi come variabili d'ambiente. Non nel controllo versione.
• Ruota immediatamente se viene divulgata. Scrivici — revocheremo la vecchia e ne emetteremo una nuova.

Errori

Le chiavi mancanti o non valide restituiscono HTTP 404 con {"error": "User not found"} — Pedra cerca la chiave come record utente, quindi una chiave sconosciuta appare come utente mancante. Vedi Errori e limiti per l'elenco completo dei modi di errore.

Account per agenti IA

Un agente IA può ottenere una chiave API per la persona per cui lavora — creando il suo account Pedra se non ce l'ha — senza che nessuno dei due apra le Impostazioni. È per agenti senza browser: Claude Code, uno script, il server MCP locale, qualsiasi cosa parli solo HTTP. La persona approva dalla sua casella di posta; l'agente non vede mai una password.

I connettori di ChatGPT e Claude non ne hanno bisogno. Collegando Pedra lì, la persona accede con OAuth, e i nuovi utenti possono creare l'account nella stessa scheda di accesso. Vedi Server MCP.

1. L'agente chiama agent_signup con l'email della persona. Pedra le invia un link di conferma, valido 30 minuti.
2. L'agente chiede alla persona di controllare l'email. Apre il link: un nuovo account indica di cosa si occupa, sceglie la lingua e una password (almeno 8 caratteri) e clicca Create account and allow; un account esistente clicca Allow. Può anche rifiutare. Non viene creato nulla finché non clicca.
3. Nel frattempo l'agente interroga agent_signup_status ogni 5 secondi. Una volta approvato, la risposta contiene l'apiKey — disponibile per 15 minuti dopo l'approvazione, quindi salvala. La chiave in sé non scade.

Perché non venga usato per creare account gratuiti in massa o per inondare caselle di posta: nessun account esiste senza un clic nell'email, i domini email usa e getta sono rifiutati, le richieste sono limitate per indirizzo e per IP, e la risposta è la stessa che l'indirizzo abbia già un account o no.

Il flusso completo, con un ciclo di polling:

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

Richiedere l'accesso

Non serve l'apiKey. Avvia una richiesta e invia alla persona il link di conferma. Restituisce un requestId da interrogare.

400 — indirizzo email non valido, oppure code: "disposable_email" (usa un indirizzo permanente). 429 rate_limited — 3 richieste l'ora per indirizzo, 10 al giorno per IP, più un tetto giornaliero globale; il link già inviato funziona ancora. 503 unavailable — la registrazione via email non è disponibile; la persona può registrarsi su app.pedra.ai e copiare una chiave da Impostazioni → API.

Risposta

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

Controllare una registrazione tramite agente

Non serve l'apiKey. Restituisce uno di questi quattro stati:

• pending — la persona non ha ancora cliccato. Riprova tra 5 secondi.
• approved — con apiKey, email, newAccount, plan, creditsRemaining e appUrl. Un nuovo account parte con i crediti della prova gratuita di Pedra. Se creditsRemaining è 0 c'è anche una note che indica che la persona può ottenere crediti con un piano; riferiscilo. Le chiamate gratuite, come elencare le proprietà, funzionano sempre.
• denied — la persona ha rifiutato. Smetti di interrogare.
• expired — nessuno ha cliccato entro 30 minuti, oppure la chiave non è stata ritirata entro 15 minuti dall'approvazione. Ricomincia con agent_signup. Un requestId sconosciuto restituisce 404.

Risposta

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