to.co API
Låt din egen programvara, till exempel en webbplats, ett kassasystem eller ett skript, läsa ditt företag på to.co och hålla det uppdaterat. Nycklar ingår i Pro och Grow.
- Bas-URL
https://api.to.co/v1/orgs/{host}- Autentisering
Authorization: Bearer toco_ak_…
Skaffa en API-nyckel
Öppna ditt företag i my.to.co, välj API-nycklar och sedan Skapa nyckel. Ge den ett namn, välj behörigheter och när den löper ut (högst ett år), och kopiera den: den visas en gång och bara en hash av den sparas.
Skicka nyckeln i Authorization-huvudet i varje begäran. En nyckel fungerar bara för sitt eget företag: alla andra adresser svarar ”hittades inte”. API:t tar bara emot nycklar, aldrig en webbläsarsession.
Exempelanrop
curl https://api.to.co/v1/orgs/mybusiness.uk.to.co \
-H "Authorization: Bearer toco_ak_…"Behörigheter och planer
En nyckel kan bara göra det dess behörigheter tillåter, och bara det som företagets plan omfattar när varje begäran görs. Läsning ingår i Pro och Grow, ändringar i Grow.
| Behörighet | Vad den gör | Från plan |
|---|---|---|
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
Alla routes ligger under bas-URL:en, med ditt företags to.co-adress i stället för {host}, till exempel mybusiness.uk.to.co. Begäranden och svar är JSON. Ändringar går igenom samma kontroller, historik och ompublicering som ändringar i my.to.co och registreras som gjorda av nyckeln.
| Route | Vad den gör | Behörighet |
|---|---|---|
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 |
Krediter och gränser
- Varje begäran använder en API-kredit, ur samma månadspott som din egen AI-assistents anrop till ditt företags MCP-server: 5,000 i månaden per företag på Pro och 50,000 på Grow. En begäran som misslyckas ger tillbaka sin kredit. Krediterna börjar om den 1:a varje månad (UTC), och det finns inga extra avgifter. Svaren innehåller X-Credits-Limit, X-Credits-Remaining och X-Credits-Reset.
- Upp till 120 begäranden i minuten per nyckel.
- Upp till 60 ändringar i minuten per företag, räknat tillsammans med ändringar i my.to.co och via MCP.
Fel
Ett fel svarar med en HTTP-status och JSON: error (ett meddelande), code (en av koderna nedan) och request_id. Ett 429-svar innehåller 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
På Grow kan to.co också skicka signerade händelser till din egen server när något ändras, till exempel ett nytt meddelande eller ändrade företagsuppgifter. Ställ in dem i my.to.co under Webhooks.