De to.co API
Laat je eigen software, zoals een website, een kassasysteem of een script, je bedrijf op to.co lezen en bijwerken. Sleutels zitten in Pro en Grow.
- Basis-URL
https://api.to.co/v1/orgs/{host}- Authenticatie
Authorization: Bearer toco_ak_…
Een API-sleutel maken
Open je bedrijf in my.to.co, kies API-sleutels en daarna Sleutel maken. Geef hem een naam, kies zijn rechten en wanneer hij verloopt (hooguit een jaar), en kopieer hem: hij wordt één keer getoond en alleen een hash ervan wordt bewaard.
Stuur de sleutel bij elk verzoek in de Authorization-header. Een sleutel werkt alleen voor zijn eigen bedrijf: elk ander adres antwoordt met ‘niet gevonden’. De API neemt alleen sleutels aan, nooit een browsersessie.
Voorbeeldaanroep
curl https://api.to.co/v1/orgs/mybusiness.uk.to.co \
-H "Authorization: Bearer toco_ak_…"Rechten en abonnementen
Een sleutel kan alleen wat zijn rechten toestaan, en alleen wat het abonnement van het bedrijf op het moment van elk verzoek omvat. Lezen zit in Pro en Grow; wijzigen in Grow.
| Recht | Wat het doet | Vanaf abonnement |
|---|---|---|
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
Elke route staat onder de basis-URL, met het to.co-adres van je bedrijf in plaats van {host}, bijvoorbeeld mybusiness.uk.to.co. Verzoeken en antwoorden zijn JSON. Wijzigingen doorlopen dezelfde controles, geschiedenis en herpublicatie als wijzigingen in my.to.co, vastgelegd als gedaan door de sleutel.
| Route | Wat het doet | Recht |
|---|---|---|
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 en limieten
- Elk verzoek gebruikt één API-credit, uit hetzelfde maandtegoed als de aanroepen van je eigen AI-assistent naar de MCP-server van je bedrijf: 5,000 per maand per bedrijf op Pro en 50,000 op Grow. Een mislukt verzoek geeft zijn credit terug. Credits beginnen opnieuw op de 1e van elke maand (UTC) en er zijn geen extra kosten. Antwoorden bevatten X-Credits-Limit, X-Credits-Remaining en X-Credits-Reset.
- Tot 120 verzoeken per minuut per sleutel.
- Tot 60 wijzigingen per minuut per bedrijf, samen geteld met wijzigingen in my.to.co en via MCP.
Fouten
Een fout antwoordt met een HTTP-status en JSON: error (een melding), code (een van de codes hieronder) en request_id. Een 429 bevat 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
Op Grow kan to.co ook ondertekende events naar je eigen server sturen als er iets verandert, zoals een nieuw bericht of gewijzigde bedrijfsgegevens. Stel ze in via my.to.co onder Webhooks.