Get connected

  1. Create a token in your workspace. Today the setup wizard shows it once, at the end of setup; keep it in a password manager.
  2. 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.
  3. Try the first call. It answers with your workspace's name and the server's version.
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.

  1. 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.

  2. 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.png

    Answers 204.

  3. 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.png

    Answers 204.

  4. 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.

  5. 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.

  6. The answer's url is the tour's link, as a path to put after your site's address.

  7. 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.

  1. 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.

  2. 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.png

    Answers 204.

  3. 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.

  4. 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.

  5. 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.

  1. A missing or wrong token answers 401.

    curl https://YOUR-SITE/api/v1/me

    Answers 401.

  2. 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.

  3. 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

StatusCodeMeaning
400bad_imageThe picture sent is not the one the manifest describes; the detail says what differs.
400bad_manifestThe manifest breaks a rule; the detail names the field.
400bad_requestThe body is not what the request expects.
400bad_targetThe upload's target is missing, or its kind is not new, chapter or replace.
400bad_titleThe title breaks the rule for a title; the detail says how.
400empty_tourA tour with no steps cannot be published.
401unauthorizedThe token is missing, malformed, unknown or revoked. This answer has no detail.
404not_foundNothing with that id in this workspace, or no request has that address.
409already_sentThis step's image, or the logo, was already sent.
409chapter_changedAnother upload replaced the chapter first; cancel this upload and start again.
409incompleteAn image, or the logo, has not been sent yet; nothing changed.
409logo_not_usedThe upload goes into an existing tour, which keeps its logo; do not send one.
409publish_busyA publish of the tour is in progress or just starting; try again.
409publish_cancelledThat publish was stopped before it finished; publish again to start over.
413too_largeThe body, the picture or the tour is over a limit.
429too_many_uploadsThe workspace has its number of open uploads; finish or cancel one. The retry-after header says how long to wait.
500cleanup_pendingThe tour is deleted or unpublished, but some files are still to be removed; send the same request again.
500internalThe server failed; nothing about the failure is given.
500misconfiguredOn Cloudflare, the two addresses in the settings cannot be used together.
500publish_failedThe tour could not be published; what was published before is unchanged.

Limits

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.