[Serveur MCP](https://to.co/fr-fr/docs/mcp?format=md) · **API**

# L’API to.co

Laissez votre propre logiciel, comme un site web, une caisse ou un script, lire votre entreprise sur to.co et la tenir à jour. Les clés sont incluses dans Pro et Grow.

- URL de base: `https://api.to.co/v1/orgs/{host}`
- Authentification: `Authorization: Bearer toco_ak_…`

## Obtenir une clé d’API

Ouvrez votre entreprise dans my.to.co, choisissez Clés d’API, puis Créer une clé. Donnez-lui un nom, choisissez ses autorisations et sa date d’expiration (un an au plus), puis copiez-la : elle n’est affichée qu’une fois et seule son empreinte est conservée.

Envoyez la clé dans l’en-tête Authorization à chaque requête. Une clé ne fonctionne que pour sa propre entreprise : toute autre adresse répond « introuvable ». L’API n’accepte que des clés, jamais une session de navigateur.

Exemple d’appel:

```shell
curl https://api.to.co/v1/orgs/mybusiness.uk.to.co \
  -H "Authorization: Bearer toco_ak_…"
```

## Autorisations et offres

Une clé ne peut faire que ce que ses autorisations permettent, et seulement ce que l’offre de l’entreprise inclut au moment de chaque requête. La lecture est incluse dans Pro et Grow ; les modifications dans Grow.

| Autorisation | Ce qu’elle permet | À partir de l’offre |
|---|---|---|
| `company:read` | Your company details, services and locations. | Pro |
| `messages:read` | Messages from your contact form (not those held as spam). | Pro |
| `company:write` | Replace your services, and change phone numbers and opening hours. | Grow |
| `posts:read` | The posts you write on to.co, drafts included. | Pro |
| `posts:write` | Write, save, publish, unpublish and delete posts. | Grow |

## Routes

Chaque route se trouve sous l’URL de base, avec l’adresse to.co de votre entreprise à la place de `{host}`, par exemple mybusiness.uk.to.co. Les requêtes et les réponses sont en JSON. Les modifications passent par les mêmes contrôles, le même historique et la même republication que celles faites dans my.to.co, et sont enregistrées comme faites par la clé.

| Route | Ce qu’elle permet | Autorisation |
|---|---|---|
| `GET /v1/orgs/{host}` | The company record, with its services and locations. | `company:read` |
| `GET /v1/orgs/{host}/services` | The services, in order. | `company:read` |
| `GET /v1/orgs/{host}/locations` | The locations, with phones and opening hours. | `company:read` |
| `GET /v1/orgs/{host}/messages` | Contact form messages. Filter with ?status=new\|read\|replied\|archived. | `messages:read` |
| `GET /v1/orgs/{host}/messages/{id}` | One message. | `messages:read` |
| `PATCH /v1/orgs/{host}` | Change the company phone numbers: JSON { "phones": … }. | `company:write` |
| `PUT /v1/orgs/{host}/services` | Replace the whole list of services, in order: JSON { "services": [ … ] }. | `company:write` |
| `PATCH /v1/orgs/{host}/locations/{location}` | Change a location: JSON with any of phones, normal_hours and special_hours. Every value is checked, and the answer carries the checks. The registered office comes from the register and cannot be changed. | `company:write` |
| `GET /v1/orgs/{host}/posts` | Posts written on to.co, newest change first, a page at a time: ?limit, ?state and ?cursor (next_cursor from the page before). | `posts:read` |
| `GET /v1/orgs/{host}/posts/{id}` | One post, its body as blocks, with its version as the ETag. | `posts:read` |
| `POST /v1/orgs/{host}/posts` | A new draft: JSON { "title", "standfirst", "body" }, or the body as text/markdown. | `posts:write` |
| `PATCH /v1/orgs/{host}/posts/{id}` | Save a post. Send the version you are changing as If-Match; JSON, or the body as text/markdown. | `posts:write` |
| `DELETE /v1/orgs/{host}/posts/{id}` | Move a post to the bin. The owner can restore it in my.to.co for 30 days. | `posts:write` |
| `POST /v1/orgs/{host}/posts/{id}/publish` | Publish the If-Match version. It is checked first, as when the owner publishes. | `posts:write` |
| `POST /v1/orgs/{host}/posts/{id}/unpublish` | Take a post off the page and back to a draft. | `posts:write` |

## Crédits et limites

- Chaque requête utilise un crédit d’API, pris sur la même allocation mensuelle que les appels de votre propre assistant IA au serveur MCP de votre entreprise : 5,000 par mois et par entreprise avec Pro et 50,000 avec Grow. Une requête qui échoue rend son crédit. Les crédits repartent le 1er de chaque mois (UTC), sans frais de dépassement. Les réponses portent X-Credits-Limit, X-Credits-Remaining et X-Credits-Reset.
- Jusqu’à 120 requêtes par minute et par clé.
- Jusqu’à 60 modifications par minute et par entreprise, comptées avec celles faites dans my.to.co et via MCP.

## Erreurs

Une erreur répond avec un statut HTTP et du JSON : error (un message), code (l’un de ceux ci-dessous) et request_id. Une 429 porte Retry-After.

- `invalid_request` (400): The body or a query value is not valid; the message says which field.
- `cookie_not_accepted` (400): The request carried a browser session. This API takes an API key only.
- `if_match_required` (400): A post change without If-Match.
- `not_ready` (400): The post cannot be published yet; problems lists why.
- `image_unknown` (400): A post body shows an image the post does not have. A key cannot upload images.
- `invalid_key` (401): No key, or one that is unknown, revoked or expired.
- `insufficient_scope` (403): The key does not have the scope this route needs.
- `plan_required` (403): The company plan does not include this scope now; plan_needed names the plan that does.
- `insufficient_role` (403): The person who made the key no longer has the role for this; an owner makes a new key.
- `not_found` (404): Not found. A host other than the key's own company is always not found.
- `registered_office` (409): The registered office comes from the company register and cannot be changed with a key.
- `post_changed` (409): The post changed since the If-Match version. Read it again.
- `post_deleted` (409): The post is in the bin.
- `not_draft` (409): Only a draft can be scheduled.
- `slug_taken` (409): Another post already uses that address.
- `rate_limited` (429): Too many requests. Wait for Retry-After.
- `credits_exhausted` (429): This month's API credits are used. They start again on the first of next month; there are no overage charges.
- `credits_unavailable` (503): The API cannot count credits right now. Try again later.

## Webhooks

Avec Grow, to.co peut aussi envoyer des événements signés à votre propre serveur quand quelque chose change, comme un nouveau message ou une modification des informations de votre entreprise. Configurez-les dans my.to.co sous Webhooks.

## Étapes suivantes

- [Le serveur MCP de to.co, pour les assistants IA](https://to.co/fr-fr/docs/mcp?format=md)
- [Ouvrir my.to.co](https://my.to.co)