Control
Politique de confidentialitéOuvrir l’API

Documentation développeur

API publique de confidentialité

Interroger le registre public et versionné des traitements de données, modules et notices de confidentialité de Control.

Version v1En service depuis le 22 septembre 2026Lecture publique

Une API JSON en lecture seule, sans authentification, conçue pour être consultée par les utilisateurs, les intégrateurs et les outils automatisés.

Aperçu

L’API répond en JSON UTF-8, sans clé d’API ni authentification. Tous les endpoints sont en lecture seule et utilisent le schéma public v1.

  • Les réponses ne publient ni nom de serveur, ni invitation, ni liste de salons, ni configuration brute.
  • Le catalogue global est dérivé des mêmes déclarations produit que les modules Control et la page de confidentialité.
  • Une notice de serveur distingue toujours la possibilité de collecter de l’existence de données encore conservées.
  • Une révision historique est immuable. Son empreinte identifie exactement son état canonique et permet de vérifier qu’une copie connue n’a pas été modifiée.
Base URL/api/public/v1/privacyAfficher le JSON

Endpoints disponibles

GET/api/public/v1/privacy

Catalogue global des traitements, catégories de données, capacités et règles de conservation.

Authentification
Aucune
Cache
public, max-age=60, s-maxage=300, stale-while-revalidate=60
ETag
Oui, revalidation If-None-Match disponible
GET/api/public/v1/privacy/{guildId}

Notice actuelle d’un serveur configuré dans Control, sans publier son nom ni sa configuration brute.

Authentification
Aucune
Cache
public, max-age=30, s-maxage=60, stale-while-revalidate=30
ETag
Oui, revalidation If-None-Match disponible
GET/api/public/v1/privacy/{guildId}/revisions

Liste des révisions disponibles pour la notice d’un serveur.

Authentification
Aucune
Cache
public, max-age=30, s-maxage=60
ETag
Non
GET/api/public/v1/privacy/{guildId}/revisions/{revision}

État complet d’une révision historique immuable.

Authentification
Aucune
Cache
public, max-age=31536000, immutable
ETag
Oui, revalidation If-None-Match disponible

Paramètres de chemin

guildId
Identifiant Discord du serveur (snowflake). Le serveur doit être configuré dans Control.
revision
Numéro entier d’une révision retournée par l’endpoint de liste des révisions.

Lecture depuis n’importe quel site

Chaque réponse fournit Access-Control-Allow-Origin: * et Cross-Origin-Resource-Policy: cross-origin. Un site tiers, y compris une page isolée avec Cross-Origin-Embedder-Policy: require-corp, peut donc effectuer un fetch CORS et lire la réponse directement dans son client. Les preflights autorisent If-None-Match et les en-têtes ETag, Retry-After et X-RateLimit sont exposés au navigateur. L’API n’utilise pas de cookies ni d’identifiants CORS et ne doit pas être appelée avec des credentials.

Access-Control-Allow-Origin: *Access-Control-Allow-Methods: GET, HEAD, OPTIONSAccess-Control-Allow-Headers: If-None-MatchAccess-Control-Expose-Headers: ETag, Retry-After, X-RateLimit-Limit, X-RateLimit-RemainingCross-Origin-Resource-Policy: cross-origin

Limites de débit

Les limites sont cumulatives. Une lecture de notice de serveur consomme les budgets global, confidentialité et serveur.

Budget global de l’API300 requêtespar 1 minuteClé de calcul : adresse IP
Registre de confidentialité30 requêtespar 1 minuteClé de calcul : adresse IP
Notice d’un serveur10 requêtespar 1 minuteClé de calcul : adresse IP et serveur Discord

Chaque réponse indique X-RateLimit-Limit et X-RateLimit-Remaining. Une réponse 429 ajoute Retry-After en secondes et un corps JSON contenant retryAfterMs.

Cache et revalidation

Les réponses courantes exposent Cache-Control et, lorsqu’une empreinte est disponible, ETag. Envoyez If-None-Match pour recevoir une réponse 304 sans corps lorsque la ressource n’a pas changé. Les révisions historiques sont immuables.

Empreinte et canonicalisation

contentHash utilise sha-256 et la convention control-sorted-json-v1. Les clés de chaque objet sont triées récursivement dans l’ordre des unités de code UTF-16, l’ordre des tableaux est conservé, puis JSON.stringify produit le texte encodé en UTF-8 avant le calcul SHA-256. La valeur est encodée en hexadécimal minuscule. Les champs inclus sont : schemaVersion, guildId, catalogRevision, treatments. sourceConfigurationRevision, revision, effectiveAt, rights et les définitions développées du catalogue n’en font pas partie ; catalogRevision lie séparément ces définitions. Cette convention propre à Control n’est pas une déclaration de conformité RFC 8785.

algorithm
sha-256
canonicalization
control-sorted-json-v1
value
SHA-256 encodé en hexadécimal minuscule.

Structure des réponses

Catalogue global

schemaVersion
Version numérique du schéma JSON. La version actuelle est 1.
catalogRevision
Empreinte stable du contenu déclaratif publié.
publishedAt
Date ISO 8601 de publication de cette projection du catalogue.
categories
Catégories lisibles regroupant les types de données.
dataPoints
Données unitaires susceptibles d’être utilisées par les traitements déclarés.
capabilities
Capacités Control pouvant donner accès à certaines données ou opérations.
treatments
Traitements du cœur et des modules, avec finalité, données, accès et conservation.
rights
Disponibilité et URL du parcours d’exercice des droits.

Notice d’un serveur

processing
may-collect si la configuration autorise le traitement futur ; stopped sinon.
storage
retained si des données subsistent, none si toutes les sondes répondent négativement, unknown si la preuve est incomplète.
storageVerification
Qualité de la preuve : fresh, stale, unavailable ou not-required.
roleAccess
Rôles explicitement liés aux capacités publiées, avec leurs opérations et données accessibles.
effectiveAt
Date ISO 8601 depuis laquelle cette révision de la notice est effective.
contentHash
Objet décrivant l’algorithme, la canonicalisation et la valeur hexadécimale de l’empreinte de l’état de notice.

Erreurs

404
Serveur ou révision introuvable.
429
Limite de débit dépassée. Respectez Retry-After avant une nouvelle tentative.
503
Révision momentanément indisponible après un échec de vérification d’intégrité. Retry-After indique quand réessayer.

Exemples

JavaScript dans un navigateur

const response = await fetch("https://bot.myvirtual.id/api/public/v1/privacy", { mode: "cors" });
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const catalog = await response.json();
console.log(response.headers.get("ETag"), response.headers.get("X-RateLimit-Remaining"));
console.log(catalog.schemaVersion, catalog.treatments);

cURL

curl --fail --show-error https://bot.myvirtual.id/api/public/v1/privacy