Public API

December 15, 2023 · View on GitHub

This API provides a way to programmatically import data into the p5.js Web Editor.

Authentication

Access to the API is available via a Personal Access Token, linked to an existing editor user account. Tokens can be created and deleted via the logged-in user’s Settings page.

When contacting the API, the username and token must be sent with every request using basic auth.

This involved sending the base64 encoded ${username}:${personalAccessToken} in the Authorization header. For example: Authorization: Basic cDU6YWJjMTIzYWJj

API Access

  • All requests send and receive Content-Type: application/json unless otherwise stated

Versioning

The API is versioned and this version is indicated in the root URL path e.g. version 1 of the API can be found at http://editor.p5js.org/api/v1.

You must provide the version number when accessing the API.

VersionRelease date
v1Unreleased

Models

The API accepts and returns the following model objects, as JSON.

Enabling Access Token UI in Settings Page

To enable the Access Token UI in the Settings page, follow these steps:

  1. Navigate to the .env file in your project.
  2. Locate the line specifying UI_ACCESS_TOKEN_ENABLED.
  3. Set the value to true, as shown below:
UI_ACCESS_TOKEN_ENABLED=true

Sketch

NameTypeDescription
nameStringThe sketch’s title
filesDirectoryContentsThe files and directories in this sketch. See DirectoryContents for the structure.
slugStringA path that can be used to access the sketch
{
  "id": String, // opaque ID
  "name: String,
  "files": DirectoryContents,
  "slug": String // optional
}

Validations

  • files must have exactly one top-level file with the .html extension. If none is provided, then a default index.html and associated style.css will be automatically created.
  • slug must be an URL-safe string
  • slug must be unique across all user's sketches

DirectoryContents

A map of filenames to File or Directory. The key of each item is used as the filename. Using a map ensures that filenames are unique in the directory.

{
  [String]:  File | Directory
}


{
  "sketch.js": { "content": "var answer = 42;" },
  "index.html" { "content": "..." }
}

DirectFile

This file is editable in the Editor UI and stored in the Editor's database.

NameTypeDescription
contentUTF-8 StringThe contents of the file as a UTF-8 string
{
  "content": String
}

ReferencedFile

This file is hosted elsewhere on the Internet. It appears in the Editor's listing and can be referenced using a proxy URL in the Editor.

NameTypeDescription
urlURLA valid URL pointing to a file hosted elsewhere
{
  "url": URL
}

File

A File is either a DirectFile or ReferencedFile. The API supports both everywhere.

Directory

NameTypeDescription
filesDirectoryContentsA map of the directory contents
{
  "files": DirectoryContents
}

API endpoints

Sketches

GET /:user/sketches

List a user’s sketches.

This will not return the files within the sketch, just the sketch metadata.

Request format

No body.

Response format

{
  "sketches": Array<Sketch>
}

Example

GET /p5/sketches

{
  "sketches": [
    { "id": "H1PLJg8_", "name": "My Lovely Sketch" },
    { "id": "Bkhf0APpg", "name":  "My Lovely Sketch 2" }
  ]
}

POST /:user/sketches

Create a new sketch.

A sketch must contain at least one file with the .html extension. If none is provided in the payload, a default index.html and linked style.css file will be created automatically.

Request format

See Sketch in Models above.

Response format

{
  "id": String
}

Example

POST /p5/sketches

{
  "name": "My Lovely Sketch",
  "files": {
    "index.html": { "content": "<DOCTYPE html!><body>Hello!</body></html>" },
    "sketch.js": { "content": "var useless = true;" }
  }
}

files can be nested to represent a folder structure. For example, this will create an empty “data” directory in the sketch:

POST /p5/sketches

{
  "name": "My Lovely Sketch 2",
  "files": [
    {
       "name": "assets",
       "type": "",
       "files": {
        "index.html": { "content": "<DOCTYPE html!><body>Hello!</body></html>" },
        "data": {
          "files": {}
        }
      }
   }
}

Responses

HTTP codeBody
201 Createdid of sketch
422 Unprocessable Entityfile validation failed, unsupported filetype, slug already exists

Examples

201 CREATED

{
  "id": "Ckhf0APpg"
}

DELETE /:user/sketches/:id

Delete a sketch and all its associated files.

Request format

No body

Response format

No body

Example

DELETE /p5/sketches/Ckhf0APpg

Responses

HTTP codeDescription
200 OKSketch has been deleted
404 Not FoundSketch does not exist