Get connected
- Create a token in your workspace. Today the setup wizard shows it once, at the end of setup; keep it in a password manager.
- Send it with every request, as the header
Authorization: Bearer YOUR_TOKEN. A token typed into a command stays in your shell's history. Put it in a variable first, with read -rs TOKEN, and write $TOKEN in place of YOUR_TOKEN. - Try the first call. It answers with your workspace's name and the server's version.
Kept in this tab only, never stored.
curl https://YOUR-SITE/api/v1/me -H "Authorization: Bearer YOUR_TOKEN"Guides
Reference
Upload and publish a tour
A tour is uploaded as a draft in three kinds of request, then published. Nothing is public until the publish finishes.
In the examples, YOUR_TOKEN is your token; UPLOAD_ID is the upload_id from the first answer; TOUR_ID is the tour_id from the answer that finished the upload; step-001.png is a PNG picture of exactly the width, height and bytes the manifest gives; logo.png is a PNG picture. A token typed into a command stays in your shell's history. Put it in a variable first, with read -rs TOKEN, and write $TOKEN in place of YOUR_TOKEN.
Start the upload with the tour's manifest. Note the upload_id in the answer.
curl https://YOUR-SITE/api/v1/uploads -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"manifest":{"version":3,"generator":"curl","title":"My first tour","steps":[{"image":"step-001.png","width":1280,"height":720,"bytes":48213,"click":{"x":50,"y":50},"t_ms":0}],"cover":{"title":"My first tour","logo":"logo.png"}},"target":{"kind":"new"}}'Answers 201.
Send each step's image, numbered from 1. The image must have the size and length the manifest gives.
curl -X PUT https://YOUR-SITE/api/v1/uploads/UPLOAD_ID/steps/1 -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: image/png" --data-binary @step-001.pngAnswers 204.
If the manifest names a logo, send it too.
curl -X PUT https://YOUR-SITE/api/v1/uploads/UPLOAD_ID/logo -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: image/png" --data-binary @logo.pngAnswers 204.
Finish the upload. The answer has the tour_id.
curl -X POST https://YOUR-SITE/api/v1/uploads/UPLOAD_ID/commit -H "Authorization: Bearer YOUR_TOKEN"Answers 201.
Publish the tour. A small tour answers 200 at once; a large one answers 202 with a publish_id: send the request again with that id until it answers 200.
curl -X POST https://YOUR-SITE/api/v1/tours/TOUR_ID/publish -H "Authorization: Bearer YOUR_TOKEN"Answers 200 when it is done, 202 until then.
The answer's url is the tour's link, as a path to put after your site's address.
To take the tour down again, unpublish it.
curl -X POST https://YOUR-SITE/api/v1/tours/TOUR_ID/unpublish -H "Authorization: Bearer YOUR_TOKEN"Answers 204.
Update a tour over the same link
To change a published tour, replace one of its chapters and publish again. The link and the title stay the same, and visitors see the old version until the publish finishes.
In the examples, YOUR_TOKEN is your token; TOUR_ID is the tour's id; CHAPTER_ID is the chapter_id from the answer that finished the chapter's upload; SHA256_OF_STEP_001 is the SHA-256 of step-001.png, as 64 lowercase hex characters, and likewise for SHA256_OF_STEP_002; UPLOAD_ID is the upload_id from this guide's first answer; step-002.png is a PNG picture of exactly the width, height and bytes the manifest gives. A token typed into a command stays in your shell's history. Put it in a variable first, with read -rs TOKEN, and write $TOKEN in place of YOUR_TOKEN.
Start an upload that replaces the chapter. With a SHA-256 for each picture, the answer's have lists the steps the site already has, so you do not send them.
Replacing a tour's first chapter also replaces the tour's settings and logo with the manifest's; the answer's settings is then true. This example's manifest names no logo, so the tour ends up without one.
curl https://YOUR-SITE/api/v1/uploads -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"manifest":{"version":3,"generator":"curl","title":"My first tour","steps":[{"image":"step-001.png","width":1280,"height":720,"bytes":48213,"click":{"x":50,"y":50},"t_ms":0},{"image":"step-002.png","width":1280,"height":720,"bytes":51022,"click":null,"t_ms":1500}],"cover":{"title":"My first tour"}},"target":{"kind":"replace","tour_id":"TOUR_ID","chapter_id":"CHAPTER_ID"},"sha256":["SHA256_OF_STEP_001","SHA256_OF_STEP_002"]}'Answers 201.
Send the other steps' images.
curl -X PUT https://YOUR-SITE/api/v1/uploads/UPLOAD_ID/steps/2 -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: image/png" --data-binary @step-002.pngAnswers 204.
Finish the upload. The answer's publish says what publishing would do now: draft, ready or other_changes.
curl -X POST https://YOUR-SITE/api/v1/uploads/UPLOAD_ID/commit -H "Authorization: Bearer YOUR_TOKEN"Answers 201.
If it says ready, publish the tour as in the first guide.
curl -X POST https://YOUR-SITE/api/v1/tours/TOUR_ID/publish -H "Authorization: Bearer YOUR_TOKEN"Answers 200 when it is done, 202 until then.
To give up instead, cancel the upload; it removes only what this upload stored.
curl -X DELETE https://YOUR-SITE/api/v1/uploads/UPLOAD_ID -H "Authorization: Bearer YOUR_TOKEN"Answers 204.
Errors and limits
Every refusal is JSON with an error code and, mostly, a detail in plain words. The codes are stable; the detail text may change.
In the examples, YOUR_TOKEN is your token; TOUR_ID is the id of one of your tours. A token typed into a command stays in your shell's history. Put it in a variable first, with read -rs TOKEN, and write $TOKEN in place of YOUR_TOKEN.
A missing or wrong token answers 401.
curl https://YOUR-SITE/api/v1/meAnswers 401.
Another workspace's tour answers 404, the same as one that does not exist.
curl -X PATCH https://YOUR-SITE/api/v1/tours/tour_000000000000000000000000 -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"title":"A new title"}'Answers 404.
A body that is not what the request expects answers 400 with the reason.
curl -X PATCH https://YOUR-SITE/api/v1/tours/TOUR_ID -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" -d '{"title":""}'Answers 400.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_image | The picture sent is not the one the manifest describes; the detail says what differs. |
| 400 | bad_manifest | The manifest breaks a rule; the detail names the field. |
| 400 | bad_request | The body is not what the request expects. |
| 400 | bad_target | The upload's target is missing, or its kind is not new, chapter or replace. |
| 400 | bad_title | The title breaks the rule for a title; the detail says how. |
| 400 | empty_tour | A tour with no steps cannot be published. |
| 401 | unauthorized | The token is missing, malformed, unknown or revoked. This answer has no detail. |
| 404 | not_found | Nothing with that id in this workspace, or no request has that address. |
| 409 | already_sent | This step's image, or the logo, was already sent. |
| 409 | chapter_changed | Another upload replaced the chapter first; cancel this upload and start again. |
| 409 | incomplete | An image, or the logo, has not been sent yet; nothing changed. |
| 409 | logo_not_used | The upload goes into an existing tour, which keeps its logo; do not send one. |
| 409 | publish_busy | A publish of the tour is in progress or just starting; try again. |
| 409 | publish_cancelled | That publish was stopped before it finished; publish again to start over. |
| 413 | too_large | The body, the picture or the tour is over a limit. |
| 429 | too_many_uploads | The workspace has its number of open uploads; finish or cancel one. The retry-after header says how long to wait. |
| 500 | cleanup_pending | The tour is deleted or unpublished, but some files are still to be removed; send the same request again. |
| 500 | internal | The server failed; nothing about the failure is given. |
| 500 | misconfigured | On Cloudflare, the two addresses in the settings cannot be used together. |
| 500 | publish_failed | The tour could not be published; what was published before is unchanged. |
Limits
- 200 steps in one upload, and 20 notes on a step.
- The manifest: 262,144 bytes.
- A step image: 2,000,000 bytes and 4,096 pixels on a side, PNG or JPEG.
- The logo: 200,000 bytes and 512 pixels on a side, PNG or JPEG.
- Text, in characters after trimming: title 200, generator 100, note text 500, card title 80, card body 300, next label 24, cover title 80, cover body 200, cover button 24, button label 24, end text 200, link 500.
- 400 steps in one published tour, and 512,000 bytes for its text (titles, notes, cards and settings together).
- One publish request copies up to 12 images; one delete request removes up to 250 files.
- 5 open uploads per workspace, unless the server's settings give another number.
- An upload that is not finished is removed after 24 hours.
- A publish that makes no progress for 15 minutes counts as abandoned.
Requests that work in steps (publish, unpublish, delete) are safe to send again; send the same request until it answers 200 or 204.
With two addresses, a request to any other host name answers 421 with nothing in it.