Authentification

Chaque requête à l'API Pedra s'authentifie avec une clé API passée dans le corps JSON.

Obtenir une clé API

1. Inscrivez-vous sur app.pedra.ai.
2. Ouvrez Paramètres → API.
3. Copiez votre clé. Elle a une longue durée de vie et est liée à votre compte.

Pour des quotas plus élevés, une capacité dédiée ou des tarifs enterprise, écrivez à felix@pedra.ai.

Vous construisez un agent ? Il peut obtenir une clé pour la personne pour qui il travaille, par e-mail et avec son accord — voir Comptes pour agents IA.

Utiliser la clé

Passez la clé sous apiKey dans le corps JSON de chaque requête. Il n'y a pas d'authentification par en-tête, de flux OAuth ni de refresh de token — les clés ont une longue durée de vie et sont liées à votre compte.

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

Garder votre clé en sécurité

• Ne déployez jamais de clés dans le code côté client. Les appels doivent provenir de votre backend. Une clé intégrée à un bundle navigateur ou une app mobile est effectivement publique.
• Stockez les clés comme variables d'environnement. Pas dans le contrôle de version.
• Faites tourner la clé immédiatement en cas de fuite. Écrivez-nous — nous révoquerons l'ancienne et en émettrons une nouvelle.

Erreurs

Les clés manquantes ou invalides renvoient HTTP 404 avec {"error": "User not found"} — Pedra recherche la clé comme un enregistrement utilisateur, donc une clé inconnue apparaît comme un utilisateur inexistant. Voir Erreurs et limites pour la liste complète des modes d'échec.

Comptes pour agents IA

Un agent IA peut obtenir une clé API pour la personne pour qui il travaille — et lui créer un compte Pedra si elle n'en a pas — sans que l'un ou l'autre n'ouvre les Paramètres. C'est pour les agents sans navigateur dans la boucle : Claude Code, un script, le serveur MCP local, tout ce qui ne parle que HTTP. La personne approuve depuis sa boîte mail ; l'agent ne voit jamais de mot de passe.

Les connecteurs ChatGPT et Claude n'en ont pas besoin. Connecter Pedra là-bas connecte la personne via OAuth, et les nouveaux utilisateurs peuvent créer leur compte dans ce même onglet. Voir Serveur MCP.

1. L'agent appelle agent_signup avec l'e-mail de la personne. Pedra lui envoie un lien de confirmation, valable 30 minutes.
2. L'agent demande à la personne de vérifier ses e-mails. Elle ouvre le lien : un nouveau compte indique son métier, choisit une langue et un mot de passe (8 caractères ou plus) et clique sur Create account and allow ; un compte existant clique sur Allow. Elle peut aussi refuser. Rien n'est créé avant son clic.
3. Pendant ce temps, l'agent interroge agent_signup_status toutes les 5 secondes. Une fois approuvé, la réponse contient l'apiKey — disponible pendant 15 minutes après l'approbation, donc stockez-la. La clé elle-même n'expire pas.

Pour éviter qu'il serve à créer des comptes gratuits en masse ou à spammer des boîtes mail : aucun compte n'existe sans un clic dans la boîte mail, les domaines d'e-mail jetables sont refusés, les demandes sont limitées par adresse et par IP, et la réponse est la même que l'adresse ait déjà un compte ou non.

Le flux complet, avec une boucle d'interrogation :

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

Demander l'accès

Pas besoin d'apiKey. Crée une demande et envoie le lien de confirmation à la personne. Renvoie un requestId à interroger.

400 — adresse e-mail invalide, ou code: "disposable_email" (utilisez une adresse permanente). 429 rate_limited — 3 demandes par heure par adresse, 10 par jour par IP, plus un plafond quotidien global ; le lien déjà envoyé fonctionne toujours. 503 unavailable — l'inscription par e-mail est indisponible ; la personne peut s'inscrire sur app.pedra.ai et copier une clé dans Paramètres → API.

Réponse

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

Vérifier une inscription par agent

Pas besoin d'apiKey. Renvoie l'un de ces quatre statuts :

• pending — la personne n'a pas encore cliqué. Réessayez dans 5 secondes.
• approved — avec apiKey, email, newAccount, plan, creditsRemaining et appUrl. Un nouveau compte commence avec les crédits d'essai gratuit de Pedra. Si creditsRemaining vaut 0, il y a aussi une note indiquant que la personne peut obtenir des crédits avec un plan ; transmettez-la-lui. Les appels gratuits, comme lister les propriétés, fonctionnent toujours.
• denied — la personne a refusé. Arrêtez d'interroger.
• expired — personne n'a cliqué en 30 minutes, ou la clé n'a pas été récupérée dans les 15 minutes suivant l'approbation. Recommencez avec agent_signup. Un requestId inconnu renvoie 404.

Réponse

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