The public API lets your own systems work with your books: a press's catalogue, its website or a build pipeline. They can read each book, its editions and formats, with the store details, ISBNs, prices, newest builds and where each format is listed, and, if you allow it, start builds and download the files.
Keys. The team's owner makes keys on the Settings page, under API keys. A key is shown once, when it's made: copy it then and keep it somewhere safe. Every key can read; tick "Can start builds" for one that may build too. A key acts as the owner who made it, reaches only this team's books and does nothing they couldn't do here. It stops working when it's revoked, when its maker is no longer the team's owner, or while the plan doesn't include the API. The team's keys may make 120 requests a minute between them. With two-factor sign-in on, making a key asks for a fresh code from your authenticator app.
Calls. Send the key in each request's Authorization header, as Bearer and then the key. The API lives under /api/v1 on the studio's address, and answers in JSON:
- GET /api/v1/team: the team the key belongs to, and the key's name and scopes. A good first call.
- GET /api/v1/books: the team's books, oldest first, up to 100 at a time (limit takes up to 500). When there are more, pass the answer's next as after for the next ones.
- GET /api/v1/books/{id}: one book and its editions.
- GET /api/v1/editions/{id}: one edition: its store details, its manuscript, and each format with its ISBN, trim, paper, prices, newest build and cover, and the stores it's listed in.
- POST /api/v1/formats/{id}/builds: build a format, as its Build button does (keys that can start builds). The answer is the build's job: new, or the one already on its way.
- GET /api/v1/jobs/{id}: the job: queued, running, done or failed, and once done, the build and its file.
- GET /api/v1/files/{id}: a build's file or a manuscript, as a download.
Mistakes come back with a status and a detail that says what to do: 401 for a missing or revoked key, 403 for something the key may not do, 404 for something it can't reach, 429 when it's going too fast.
Webhooks. Your systems can also hear when something happens, without asking: add a webhook on the Settings page with a public https address of yours and the events it wants:
- build.finished: a format's build finished, or failed.
- translation.stage_finished: a translation stage finished, or stopped.
- review.signed_off: your reviewer signed a translation off, with their note.
- listing.changed: a format's place in a store changed in the upload tracker.
Each event is a POST of JSON with its type, its time and its data, signed the way Standard Webhooks (standardwebhooks.com) sign them: the webhook-id, webhook-timestamp and webhook-signature headers, made with the endpoint's secret, which is shown once when you add it. Their libraries check it for you. Answer with any 2xx status within ten seconds (the studio reads only the status, never the body); otherwise it tries again after about a minute, five, half an hour, two hours, six, twelve and a day, or later if your answer says Retry-After. When five events in a row are given up, or the address answers 410 Gone, the endpoint is turned off: the card says why, and turns it on again. Send a test to see a delivery arrive.
An event carries what it's about, and that can be personal: your reviewer's name and the note they signed off with, or the message a failed build or translation stage stopped with. Send them only to a system you trust with that.
Webhooks go only to public https addresses on port 443 or 8443: an address that leads to a private network isn't accepted, and redirects aren't followed.
What you need: the Publisher plan, and to be the team's owner to make keys and add webhooks.