Commencer

Il vous faut :

• un compte utilisateur de Docage, dans l'organisation où vous travaillerez : l'API agit en son nom, avec ses droits ;
• sa clé API, générée dans sa fiche (onglet Clé API), ou son mot de passe.

Votre premier appel

Demandez un jeton (voir S'authentifier), puis lisez les cinq contacts créés le plus récemment :

QUERY https://staging-api.docage.com/Contacts
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
  "SortOrder": "CreationDate_Desc",
  "Take": 5,
  "EntityProperties": ["Id", "FirstName", "LastName", "Email"]
}

curl -X QUERY "https://staging-api.docage.com/Contacts" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…" \
  -H "Content-Type: application/json" \
  -d '{
    "SortOrder": "CreationDate_Desc",
    "Take": 5,
    "EntityProperties": ["Id", "FirstName", "LastName", "Email"]
  }'

using HttpClient client = new();
using HttpRequestMessage request = new(new HttpMethod("QUERY"), "https://staging-api.docage.com/Contacts");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = new StringContent("""
    {
      "SortOrder": "CreationDate_Desc",
      "Take": 5,
      "EntityProperties": [
        "Id",
        "FirstName",
        "LastName",
        "Email"
      ]
    }
    """, Encoding.UTF8, "application/json");
using HttpResponseMessage response = await client.SendAsync(request);
string result = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
    throw new HttpRequestException(result);

const response = await fetch("https://staging-api.docage.com/Contacts", {
  method: "QUERY",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "SortOrder": "CreationDate_Desc",
    "Take": 5,
    "EntityProperties": ["Id", "FirstName", "LastName", "Email"]
  })
});
const text = await response.text();
if (!response.ok) throw new Error(text);
const result = text ? JSON.parse(text) : null;

La réponse est la liste des contacts. L'en-tête Docage-TotalItems dit combien la liste en compte en tout, au-delà de la page rendue. Lire des listes détaille le filtre, le tri et la pagination.

Les conventions de tous les échanges

• JSON, noms de propriétés en PascalCase (FirstName, ParentOrganizationId), tels que la référence les écrit.
• Identifiants : chaque fiche a son identifiant Id, un GUID (3f2504e0-4f89-11d3-9a0c-0305e82c3301).
• Énumérations : écrites en nombres (2). L'API lit aussi le nom du membre ; la référence donne, pour chaque valeur, son libellé.
• Dates : en UTC, au format ISO 8601, avec leur fuseau — voir Dates et fuseaux.
• Droits : une route ne rend que ce que l'utilisateur a le droit de voir, et refuse ce qu'il n'a pas le droit de faire — voir Droits et visibilité.

Pour aller plus loin

• les principes : créer et modifier, modèles et instances, erreurs ;
• le démarrage rapide : un besoin courant, du premier appel au résultat, rangé par thème ;
• le menu Intégralité des routes, dans le sommaire : chaque route, ses paramètres et ses réponses, avec une console pour l'essayer ;
• les définitions des objets : chaque fiche, ses propriétés, ses énumérations et ses liaisons.

Pour un outil ou un agent IA

• La référence complète, au format OpenAPI 3.1 (JSON), de quoi générer un client ; chaque route y porte un identifiant (operationId), le nom de sa méthode dans le client :

  Copier

  https://staging-api.docage.com/openapi/v2-fr.json

• L'index des routes, pour un agent : une ligne par route, et l'adresse du document OpenAPI de chaque contrôleur, autonome et assez court pour son contexte, https://staging-api.docage.com/openapi/v2-fr/index.md.

• Le llms.txt de l'API, https://staging-api.docage.com/llms.txt (la racine de l'API y renvoie) : pour un agent qui n'a que l'adresse de l'API, où lire sa référence et sa documentation.

• L'index de cette documentation, https://staging-app.docage.com/llms.txt : chaque page dans sa version Markdown. https://staging-app.docage.com/llms-full.txt réunit toute la partie API en un fichier.

• Chaque page en Markdown : son adresse suivie de .md (https://staging-app.docage.com/documentation/api/commencer.md), ou le bouton Copier en Markdown de la page.

• Intégrer avec un agent IA rassemble ce qu'un agent doit savoir avant d'écrire une intégration.