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

# Die to.co API

Lassen Sie Ihre eigene Software, etwa eine Website, ein Kassensystem oder ein Skript, Ihr Unternehmen auf to.co lesen und aktuell halten. Schlüssel gibt es in Pro und Grow.

- Basis-URL: `https://api.to.co/v1/orgs/{host}`
- Authentifizierung: `Authorization: Bearer toco_ak_…`

## Einen API-Schlüssel erstellen

Öffnen Sie Ihr Unternehmen in my.to.co, wählen Sie API-Schlüssel und dann Schlüssel erstellen. Geben Sie ihm einen Namen, wählen Sie seine Berechtigungen und wann er abläuft (höchstens ein Jahr), und kopieren Sie ihn: Er wird einmal angezeigt, und gespeichert wird nur ein Hash davon.

Senden Sie den Schlüssel bei jeder Anfrage im Authorization-Header. Ein Schlüssel gilt nur für sein eigenes Unternehmen: Jede andere Adresse antwortet mit „nicht gefunden“. Die API nimmt nur Schlüssel an, nie eine Browsersitzung.

Beispielaufruf:

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

## Berechtigungen und Tarife

Ein Schlüssel kann nur, was seine Berechtigungen erlauben, und nur, was der Tarif des Unternehmens zum Zeitpunkt jeder Anfrage enthält. Lesen gibt es in Pro und Grow, Änderungen in Grow.

| Berechtigung | Was sie tut | Ab Tarif |
|---|---|---|
| `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 |

## Routen

Jede Route liegt unter der Basis-URL, mit der to.co-Adresse Ihres Unternehmens anstelle von `{host}`, zum Beispiel mybusiness.uk.to.co. Anfragen und Antworten sind JSON. Änderungen durchlaufen dieselben Prüfungen, denselben Verlauf und dieselbe Neuveröffentlichung wie Änderungen in my.to.co und werden als vom Schlüssel vorgenommen erfasst.

| Route | Was sie tut | Berechtigung |
|---|---|---|
| `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` |

## Credits und Limits

- Jede Anfrage verbraucht einen API-Credit aus demselben monatlichen Kontingent wie die Aufrufe Ihres eigenen KI-Assistenten an den MCP-Server Ihres Unternehmens: 5,000 pro Monat und Unternehmen in Pro und 50,000 in Grow. Eine fehlgeschlagene Anfrage gibt ihren Credit zurück. Die Credits beginnen am 1. jedes Monats (UTC) neu, und es gibt keine Zusatzkosten. Antworten enthalten X-Credits-Limit, X-Credits-Remaining und X-Credits-Reset.
- Bis zu 120 Anfragen pro Minute und Schlüssel.
- Bis zu 60 Änderungen pro Minute und Unternehmen, zusammen mit Änderungen in my.to.co und über MCP gezählt.

## Fehler

Ein Fehler antwortet mit einem HTTP-Status und JSON: error (eine Meldung), code (einer der folgenden) und request_id. Ein 429 enthält 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

In Grow kann to.co außerdem signierte Ereignisse an Ihren eigenen Server senden, wenn sich etwas ändert, etwa bei einer neuen Nachricht oder geänderten Unternehmensdaten. Richten Sie sie in my.to.co unter Webhooks ein.

## Nächste Schritte

- [Der to.co MCP-Server für KI-Assistenten](https://to.co/de-de/docs/mcp?format=md)
- [my.to.co öffnen](https://my.to.co)