# API HTTP

> Les routes derrière le CLI et l'espace client, pour écrire ton propre outil.

Le CLI n'a aucun privilège particulier : il appelle la même API que l'espace client, avec
un [jeton](/commencer/jetons) au lieu d'un cookie de session. Tout ce qu'il fait, tu peux
le faire.

```bash
curl https://api.arkya.gg/api/resources \
  -H "Authorization: Bearer ark_xxxxxxxxxxxx"
```

## Par où commencer

<CardGroup cols={2}>
  <Card title="Toutes les routes" icon="table-list" href="/api/reference">
    La surface publique en une page. Le raccourci quand tu cherches quelque chose.
  </Card>
  <Card title="Authentification" icon="key" href="/api/authentification">
    Le jeton, ses deux portées, ce qu'elles ouvrent.
  </Card>
  <Card title="Services" icon="server" href="/api/services">
    Lister, lire, suivre l'état — et les capacités, qui décident du reste.
  </Card>
  <Card title="Erreurs" icon="triangle-exclamation" href="/api/erreurs">
    Les codes, la forme des messages, quoi faire de chacun.
  </Card>
</CardGroup>

## Piloter un service

<CardGroup cols={3}>
  <Card title="Marche et arrêt" icon="power-off" href="/api/cycle-de-vie" />
  <Card title="Réglages" icon="sliders" href="/api/reglages" />
  <Card title="Variables" icon="list-check" href="/api/variables" />
  <Card title="Journaux" icon="file-lines" href="/api/journaux" />
  <Card title="Console" icon="signal-stream" href="/api/console" />
  <Card title="Fichiers" icon="folder-open" href="/api/fichiers" />
  <Card title="Sauvegardes" icon="clock-rotate-left" href="/api/sauvegardes" />
  <Card title="SFTP" icon="key" href="/api/sftp" />
  <Card title="Bases de données" icon="database" href="/api/bases-de-donnees" />
</CardGroup>

## Construire

<CardGroup cols={3}>
  <Card title="Projets" icon="layer-group" href="/api/projets" />
  <Card title="Commander" icon="cart-shopping" href="/api/commander" />
  <Card title="Applications" icon="container-storage" href="/api/applications" />
  <Card title="Facturation" icon="receipt" href="/api/facturation" />
  <Card title="Clés SSH" icon="key" href="/api/cles-ssh" />
</CardGroup>

## Les conventions

| | |
| --- | --- |
| Racine | `https://api.arkya.gg` |
| Format | JSON en entrée comme en sortie, UTF-8 |
| Authentification | `Authorization: Bearer ark_…` |
| Dates | ISO 8601 en UTC, `2026-09-17T17:41:57.078Z` |
| Montants | En **cents**, sauf les champs en `…Millicents` qui valent un dixième de cent |
| Identifiants | Opaques. Ne les découpe pas, ne suppose rien de leur forme |

### Ce qui n'est jamais rendu deux fois

Un mot de passe SFTP, un secret généré à la commande, le secret d'un jeton : ces valeurs
sortent **à l'appel qui les crée**, et jamais ensuite. Garde-les à ce moment-là, ou
régénère-les — ce qui invalide la précédente.

### Lire la réponse plutôt que la deviner

Toutes les routes rendent la même forme que ce que `--json` affiche dans le CLI :

```bash
ark ls --json
ark info mon-service --json
ark settings mon-service --json
```

### La limite de débit

L'API accepte un usage raisonnable sans limite affichée. Une boucle qui interroge
`/api/resources` toutes les secondes finira par recevoir des `429` : espace tes appels,
et préfère le WebSocket de la [console](/api/console) à un sondage pour suivre un état.

### Ce qui n'est pas ici

L'administration, le protocole du daemon et les parcours de paiement ne sont pas exposés.
[La page des routes](/api/reference#ce-qui-nest-pas-exposé-et-pourquoi) dit lesquels, et
pourquoi.