Base URL and authentication
The production extension uses https://livescratchapi.waakul.com/apiv2. Socket.IO uses /apiv2/socket.io. A custom-server setting takes an origin; the extension constructs its API base. Source routes are the authoritative contract for compatible clients.
Protected HTTP calls use the authorization header containing the CoBlocks token. Some routes also take uname in a header, path, or request body. These are not interchangeable; follow the specific handler. Do not embed tokens in URLs.
Typical failures include 401 for rejected authentication, 403 for denied project/owner access, 404 for missing records, and 429 for rate limiting. Error bodies vary by route (for example noauth, noaccess, or err); callers must inspect HTTP status and body.
Authentication routes
| Route under /apiv2 | Purpose |
|---|---|
| POST /auth/scratch/start | Begins a short-lived login and returns a state and provider URL. |
| GET /auth/scratch/callback | Receives and verifies the Scratch Auth provider callback. |
| GET /auth/scratch/complete | Completes the browser-to-extension handoff. |
| POST /auth/scratch/finish | Exchanges completed handoff state for a backend login. |
| POST /auth/session | Validates a token against the stated Scratch username. |
| POST /auth/logout | Invalidates a CoBlocks session. |
Project and sync routes
| Route | Purpose |
|---|---|
| POST /newProject/:scratchId/:owner | Creates a collaboration from a Scratch project snapshot. |
| GET /lsId/:scratchId/:uname | Resolves a Scratch copy to a collaboration. |
| PUT /linkScratch/:scratchId/:lsId/:owner | Links a Scratch copy to a collaboration, with conflict checks. |
| GET /projectJSON/:lsId | Fetches a project snapshot for an authorized user. |
| POST /projectSavedJSON/:lsId/:version | Persists a saved snapshot/version. |
| GET /changesSince/:id/:version | Retrieves changes after a known version. |
| GET /active/:lsId | Lists active project participants. |
| GET /userProjectsScratch/:user | Lists eligible project cards and Scratch links. |
| PUT /leaveScratchId/:scratchId/:username or /leaveLSId/:lsId/:username | Leaves or unlinks membership via the indicated identifier. |
Access, invites, and friends
| Route | Purpose |
|---|---|
| GET /share/:id | Reads project membership. |
| PUT /share/:id/:to/:from | Owner adds a collaborator. |
| PUT /unshare/:id/:to | Owner removes a collaborator. |
| POST /invite/:id | Owner creates/replaces the seven-day invite. |
| DELETE /invite/:id | Owner revokes the current invite. |
| POST /invite/:id/accept | Authenticated user submits a token to gain membership. |
| GET /friends/:user; POST /friends/:user/:friend; DELETE /friends/:user/:friend | Read, add, and remove CoBlocks friend entries. |
| GET /privateMe/:username; PUT /privateMe/:username/:private | Read/update the public usage-badge privacy preference. |
| GET /userExists/:username | Reports public CoBlocks usage subject to privacy settings. |
Chat and backpack
| Route | Purpose |
|---|---|
| GET /chat/:id | Loads authorized project chat history. |
| GET /backpack/:id | Reads project scripts. |
| POST /backpack/:id | Validates and stores a script item. |
| DELETE /backpack/:id/:itemId | Owner or item creator removes a script. |
Live message families
The Socket.IO connection receives message envelopes dispatched by meta. Implemented handlers include joinSession, joinSessions, leaveSession, projectChange, setTitle, setCursor, pointer, and chat.
Live edit/chat/pointer operations require project access and a joined identity. The pointer path accepts Code-workspace coordinates and target identity; it is not a generic page-coordinate broadcast.
Lookup and operator routes
Admin routes are operator endpoints, not public user settings or a versioned third-party SDK. The ADMIN_USER environment value configures HTTP Basic Auth. The ADMIN username list separately enables privileged in-chat broadcast handling. Review those handlers and restrict operator access before exposing a custom service.
| Route | Purpose / access |
|---|---|
| GET / | API service response. |
| GET /scratchIdInfo/:scratchId | Reads a Scratch-copy mapping subject to the handler’s project access checks. |
| GET /projectTitle/:id | Reads the collaboration’s project title. |
| GET /userRedirect/:scratchId/:username | Determines which linked copy to open or whether to create one. |
| GET /userProjects/:user | Lists eligible shared collaboration IDs. |
| POST /auth/scratch/ack | Acknowledges an issued login token and clears the pending handoff. |
| GET /dau/:days | Aggregate recent-usage count; days must be greater than zero and at most 365. |
| GET /stats | HTTP Basic Auth protected operator statistics. |
| GET /banned; PUT /ban/:username; PUT /unban/:username | HTTP Basic Auth protected moderation endpoints. |
| GET /html/* | Static backend HTML resources. |