Introduction

Welcome to the Bitpaper API!

The following guide explains how you can create and manage papers programmatically using a REST API and how to integrate Bitpaper in your website.

You can view code examples alongside each section.

You can get full access to the REST API by subscribing to the ‘Enterprise/API’ plan on the Pricing page.

Usage

The Bitpaper API is organized around REST.

It uses predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses and uses standard HTTP response codes, authentication and verbs.

All requests must be made via HTTPS.
Requests which require a request body use JSON, so they must include a Content-Type: application/json header.

API versioning follows Semantic Versioning.

Rate Limiting

The Bitpaper API employs a rate limiter to guard against bursts of incoming traffic and maximise stability. Users who send too many requests in quick succession may see 429 error responses.

All requests are limited to 600 requests per hour.

Authentication

# An example of an authorized API call curl "<api-endpoint-here>" \ -H "Authorization: Bearer <my-secret-api-token>"

Replace <my-secret-api-token> with your actual API token.

Bitpaper uses API tokens to allow access to the API.

You can view your API token in your Bitpaper account.

Include your API token in all requests as a header:

Authorization: Bearer <my-secret-api-token>

Test Mode

The API allows simulating requests using your test API token so you can test without incurring paper creation charges.

Bitpaper provides 2 API tokens, found here:

Production API token — Creates functioning papers and charges them to your account. Use this in production.
Test API token — Creates non-functioning papers which are not charged. Use this for testing.

Papers

Papers are the primary resource in Bitpaper.

A Paper is a collaborative whiteboard instance accessible via a unique and permanent URL.

Creating a paper programmatically returns URLs that users can visit to join and collaborate on a whiteboard.

A paper can have up to 100 individual pages. Pages can be created and switched using the page toolbar on the top-right.

API Papers

By default, API-created papers have the full set of whiteboard tools including audio/video calls and screensharing.

You can control access to paid call features using the Calls toggle in your Call Settings.

API-created papers do not display any Bitpaper branding.

To mask the URL, follow the Whitelabelling guide below.

Create a Paper

curl "https://api.bitpaper.io/public/api/v1/paper" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <my-secret-api-token>" \ --data '{"name":"Maths"}'

Returns JSON structured like this:

{ "id_saved_paper": "ddc95912-2a81-a25e-b589-8de1d472f6e8", "name": "Maths", "created_at": "2021-01-01T01:00:00.000Z", "is_test_paper": false, "urls": { "admin": "https://bitpaper.io/go/Maths/xdXfoI?access-token=eyJhbGciO", "guest": "https://bitpaper.io/go/Maths/xdXfoI?access-token=iJIUzI9.e" } }

Creates a paper and returns the paper information and URLs which can be used to access it.

Visiting any of the URLs in the response takes you directly to the created paper.

HTTP Request

POST https://api.bitpaper.io/public/api/v1/paper

Body Parameters

Parameter	Type	Description
`name`	`String` (URL-safe, 4–64 chars)	A name for the paper. Does not have to be unique.

Response

Responds with HTTP 201 if successful.

Parameter	Description
`id_saved_paper`	`String` (36 chars) — Unique paper identifier
`name`	`String` (URL-safe, 4–64 chars)
`is_test_paper`	`Boolean` — `true` if created with test token
`created_at`	`String` — ISO 8601 timestamp
`urls`	`Object` — Access URLs for the paper
`urls.admin`	`String` — Administrator access URL
`urls.guest`	`String` — Guest access URL

id_saved_paper is a randomly-generated, unique and permanent identifier. You can safely store this in your system to match a paper to a user or class.

Access a Paper

Created papers contain 2 URLs:

Administrator URL — full whiteboard privileges.
Guest URL — restricted whiteboard privileges.

A paper can have more than one administrator or guest. Redirecting 2 users via urls.admin or urls.guest gives both the same privileges.

Give names to your users

Papers display user names in features like chat. To assign a name, append a user_name query parameter:

https://bitpaper.io/go/Hello%20World/xdXfoI?access-token=foo&user_name=John%20Doe

Get a Paper

curl "https://api.bitpaper.io/public/api/v1/paper/ddc95912-2a81-a25e-b589-8de1d472f6e8" \ -H "Authorization: Bearer <my-secret-api-token>"

Returns JSON structured like this:

{ "id_saved_paper": "ddc95912-2a81-a25e-b589-8de1d472f6e8", "name": "Maths", "status": "active", "created_at": "2021-01-01T01:00:00.000Z", "is_test_paper": false }

Retrieves information about a specific paper, including its current status.

HTTP Request

GET https://api.bitpaper.io/public/api/v1/paper/<id_saved_paper>

URL Parameters

Parameter	Description
`id_saved_paper`	`String` (UUID) — The paper identifier

Response

Responds with HTTP 200 if successful.

Parameter	Description
`id_saved_paper`	`String` (36 chars) — Unique paper identifier
`name`	`String` — Paper name
`status`	`String` — `active`, `INFLIGHT`, or `FAILED`
`is_test_paper`	`Boolean` — `true` if created with test token
`created_at`	`String` — ISO 8601 timestamp

Duplicate a Paper

curl "https://api.bitpaper.io/public/api/v1/paper/ddc95912-2a81-a25e-b589-8de1d472f6e8/copy" \ -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <my-secret-api-token>" \ --data '{"name":"Maths (copy)"}'

Returns JSON structured like this:

{ "id_saved_paper": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Maths (copy)", "status": "INFLIGHT", "created_at": "2021-06-15T09:30:00.000Z", "is_test_paper": false }

Duplicates an existing paper, including all content. This is a fire-and-forget operation — the response returns immediately while the copy runs in the background.

The new paper is returned with status set to INFLIGHT. Poll Get a Paper with the new id_saved_paper until status resolves to active or FAILED.

HTTP Request

POST https://api.bitpaper.io/public/api/v1/paper/<id_saved_paper>/copy

URL Parameters

Parameter	Description
`id_saved_paper`	`String` (UUID) — The paper to duplicate

Body Parameters

Parameter	Type	Description
`name`	`String` (4–64 chars)	A name for the duplicate paper.

Response

Responds with HTTP 201 if successful.

Parameter	Description
`id_saved_paper`	`String` (36 chars) — Unique identifier of the new paper
`name`	`String` — Name of the duplicate
`status`	`String` — Initially `INFLIGHT`
`is_test_paper`	`Boolean` — `true` if created with test token
`created_at`	`String` — ISO 8601 timestamp

Delete a Paper

curl "https://api.bitpaper.io/public/api/v1/paper/ddc95912-2a81-a25e-b589-8de1d472f6e8" \ -X DELETE \ -H "Authorization: Bearer <my-secret-api-token>"

Responds with HTTP 204 if successful.

Deletes a specific paper. The content is permanently deleted and the URL becomes permanently inaccessible.

HTTP Request

DELETE https://api.bitpaper.io/public/api/v1/paper/<id_saved_paper>

URL Parameters

Parameter	Description
`id_saved_paper`	`String` — The paper identifier to delete

Response

Responds with HTTP 204 if successful.

Whitelabelling

Bitpaper allows embedding the whiteboard in your website, under your own domain and without any Bitpaper branding.

This creates a seamless experience for your users without any hints of using an external whiteboard.

Use your own domain

<iframe src="https://bitpaper.io/go/Maths/xdXfoI?access-token=eyJhbGciO&user_name=John%20Doe" allow="camera; microphone; display-capture; clipboard-read; clipboard-write;" style=" position: fixed; top: 0px; bottom: 0px; right: 0px; width: 100%; border: none; margin: 0; padding: 0; overflow: hidden; z-index: 999999; height: 100%; "> </iframe>

Bitpaper can be embedded into your website using an <iframe>. This displays papers to your users in a webpage rendered on your own domain.

The src of the iframe can be set to either of the URLs returned when creating a paper.

Status Codes

The Bitpaper API uses the following HTTP status codes:

Code	Meaning
200	OK — Request succeeded with response data.
201	Created — Resource created successfully.
204	No Content — Request succeeded, no response data.
400	Bad Request — Request has validation errors.
401	Unauthorized — Invalid or revoked API token.
403	Forbidden — Subscription inactive or insufficient privileges.
404	Not Found — Entity not found.
405	Method Not Allowed — Invalid method for this endpoint.
406	Not Acceptable — Requested a non-JSON format.
410	Gone — Entity permanently removed.
429	Too Many Requests — Rate limit exceeded.
500	Internal Server Error — Server problem. Try again later.
503	Service Unavailable — Maintenance. Check Bitpaper Status.

Changelog

v1.1.0

March 23, 2026

Added Get a Paper endpoint
Added Duplicate a Paper endpoint

v1.0.0

August 20, 2021

Initial release