Référence de l’API locale : gérez vos profils de navigateur depuis vos scripts.

Vue d’ensemble

L’API locale est une fonctionnalité de Prism Pro conçue pour gérer des profils par lots depuis vos propres scripts : créer des profils à partir de vos données métier, les lancer dans l’ordre, vérifier leur état et les fermer une fois le travail terminé. Elle ne gère que les profils eux-mêmes : elle ne lit ni les cookies, ni les mots de passe, ni les identifiants de proxy, ni le contenu des pages, et ne fournit aucun point de terminaison de débogage Puppeteer / Playwright. Pour permettre à une IA de lire des pages, de cliquer et de remplir des formulaires, utilisez MCP.

Démarrage rapide

1. Démarrer l’API locale

   Dans Prism, ouvrez « API d’automatisation » dans la barre latérale gauche, puis cliquez sur « Démarrer l’API locale ». Cette fonctionnalité nécessite Prism Pro.

2. Copier l’adresse et le jeton

   La fenêtre affiche « Adresse API » et « Jeton d’accès de cette session ». Le jeton ne s’affiche qu’une seule fois, au démarrage de l’API : copiez-le immédiatement. Pour obtenir un nouveau jeton par la suite, arrêtez puis redémarrez l’API.

3. Envoyer une première requête

   Dans un terminal, définissez deux variables, puis vérifiez l’état du service et listez vos profils. Si la réponse contient "state": "running", l’adresse et le jeton fonctionnent.

PRISM_API='http://127.0.0.1:43123'   # the API address shown in Prism
PRISM_TOKEN='<token>'                # the token shown in Prism

curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/status"
curl -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles"

Dans Windows PowerShell, curl est un alias d’une autre commande : tapez plutôt curl.exe, ou utilisez la commande Invoke-RestMethod, intégrée à PowerShell :

$api = 'http://127.0.0.1:43123'
$headers = @{ Authorization = 'Bearer <token>' }
(Invoke-RestMethod -Uri "$api/v1/profiles" -Headers $headers).result | Format-Table serialNumber, name, status

Règles de requête

L’API n’accepte que les requêtes envoyées par des scripts ou des programmes exécutés sur cet ordinateur. Une requête qui enfreint l’une des règles suivantes n’est pas exécutée et renvoie l’erreur indiquée dans le tableau :

Prism traite les requêtes de l’API locale et de MCP une par une, dans l’ordre de réception. Le lancement d’un profil comprend le test du proxy et l’ouverture du navigateur, ce qui prend généralement quelques secondes ; pendant ce temps, les requêtes suivantes attendent leur tour. Attendez la réponse à chaque requête avant d’envoyer la suivante.

Points de terminaison

{id} est l’ID d’un profil, à récupérer dans le résultat de GET /v1/profiles. Les réponses en cas de succès ont toutes le statut HTTP 200 ; à l’exception de GET /v1/status, elles placent le résultat dans le champ result. L’API ne propose aucun point de terminaison pour modifier ou supprimer des profils.

Objet profil

La liste des profils, l’état d’un profil, le lancement et la fermeture renvoient tous le même objet profil :

{
  "result": {
    "id": "8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70",
    "serialNumber": 12,
    "name": "Shop A",
    "group": "Project A",
    "tags": ["automation"],
    "status": "running",
    "lastOpenedAt": "2026-10-02T08:30:00.000Z"
  }
}

Les réponses ne contiennent jamais l’adresse ou les identifiants du proxy, les paramètres d’empreinte, les cookies, les mots de passe, ni les données de sites ou d’extensions.

Consulter, lancer et fermer

GET /v1/status

Renvoie l’état du service, pour vérifier que l’adresse et le jeton fonctionnent. C’est la seule réponse qui n’est pas encapsulée dans result :

{
  "state": "running",
  "transport": "loopback",
  "protocolVersion": 1
}

GET /v1/profiles

Renvoie un tableau d’objets profil, les plus récemment modifiés en premier. Les profils placés dans la corbeille n’y figurent pas.

GET /v1/profiles/{id}/status

Renvoie l’état actuel d’un profil. Si le profil n’existe pas ou se trouve dans la corbeille, l’API renvoie 404 PROFILE_NOT_FOUND.

POST /v1/profiles/{id}/start

• Fonctionne comme un clic sur « Ouvrir » dans l’application : Prism vérifie le noyau et la licence du noyau Pro, teste le proxy et les changements d’IP de sortie, puis ouvre la fenêtre du navigateur. En cas de succès, renvoie l’objet profil avec le statut running.
• Si le profil est déjà en cours d’exécution, son état actuel est renvoyé directement, sans seconde ouverture.
• Prism ne traite la requête suivante qu’une fois la requête de lancement terminée. Pour lancer de nombreux profils, appelez simplement le point de terminaison pour chacun d’eux, l’un après l’autre ; le nombre de profils pouvant tourner en même temps dépend de la mémoire et du CPU de votre ordinateur.
• Si le noyau requis est absent, si le test du proxy échoue, si l’IP de sortie du proxy a changé (avec la règle block) ou si un processus orphelin subsiste, le lancement échoue avec 502 et error.message en indique la raison.
• Les cas où l’application vous demanderait une confirmation pour continuer échouent d’emblée via l’API, par exemple lorsque les sources de géolocalisation se contredisent sur la sortie du proxy. Face à ce type d’erreur, ouvrez le profil dans l’application Prism ou réglez son identité réseau sur manual.
• Prism garde la trace des profils visés par un appel au point de terminaison de lancement (y compris ceux qui étaient déjà en cours d’exécution au moment de l’appel), et un clic sur « Arrêt d’urgence » dans la fenêtre « API d’automatisation » les ferme tous. « Arrêter l’API », de même que l’arrêt normal ou d’urgence depuis la fenêtre MCP, n’arrête que l’API : ces profils restent ouverts.

POST /v1/profiles/{id}/close

Ferme la fenêtre du navigateur, conserve les données du profil et renvoie l’objet profil avec le statut closed ; si le profil n’est pas en cours d’exécution, closed est renvoyé directement. Si le navigateur ne s’est pas fermé au bout de 8 secondes et occupe toujours le répertoire de données, le statut renvoyé est orphaned ; un nouvel appel de fermeture termine alors le processus orphelin.

PROFILE_ID='8f0c2b9e-4d6a-4f51-9a7e-2f1c3d5b6a70'   # an id from GET /v1/profiles
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/start"
curl -X POST -H "Authorization: Bearer $PRISM_TOKEN" "$PRISM_API/v1/profiles/$PROFILE_ID/close"

Créer des profils

Les points de terminaison de création enregistrent les nouveaux profils à l’état fermé, sans ouvrir de navigateur. Tous les champs sont facultatifs : les champs omis prennent les mêmes valeurs par défaut que « Nouveau profil » dans l’application, et chaque profil reçoit une nouvelle graine d’empreinte. Les champs inconnus sont refusés.

Créer un profil

curl -X POST "$PRISM_API/v1/profiles" \
  -H "Authorization: Bearer $PRISM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-b-001" \
  -d '{
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "startUrls": ["https://example.com/"],
    "proxy": { "protocol": "socks5", "host": "203.0.113.10", "port": 1080, "username": "user", "password": "pass" }
  }'

En cas de succès, le nouveau profil est renvoyé :

{
  "result": {
    "id": "3b1f7a52-9c4e-4d2b-8f60-1a2b3c4d5e6f",
    "serialNumber": 13,
    "name": "Shop B",
    "group": "Project A",
    "tags": ["automation"],
    "status": "closed"
  }
}

Créer des profils par lots

Le corps de POST /v1/profiles/batch est un tableau profiles de 1 à 50 éléments ; chaque élément s’écrit comme pour une création unique, à ceci près que requestKey se place à la racine du corps ou dans l’en-tête de la requête. Prism valide d’abord toutes les configurations : si l’une d’elles est invalide, aucun profil n’est créé, et le message d’erreur indique le profil et le champ en cause (profiles[1] désigne le deuxième profil, la numérotation commençant à 0). Les résultats sont renvoyés dans l’ordre des entrées :

{
  "requestKey": "shops-batch-001",
  "profiles": [
    { "name": "Shop C", "group": "Project A" },
    { "name": "Shop D", "group": "Project A", "fingerprint": { "platform": "windows" } }
  ]
}

{
  "result": {
    "profiles": [
      { "id": "…", "serialNumber": 14, "name": "Shop C", "group": "Project A", "tags": [], "status": "closed" },
      { "id": "…", "serialNumber": 15, "name": "Shop D", "group": "Project A", "tags": [], "status": "closed" }
    ],
    "count": 2
  }
}

Champs du profil

Champs du proxy

Champs de l’empreinte

Modèles matériels

Une requête dont le modèle ne correspond pas à platform est refusée. La position et la taille de la fenêtre, les cookies, les données d’extensions et les autres réglages de ce type ne peuvent pas être définis via l’API ; modifiez-les dans l’application Prism après la création.

Réessayer sans doublons

En cas de coupure réseau ou de requête expirée, vous ne savez pas forcément si le profil a été créé. Fournissez une clé de requête pour chaque création, et une nouvelle tentative ne créera jamais de doublon :

• Indiquez une clé de 8 à 128 caractères dans l’en-tête Idempotency-Key ou dans le champ requestKey du corps ; caractères autorisés : lettres ASCII, chiffres et . _ : -. Si vous utilisez les deux, les valeurs doivent être identiques.
• Une nouvelle tentative avec la même clé et le même contenu dans les 24 heures renvoie les profils créés la première fois (HTTP 200), même après un redémarrage de Prism.
• Une même clé avec un contenu différent renvoie 409 IDEMPOTENCY_CONFLICT. Si un profil créé la première fois a été supprimé (y compris s’il a été placé dans la corbeille), l’API renvoie 409 IDEMPOTENCY_RESULT_GONE au lieu de le recréer en silence ; pour le recréer, utilisez une nouvelle clé.
• Au-delà de 24 heures, la même clé est traitée comme une nouvelle requête.
• Jusqu’à 1 000 requêtes avec clé sont conservées sur 24 heures, une limite partagée avec les créations via MCP (chaque création via MCP y est comptabilisée) ; une fois cette limite atteinte, l’API renvoie 429 IDEMPOTENCY_CAPACITY jusqu’à l’expiration des anciens enregistrements.
• Les clés et le contenu des requêtes ne sont conservés sur cet ordinateur que sous forme de hachages à clé ; le mot de passe du proxy n’est jamais enregistré en clair.

Générez de préférence vos clés à partir de vos données métier, par exemple un numéro de ligne de tableur ou un numéro de commande : shop-b-001.

Gestion des erreurs

Lorsqu’une requête est refusée dès l’entrée (voir « Règles de requête »), error est une chaîne, par exemple {"error":"unauthorized"}. Si Prism rencontre une erreur en traitant la requête, error est un objet :

{
  "error": {
    "code": "INVALID_PROFILE_INPUT",
    "message": "Invalid profile creation request; see details",
    "retryable": false,
    "details": [
      { "path": "profiles[1].proxy.port", "message": "Too big: expected number to be <=65535" }
    ]
  }
}

Vos programmes doivent se fonder sur le statut HTTP et sur code ; message est une explication destinée aux humains, en partie en chinois, dont la formulation peut changer d’une version à l’autre. Si retryable vaut true, vous pouvez renvoyer la même requête telle quelle plus tard. details n’apparaît que pour les erreurs dans les champs de création, avec 20 entrées au maximum, et ne reprend jamais les valeurs envoyées.

MCP_REQUEST_FAILED est un nom d’erreur générique utilisé en interne par Prism ; l’API locale l’utilise aussi.

Exemples de code

Remplacez l’adresse et le jeton des exemples par les valeurs affichées dans la fenêtre de Prism. Les exemples créent des profils, puis lancent et ferment un profil nouvellement créé.

Python

Nécessite requests (pip install requests) :

import requests

API = "http://127.0.0.1:43123"   # the API address shown in Prism
TOKEN = "<token>"                # the token shown in Prism

session = requests.Session()
session.headers["Authorization"] = f"Bearer {TOKEN}"

def call(method, path, **kwargs):
    response = session.request(method, API + path, timeout=70, **kwargs)
    body = response.json()
    if not response.ok:
        raise RuntimeError(f"{response.status_code}: {body['error']}")
    return body.get("result", body)

created = call("POST", "/v1/profiles/batch",
               headers={"Idempotency-Key": "shops-batch-002"},
               json={"profiles": [{"name": "Shop C"}, {"name": "Shop D"}]})
for profile in created["profiles"]:
    print("created", profile["serialNumber"], profile["id"])

profiles = call("GET", "/v1/profiles")
for profile in profiles:
    print(profile["serialNumber"], profile["name"], profile["status"])

first = created["profiles"][0]["id"]
print(call("POST", f"/v1/profiles/{first}/start")["status"])   # running
print(call("POST", f"/v1/profiles/{first}/close")["status"])   # closed

Node.js

Node.js 18 et les versions ultérieures intègrent fetch, sans dépendance à installer :

// prism.mjs — run with: node prism.mjs (Node.js 18 or later)
const API = 'http://127.0.0.1:43123' // the API address shown in Prism
const TOKEN = '<token>'              // the token shown in Prism

async function call(method, path, body, headers = {}) {
  const response = await fetch(API + path, {
    method,
    headers: { Authorization: `Bearer ${TOKEN}`, ...(body ? { 'Content-Type': 'application/json' } : {}), ...headers },
    body: body ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(70_000),
  })
  const data = await response.json()
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data.error)}`)
  return data.result ?? data
}

const profile = await call('POST', '/v1/profiles', {
  name: 'Shop E',
  fingerprint: { language: 'en-US', timezone: 'America/New_York', networkIdentityMode: 'manual' },
}, { 'Idempotency-Key': 'shop-e-001' })
console.log('created', profile.serialNumber, profile.id)

console.log((await call('POST', `/v1/profiles/${profile.id}/start`)).status) // running
console.log((await call('POST', `/v1/profiles/${profile.id}/close`)).status) // closed

API locale et MCP

L’API locale est destinée à vos propres scripts ; les clients IA doivent se connecter à Prism via MCP. MCP utilise son propre jeton et ses propres autorisations : seuls les profils autorisés dans « IA locale · MCP » sont visibles par l’IA, et l’IA ne peut pas appeler l’API locale. Les deux partagent le même service local et le même quota de 120 requêtes en 60 secondes ; l’arrêt de MCP, normal ou d’urgence, entraîne aussi celui de l’API locale.

L’IA peut aussi créer des profils avec les outils MCP prism_create_profile et prism_create_profiles, qui acceptent les mêmes champs que ceux décrits sur cette page. Pour cela, activez « Autoriser l’IA à créer des profils » dans « IA locale · MCP » (désactivé par défaut) ; la possibilité pour l’IA de contrôler les nouveaux profils dépend du mode d’accès aux profils que vous avez choisi. Les clés de requête de MCP et celles de l’API locale sont indépendantes, mais partagent la même limite de 1 000 enregistrements sur 24 heures.

Conseils de sécurité

• Le jeton est la clé qui permet de gérer les profils de cet ordinateur : ne l’écrivez jamais dans un dépôt de code, des journaux ou des conversations. En cas de fuite possible, arrêtez puis redémarrez l’API ; l’ancien jeton devient immédiatement invalide.
• L’API écoute uniquement sur 127.0.0.1 : les autres appareils du réseau local ou d’Internet ne peuvent pas y accéder directement. La vérification de l’en-tête Host sert surtout à bloquer les navigateurs et les erreurs de manipulation, et ne remplace pas un contrôle d’accès ; n’exposez pas l’API via une redirection de port ou un proxy inverse.
• Les autres programmes de cet ordinateur peuvent eux aussi appeler l’API s’ils obtiennent le jeton. Ne l’activez que sur un ordinateur de confiance, et cliquez sur « Arrêter l’API » une fois terminé.
• Dans la fenêtre « API d’automatisation », « Arrêt d’urgence » arrête l’API et ferme les profils qu’elle a lancés pendant cette session et qui sont encore en cours d’exécution.
• Chaque requête exécutée par Prism est consignée dans le journal d’audit local vault/logs/automation-audit.jsonl (dans le répertoire de données de Prism), qui enregistre l’heure, l’action, le résultat, l’ID de la requête, les ID des profils et la cause de l’échec éventuel, mais jamais le jeton, le contenu de la requête ni celui des pages. Les requêtes refusées par les règles de requête et les requêtes GET /v1/status ne sont pas consignées.

Questions fréquentes

Peut-on appeler l’API depuis une page web ou une extension de navigateur ?

Non. Les requêtes envoyées par un navigateur comportent un en-tête Origin, que l’API refuse. Appelez-la depuis un terminal, un script ou un programme local.

Pourquoi obtient-on une erreur 403 avec localhost ?

L’API exige que l’en-tête Host corresponde exactement à 127.0.0.1 et au port de l’adresse de l’API : localhost est donc refusé. Utilisez 127.0.0.1 comme nom d’hôte dans l’adresse.

Que faire si la fenêtre « API d’automatisation » indique que l’API est en cours d’exécution, mais n’affiche aucun jeton ?

Lorsque MCP est activé, Prism démarre automatiquement le service local partagé par l’API et MCP ; la fenêtre n’affiche alors que l’adresse. Le jeton ne s’affiche qu’une seule fois, après un clic réussi sur « Démarrer l’API locale » : cliquez sur « Arrêter l’API », puis sur « Démarrer l’API locale » pour obtenir un nouveau jeton. Tant que le service est arrêté, la connexion MCP est elle aussi interrompue.

L’ancien jeton reste-t-il valable après un redémarrage de Prism ?

Non. Chaque démarrage de l’API génère un nouveau port et un nouveau jeton ; l’ancien jeton devient invalide dès que vous arrêtez l’API ou quittez Prism.

L’API peut-elle modifier ou supprimer des profils ?

Non. L’API peut créer, consulter, lancer et fermer des profils ; pour modifier leur configuration ou les supprimer, utilisez l’application Prism.

Peut-on y connecter Puppeteer, Playwright ou Selenium ?

Non. L’API ne fournit ni port de débogage ni adresse WebDriver. Pour les actions au niveau des pages, confiez-les à un client IA via MCP.

Peut-on lancer de nombreux profils à la fois ?

Oui : appelez le point de terminaison de lancement pour chaque profil, l’un après l’autre. Prism traite les requêtes une par une et passe à la suivante une fois le profil lancé ; le nombre de profils pouvant tourner en même temps dépend de la mémoire et du CPU de votre ordinateur.

L’API fonctionne-t-elle aussi sous Windows ?

Oui. Prism Pro fournit la même API locale sur macOS et sur Windows. Dans Windows PowerShell, utilisez curl.exe ou Invoke-RestMethod.

Fonctionnalités et tutoriels associés