Book seats on ADOPTR from your own app.

Build with an AI agent

Using Claude, Cursor or another coding agent? Give it the instructions for agents (adoptr.uk/developers/agent.md, or "Copy instructions" on the guide). They tell it what to read, how to keep the key safe and how to pass the go-live checklist on the sandbox. It stops before going live: a person at your rescue asks for the live key.

• https://adoptr.uk/developers.md: this guide as Markdown.
• https://adoptr.uk/llms.txt: the index for agents.
• https://adoptr.uk/api/v1/openapi.json: OpenAPI 3.1, for Postman or a generated client.

How a booking goes

1. See the dates. GET /departures: deadlines and seats free.
2. Hold seats. POST /holds, before you know the animals.
3. Add each animal. POST /holds/{id}/animals: one seat becomes one animal.
4. ADOPTR takes it from there. Papers, the CHED, the route and the family's tracking link.

Keys

Every call sends your key: Authorization: Bearer <key>. A key belongs to your rescue: every answer holds only your animals and your seats, never another rescue's.

• Test keys (adk_test_…) work only on the sandbox. Make them yourself at adoptr.uk/rescue/api.
• Live keys (adk_live_…) work only on adoptr.uk. Ask for one on the same page once your app passes the go-live checklist; ADOPTR approves it and says what it may do. It is shown once, when you open it.
• Every key reads. A key holds and gives back seats only with hold, and adds animals only with confirm: animals go on held seats, so a key with confirm has hold too.
• Keep the key on your server, in an environment variable such as ADOPTR_API_KEY. Anyone holding it can book seats for your rescue. The API doesn't answer browsers, so it can't live in a web page or a phone app. If a key leaks, revoke it on the same page and make another.

Sandbox

https://sandbox.adoptr.uk/api/v1, with a test key. Made-up departures, put back as new every night at 03:00 UTC. Nothing there reaches a real family, van or border.

• Four departures: a full one (seats_free 0), one with the dogs' Brucella window open today, an empty one weeks away, and a closed one (past closes_on).
• Three animals of your own, there as soon as you make your first test key: one ready, one without a passport, one on the waiting list. Their microchips start 999.
• Hold seats on the empty departure: the others are full, closed, or already too late for an animal sent without its rabies vaccine.

Departures

GET /departures: the departures listed on adoptr.uk that haven't left, and any still on the road with your animals, soonest first. A departure is named by the day it leaves Romania (leaves_on).

• status: open; closed (past closes_on, no animal can join); on_the_road; done; not_listed (not on adoptr.uk, shown because your animals are on it).
• confirmed: enough animals booked for the van to go on this day; until then the day is an estimate.
• deadlines.closes_on: the last day an animal can join. rabies_by: the last day a rabies vaccine counts. brucella_window_from/_to: when to take dogs' Brucella samples; last_brucella_sample: the last day a sample is accepted.
• seats_free: seats anyone can still ask for, counted as adoptr.uk counts its places for the UK: the departure's UK places less the animals going to the UK, the seats held and the places kept for rescues; never more than the van's empty crates (animals going to the EU take crates too).
• yours: your animals on it, your seats held (each hold with its id and expires_at), and places ADOPTR keeps for you not filled yet.

Your animals

GET /animals: your animals on departures still ahead or on the road, and on the waiting list (leaves_on null), by id. Filters: leaves_on=YYYY-MM-DD, papers=ready|missing|blocked. Pages: limit (1 to 200, 100 by default), then after=<next_after> while next_after isn't null.

GET /animals/{id}: one of yours, in animal.

• papers: ready, missing (still to come, to_do says what) or blocked (can't make this departure); null, with to_do empty, for an animal on the waiting list.
• The adopter's address, phone and email are never sent back, only their name and postcode.

Seats

Your key does these only when ADOPTR allowed them: hold for holding and giving back seats, confirm for adding animals. Send an Idempotency-Key with each (see Retries).

Retries

Send an Idempotency-Key header with every POST and DELETE: 1 to 100 printable characters, no spaces, yours to choose (a UUID, for example). Sent again with the same key and the same body, byte for byte, within a day, the API answers as the first time and does nothing twice, a refusal such as not_enough_seats included. A call refused before it starts (a body that isn't valid, a bad key, too large) isn't kept: put it right and send it with the same key. Use a new key for a new action, and the same key when you retry one.

• The same key with another body: idempotency_conflict.
• While the first call is still running: idempotency_running. Send it again after Retry-After seconds.

Errors and limits

Errors are { "error": { "code", "message" } }. Branch on code; the message is for people and can change. Some errors say more: seats_free (with not_enough_seats), limit and held (with over_seat_limit), to_do (with papers_blocked).

Per key: 60 reads and 20 writes a minute, 5,000 calls a day.

ADOPTR keeps your calls 30 days, to help when something goes wrong: what was asked and any error, without the adopter's address, phone and email.

Go-live checklist

Your app makes these twelve calls on the sandbox, with your test keys. Each ticks itself at adoptr.uk/rescue/api when the sandbox sees it; the ticks stay when the sandbox is reset, and start again once a live key is approved, so each app passes with its own calls. A key that only reads needs the first four; one that holds seats, the first nine; one that adds animals, all twelve. Hold on the empty departure. Your app should also show your people what each answer means, not only make the call.

1. GET /departures answers 200.
2. GET /departures/{leaves_on} answers 200.
3. GET /animals?limit=1, then again with after set to next_after.
4. GET /animals/{id} answers 200.
5. POST /holds on the empty departure answers 201, sent with an Idempotency-Key.
6. The same POST /holds, sent again with the same key and body, gets the same answer.
7. POST /holds on the full departure (seats_free 0) answers 409 not_enough_seats.
8. POST /holds on the closed departure answers 409 departure_closed.
9. DELETE /holds/{id} answers 200. Then hold 3 seats again, for the next three.
10. POST /holds/{id}/animals with only name, species and a new chip answers 201.
11. POST /holds/{id}/animals with rabies_on before microchipped_on answers 422 papers_blocked.
12. POST /holds/{id}/animals with the chip of one of your sandbox animals answers 409 chip_taken.

Versions

New fields can appear in v1 at any time: ignore those you don't know. A change that would break your app comes as /api/v2, and v1 keeps working at least 6 months after it.