DocsConnect

API reference

JSON over HTTPS. Every endpoint is also an MCP tool and an SDK method, shown beside it. Hover a parameter to find it in the code.

Base URL
https://scaffold.llc
Auth
Authorization: Bearer scf_live_…Tokens

Account

Link to Retrieve your accountRetrieve your account

GET/v1/account

Show the person you act for: name, email, signup time, how they sign in, the request's console session and any pending deletion. An ended console session answers 401 with why in the error's details.

Alsoaccount_get in account_readscaffold.account.get()Read

Returns

Your account, with how you sign in and any pending deletion.

Images

Link to Retrieve an imageRetrieve an image

GET/v1/images/{image_id}

Read a logo or avatar by the image id ending its URL.

Alsoimage_get in account_readscaffold.image.get()Read

Path parameters

image_idstringrequired

Returns

The image as a base64 PNG.

Errors

404not_foundNo logo or avatar you can see has that id.

Workspaces

Link to Create a workspaceCreate a workspace

POST/v1/workspaces

Create a workspace on Free with you as its owner, named 1 to 80 characters and unlike your other workspaces. Each person owns one Free workspace: while you own one, upgrade it before creating another. Your first workspace gets your 50 starter credits once your email is verified.

Alsoworkspace_create in workspace_irreversiblescaffold.workspace.create()WriteAgents ask first

Body parameters

namestringrequired

Returns

The new workspace.

Errors

422validation_failedThe name is blank, over 80 characters or has no letter or digit.
409conflictYou already have a workspace with that name, or a deleted one still holds it.
403plan_requiredYou own a Free workspace already, which details.workspace_id names: upgrade it first.

Link to Rename a workspaceRename a workspace

POST/v1/workspaces/{workspace_id}/rename

Rename a workspace you own. Its slug stays the same.

Alsoworkspace_rename in workspace_writescaffold.workspace.rename()Write

Path parameters

workspace_idstringrequired

Body parameters

namestringrequired

Returns

The renamed workspace.

Errors

422validation_failedThe name is blank or over 80 characters.
403forbiddenYou are not an owner of the workspace.

Link to Set a workspace logoSet a workspace logo

POST/v1/workspaces/{workspace_id}/logo

Set or clear the logo of a workspace you own.

Alsoworkspace_logo_set in workspace_writescaffold.workspace.logo_set()Write

Path parameters

workspace_idstringrequired

Body parameters

imagestring

A new image. Omit it, and restore_image_id, to show none.

restore_image_idstring

Instead of image, an earlier set's previous_image_id, to undo it.

Returns

The workspace with its new logo, and the id of the image it replaced.

Errors

422validation_failedThe image is not an intact PNG, JPEG, GIF or WebP, is too large, or comes with restore_image_id.
403forbiddenYou are not an owner of the workspace.
404not_foundrestore_image_id is not the logo shown just before.

Link to Delete a workspaceDelete a workspace

DELETE/v1/workspaces/{workspace_id}

Delete a workspace you own, unless a paid plan renews.

Alsoworkspace_delete in workspace_writescaffold.workspace.delete()Write

Path parameters

workspace_idstringrequired

Returns

The workspace's id and when it is erased.

Errors

403forbiddenYou are not an owner of the workspace.
409conflictA paid plan renews: cancel it first.
502upstreamStripe failed. Try again.

Link to Restore a workspaceRestore a workspace

POST/v1/workspaces/{workspace_id}/restore

Undo workspace.delete within 24 hours. A Free one waits while you own another Free workspace, as each person owns one.

Alsoworkspace_restore in workspace_writescaffold.workspace.restore()Write

Path parameters

workspace_idstringrequired

Returns

The restored workspace.

Errors

403forbiddenYou are not its owner, or it was erased.
404not_foundThe workspace is not deleted, or its 24 hours to restore have passed.
403plan_requiredIt is on Free and you own another Free workspace, which details.workspace_id names: upgrade or delete that one first.

Link to Export a workspaceExport a workspace

POST/v1/workspaces/{workspace_id}/exports

Zip a workspace you own. workspace.export_get shows its progress and workspace.export_download returns the zip once it is ready.

Alsoworkspace_export_start in workspace_irreversiblescaffold.workspace.export_start()WriteAgents ask first

Path parameters

workspace_idstringrequired

Returns

The export, being prepared.

Errors

403forbiddenYou are not an owner of the workspace.
409conflictAn export of the workspace is still being prepared.

Link to Retrieve an exportRetrieve an export

GET/v1/workspaces/{workspace_id}/export

An export's progress; the latest by default.

Alsoworkspace_export_get in workspace_readscaffold.workspace.export_get()Read

Path parameters

workspace_idstringrequired

Query parameters

export_idstring

The workspace's latest export when omitted.

Returns

The export with its status and progress.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe workspace has no export with that id, or none yet.

Link to Download an exportDownload an export

GET/v1/workspaces/{workspace_id}/exports/{export_id}/download

A ready export's zip, as base64. Needs write access, since it holds every project's database.

Alsoworkspace_export_download in workspace_readscaffold.workspace.export_download()Read

Path parameters

export_idstringrequired
workspace_idstringrequired

Returns

The export's zip as base64, with its file name.

Errors

403forbiddenYou are not an owner of the workspace, or the token is read-only.
404not_foundThe workspace has no export with that id, or none yet.
409conflictThe export is not ready, failed or expired.

Link to List workspacesList workspaces

GET/v1/workspaces

List your workspaces and your role in each.

Alsoworkspace_list in workspace_readscaffold.workspace.list()Read

Query parameters

deletedboolean

List instead the deleted workspaces you own that can still be restored.

Returns

Your workspaces, each with your role.

Link to Invite a memberInvite a member

POST/v1/workspaces/{workspace_id}/invites

Invite an email to a workspace you own. Pass on the invite link secret it answers, shown only once.

Alsoworkspace_member_invite in workspace_irreversiblescaffold.workspace.member_invite()WriteAgents ask first

Path parameters

workspace_idstringrequired

Body parameters

emailstringrequired

Only the account with this email can accept.

Returns

The invite and its link secret, shown only once.

Errors

422validation_failedThe email does not look like [email protected].
403forbiddenYou are not an owner of the workspace.
403plan_requiredTeam members need the Paid plan.
409conflictThe email is already a member or has an open invite.
409secret_shownA retry under the same Idempotency-Key, whose secret was already shown.

Link to Revoke an inviteRevoke an invite

DELETE/v1/invites/{invite_id}

Revoke an open invite to a workspace you own, by its id from workspace.member_list.

Alsoworkspace_invite_revoke in workspace_writescaffold.workspace.invite_revoke()Write

Path parameters

invite_idstringrequired

Returns

The invite's id and when it was revoked.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundNo invite you can see has that id.
409conflictThe invite was already accepted, revoked or expired.

Link to Restore an inviteRestore an invite

POST/v1/invites/{invite_id}/restore

Undo a revoke before the invite expires.

Alsoworkspace_invite_restore in workspace_writescaffold.workspace.invite_restore()Write

Path parameters

invite_idstringrequired

Returns

The invite's id and when it now expires.

Errors

403forbiddenYou are not an owner of the workspace.
403plan_requiredTeam members need the Paid plan.
404not_foundNo invite you can see has that id.
409conflictThe invite is not revoked, expired or was replaced.

Link to Dismiss a declined inviteDismiss a declined invite

POST/v1/invites/{invite_id}/dismiss

Hide a declined invite that workspace.member_list shows.

Alsoworkspace_invite_dismiss in workspace_irreversiblescaffold.workspace.invite_dismiss()WriteAgents ask first

Path parameters

invite_idstringrequired

Returns

The invite's id and when it was dismissed.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundNo invite you can see has that id.
409conflictThe invite was not declined, or is already dismissed.

Link to Accept an inviteAccept an invite

POST/v1/invites/accept

Join a workspace by an invite sent to your account's email.

Alsoworkspace_invite_accept in workspace_writescaffold.workspace.invite_accept()Write

Body parameters

secretstringrequired

The secret from the invite link.

Returns

The workspace you joined, with your role.

Errors

403forbiddenThe invite is for another email, or you have not proven you read it.
404not_foundNo open invite has that secret.
409conflictYou are already a member.

Link to Decline an inviteDecline an invite

POST/v1/invites/decline

Turn down an invite sent to your account's email, by its secret.

Alsoworkspace_invite_decline in workspace_irreversiblescaffold.workspace.invite_decline()WriteAgents ask first

Body parameters

secretstringrequired

The secret from the invite link.

Returns

The invite's id and when you declined it.

Errors

403forbiddenThe invite is for another email, or you have not proven you read it.
404not_foundNo open invite has that secret.

Link to Retrieve an inviteRetrieve an invite

POST/v1/invites/preview

Show an invite from its link secret, signed in or not, and whether it is still open.

Alsoworkspace_invite_get in workspace_readscaffold.workspace.invite_get()Read

Body parameters

secretstringrequired

The secret from the invite link.

Returns

The invite's workspace, sender, role and whether it is still open.

Errors

404not_foundNo invite has that secret.

Link to List membersList members

GET/v1/workspaces/{workspace_id}/members

List a workspace's members with roles, avatars and last activity, and its open invites.

Alsoworkspace_member_list in workspace_readscaffold.workspace.member_list()Read

Path parameters

workspace_idstringrequired

Returns

The members with their roles, and the open, declined and expired invites.

Link to Transfer ownershipTransfer ownership

POST/v1/workspaces/{workspace_id}/transfer-ownership

Make a member the owner of a workspace you own. The plan stops using your card and billing details; the new owner adds theirs in the billing portal.

Alsoworkspace_ownership_transfer in workspace_irreversiblescaffold.workspace.ownership_transfer()WriteAgents ask first

Path parameters

workspace_idstringrequired

Body parameters

person_idstringrequired

A member who becomes the owner; you become a member.

Returns

The workspace's new and previous owner.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe person is not a member of the workspace.
409conflictThe person already owns it or is deleting their account.

Link to Remove a memberRemove a member

DELETE/v1/workspaces/{workspace_id}/members/{person_id}

Remove a member from a workspace you own, or leave one with your own person_id. Revokes their tokens there.

Alsoworkspace_member_remove in workspace_irreversiblescaffold.workspace.member_remove()WriteAgents ask first

Path parameters

person_idstringrequired

Your own id to leave the workspace.

workspace_idstringrequired

Returns

Who was removed, and when.

Errors

403forbiddenYou remove someone else and are not an owner.
404not_foundThe person is not a member of the workspace.
409conflictIt would leave the workspace without an owner.

Projects

Link to Create a projectCreate a project

POST/v1/projects

Create a project in a workspace. Refused while a deleted one with the slug can be restored, unless ignore_restorable. A Free workspace holds 2 projects; server templates need the Paid plan.

Alsoproject_create in project_writescaffold.project.create()Write

Body parameters

namestringrequired
workspace_idstringrequired
ignore_restorableboolean

Create it even while a deleted one with this slug can be restored.

regionstring

Where it runs. eu-central when omitted.

One of eu-central

templatestring

What the project starts from. empty when omitted.

One of node, python, static, booking, empty

Returns

The new project.

Errors

422validation_failedThe name is blank, over 80 characters, has no letter or digit, or contains Scaffold.
403plan_requiredServer templates need the Paid plan, and a Free workspace holds 2 projects.
409conflictThe name is taken in the workspace.
409restorable_projectA deleted project still holds the name.

Link to List projectsList projects

GET/v1/projects

List a workspace's projects, leaving out deleted ones.

Alsoproject_list in project_readscaffold.project.list()Read

Query parameters

workspace_idstringrequired
limitinteger

1 to 100, 20 when omitted.

starting_afterstring

Returns

A page of the workspace's live projects with has_more and next_cursor.

Link to Retrieve a projectRetrieve a project

GET/v1/projects/{project_id}

Show a live project with its runtime, its newest deploy and, while Scaffold has it suspended, why and the statement of reasons to appeal.

Alsoproject_get in project_readscaffold.project.get()Read

Path parameters

project_idstringrequired

Returns

The project, what its app runs on, its newest deploy and any suspension.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo live project you can see has that id or slug.

Link to Retrieve a project's metricsRetrieve a project's metrics

GET/v1/projects/{project_id}/metrics

Show a project's app users over 30 days and its costs this month: the credits of runs started for it, the hours its apps ran and what it stores.

Alsoproject_metrics_get in project_readscaffold.project.metrics_get()Read

Path parameters

project_idstringrequired

Returns

The app's users, signups and daily active users over the last 30 days, and this month's credits and agent runs of the runs started for the project, the seconds its apps ran and the bytes it stores, with what the plan includes.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Check a project addressCheck a project address

GET/v1/projects/address-check

Show the address a new project with this name would get and whether it is free. If not, project.create adds 4 random characters.

Alsoproject_address_check in project_readscaffold.project.address_check()Read

Query parameters

namestringrequired

The project name you would create, as project.create takes it.

Returns

The address a project of that name would get, and whether it is free.

Errors

422validation_failedThe name is blank, over 80 characters, contains Scaffold or cannot become an address.

Link to Delete a projectDelete a project

DELETE/v1/projects/{project_id}

Owner only: delete a project after a 24 hour grace period.

Alsoproject_delete in project_writescaffold.project.delete()Write

Path parameters

project_idstringrequired

Returns

The project's id and when it is erased.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403forbiddenYou are not an owner of the project's workspace.
404not_foundNo project you can see has that id or slug.

Link to Restore a projectRestore a project

POST/v1/projects/{project_id}/restore

Owner only: restore a deleted project within 24 hours of deleting it, unless its Free workspace holds its 2 projects already.

Alsoproject_restore in project_writescaffold.project.restore()Write

Path parameters

project_idstringrequired

Returns

The restored project.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403forbiddenYou are not an owner of the project's workspace.
404not_foundNo deleted project you can see has that id or slug.
403plan_requiredA Free workspace holds 2 projects, and it has them.
409conflictA live project took the slug.

Link to Erase a deleted projectErase a deleted project

POST/v1/projects/{project_id}/erase

Owner only: erase a deleted project now instead of when its 24 hours run out, with its deploys, env, domains and database.

Alsoproject_erase in project_irreversiblescaffold.project.erase()WriteAgents ask first

Path parameters

project_idstringrequired

Returns

The project's id and when it was erased.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403forbiddenYou are not an owner of the project's workspace.
404not_foundNo deleted project you can see has that id or slug.

Link to Retrieve a project's healthRetrieve a project's health

GET/v1/projects/{project_id}/health

Show a project's requests, errors, p95 latency, unavailable requests and downtime per hour over the last 24 hours, all its deploys together.

Alsoproject_health_get in project_readscaffold.project.health_get()Read

Path parameters

project_idstringrequired

Returns

The last 24 hours, oldest first, with their totals, the latest outage and the requests of the day before. The tenant host counts in memory, so its counts start again when it restarts.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
502upstreamThe project's tenant host did not answer. Try again.

Link to Retrieve a project's statusRetrieve a project's status

GET/v1/projects/{project_id}/status

Show whether each deploy a project's host keeps is awake, asleep or exited, with its wakes, sleeps, OOM kills and CPU.

Alsoproject_status_get in project_readscaffold.project.status_get()Read

Path parameters

project_idstringrequired

Returns

Whether Scaffold suspended the project, and its live, starting and previous deploys as its host sees them.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
502upstreamThe project's tenant host did not answer. Try again.

Link to Retrieve a project's limitsRetrieve a project's limits

GET/v1/projects/{project_id}/limits

Show the CPU, memory, disk, processes and sleep window a project's app runs under on its plan, and what its live deploy uses now.

Alsoproject_limits_get in project_readscaffold.project.limits_get()Read

Path parameters

project_idstringrequired

Returns

The limits of the workspace's plan, and the live deploy's CPU, memory, processes and disk while it is awake.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
502upstreamThe project's tenant host did not answer. Try again.

Link to Retrieve a project's alertsRetrieve a project's alerts

GET/v1/projects/{project_id}/alerts

Show the error share that alerts a project's owners, 1, 2 or 5%, and the alert firing now with its errors since it started.

Alsoproject_alert_get in project_readscaffold.project.alert_get()Read

Path parameters

project_idstringrequired

Returns

The alert rule, the plan alerts need, and the alert firing now with the host's count of its window.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
502upstreamAn alert fires and the project's tenant host did not answer.

Link to Set a project's alertsSet a project's alerts

PUT/v1/projects/{project_id}/alerts

Set the error share over 5 minutes, 1, 2 or 5%, above which a project's owners get an email and an inbox item. Owners only, on the Paid plan.

Alsoproject_alert_set in project_writescaffold.project.alert_set()Write

Path parameters

project_idstringrequired

Body parameters

error_percentintegerrequired

One of 1, 2, 5

Returns

The project's alert rule.

Errors

422validation_failederror_percent is not 1, 2 or 5.
404not_foundNo project you can see has that id or slug.
403forbiddenYou are not an owner of the workspace.
403plan_requiredAlerts need the Paid plan.

Link to Set maintenance modeSet maintenance mode

PUT/v1/projects/{project_id}/maintenance

Turn a project's maintenance mode on or off, as its owner. While on, its address and domains show a maintenance page and its deploys keep running on their own addresses.

Alsoproject_maintenance_set in project_writescaffold.project.maintenance_set()Write

Path parameters

project_idstringrequired

Body parameters

onbooleanrequired

True shows visitors the maintenance page; false serves the app again.

Returns

Whether the project is in maintenance, and since when.

Errors

403forbiddenYou are not an owner of the project's workspace.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.

Link to Move a projectMove a project

POST/v1/projects/{project_id}/move

Move a project to another workspace, owning both. Its deploys, domains, env, database with its backups, files, source uploads, logs, cron jobs, webhooks and app users go with it and nothing goes offline. For someone else's workspace, make a claim link. A Free workspace takes no server code and holds 2 projects and 1 custom domain.

Alsoproject_move in project_writescaffold.project.move()Write

Path parameters

project_idstringrequired

Body parameters

workspace_idstringrequired

The workspace to move it to. You own both.

Returns

The project, in its new workspace.

Errors

403forbiddenYou do not own both workspaces.
403plan_requiredIt runs server code and the other is Free, or would take the other past Free's 2 projects or 1 custom domain.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictIt is in that workspace already, a live project there has its slug, or it takes payments or deploys from GitHub: run app_payments.disconnect or github.disconnect first.

Link to Rotate app credentialsRotate app credentials

POST/v1/projects/{project_id}/credentials/rotate

Owners only: give a project's DATABASE_URL a new password and SCAFFOLD_STRIPE_WEBHOOK_SECRET a new value, so copies anyone kept stop working, and redeploy its live server app with them. Sessions opened with the old password end once a deploy with the new one is live, or within an hour. Removing a member and moving the project do this too.

Alsoproject_credentials_rotate in project_irreversiblescaffold.project.credentials_rotate()WriteAgents ask first

Path parameters

project_idstringrequired

Returns

Which credentials changed, and the redeploy that started with them.

Errors

403forbiddenYou are not an owner of the project's workspace.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.

Environment variables

Link to Set an env varSet an env var

POST/v1/projects/{project_id}/env

Set a project's env var, encrypted at rest. A live server app is redeployed with it at once, without a rebuild, unless deploy is false.

Alsoenv_set in project_writescaffold.env.set()Write

Path parameters

project_idstringrequired

Body parameters

namestringrequired

Letters, digits and underscores, not starting with a digit, like STRIPE_KEY.

valuestringrequired

At most 32 KiB.

deployboolean

False leaves the change for the next deploy. Left out, a live app is redeployed with it.

secretboolean

False shows the value in env.list; otherwise it stays a secret no command returns.

Returns

The var's name, when it was set, and the redeploy that started with it or that it waits for the next deploy.

Errors

422validation_failedThe name or value breaks a rule, or the name is one Scaffold sets.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe project already holds the most env vars it may, or its env holds a name the runtime sets.

Link to List env varsList env vars

GET/v1/projects/{project_id}/env

List a project's env vars. Secrets show their name, never their value.

Alsoenv_list in project_readscaffold.env.list()Read

Path parameters

project_idstringrequired

Returns

The project's env vars, secrets without their values.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Delete an env varDelete an env var

DELETE/v1/projects/{project_id}/env/{name}

Delete a project's env var by name. A live server app is redeployed without it, unless deploy is false; deploys made before keep their value for a rollback until the project is erased.

Alsoenv_delete in project_irreversiblescaffold.env.delete()WriteAgents ask first

Path parameters

namestringrequired
project_idstringrequired

Query parameters

deployboolean

False leaves the change for the next deploy. Left out, a live app is redeployed with it.

Returns

The var's name, when it was deleted, and the redeploy that started without it or that it waits for the next deploy.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or its env var of that name, does not exist.

Link to Restore an env varRestore an env var

POST/v1/projects/{project_id}/env/{name}/restore

Undo a var's latest env.set: put back the value it replaced, or delete the var it created. A live server app is redeployed with that, unless deploy is false.

Alsoenv_restore in project_writescaffold.env.restore()Write

Path parameters

namestringrequired
project_idstringrequired

Body parameters

deployboolean

False leaves the change for the next deploy. Left out, a live app is redeployed with it.

Returns

The var's name, whether its value is secret, and the redeploy that started with it or that it waits for the next deploy.

Errors

422validation_failedThe name is one Scaffold sets.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or an env.set of the var to undo, does not exist.
409conflictThe value put back would take the project past its env limits.

App source

Link to Upload app sourceUpload app source

PUT/v1/projects/{project_id}/sources

Upload a project's code as one zip, stored once by its hash. Only the newest 5 uploads are kept, and uploading one again makes it the newest. The app's files sit at the zip's root, not in a folder: index.html for a static site, or package.json with a start script or main file for a Node app, without node_modules.

Alsosource_upload in project_writescaffold.source.upload()Write

Path parameters

project_idstringrequired

Body parameters

archivestringrequired

Returns

The upload with its SHA-256, which deploys name it by.

Errors

422validation_failedThe archive is not a safe zip: over 50 MB, too many entries, too large unpacked, or a path or link that leaves its folder.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe same archive was deleted while it uploaded: upload it again.

Link to Delete an uploadDelete an upload

DELETE/v1/projects/{project_id}/sources/{sha256}

Delete a project's upload and its file. source.list gives each upload's sha256.

Alsosource_delete in project_irreversiblescaffold.source.delete()WriteAgents ask first

Path parameters

project_idstringrequired
sha256stringrequired

Returns

The upload's hash and when it was deleted.

Errors

403project_suspendedScaffold suspended the project.
404not_foundThe project, or its upload with that hash, does not exist.
409conflictA deploy is building the upload: wait until it is live or failed.

Link to List uploadsList uploads

GET/v1/projects/{project_id}/sources

List a project's uploads of its code, newest first. An upload's sha256 is all deploy.create needs to build it.

Alsosource_list in project_readscaffold.source.list()Read

Path parameters

project_idstringrequired

Returns

The project's uploads, newest first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to List an upload's filesList an upload's files

GET/v1/projects/{project_id}/sources/{sha256}/files

List the files in one of a project's uploads, by path. source.list or a deploy's source_sha256 gives the hash.

Alsosource_file_list in project_readscaffold.source.file_list()Read

Path parameters

project_idstringrequired
sha256stringrequired

The upload's SHA-256, as source.list or a deploy's source_sha256 gives it.

Returns

Each file's path, unpacked size and whether it is a link.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its upload with that hash, does not exist.

Link to Read an upload's fileRead an upload's file

GET/v1/projects/{project_id}/sources/{sha256}/file

Read one file of a project's upload. Text of at most 256 KB comes back whole; a binary or longer file comes back as its kind and size only.

Alsosource_file_get in project_readscaffold.source.file_get()Read

Path parameters

project_idstringrequired
sha256stringrequired

The upload's SHA-256, as source.list or a deploy's source_sha256 gives it.

Query parameters

pathstringrequired

The file's path in the upload, as source.file_list gives it.

Returns

The file's text, or that it is binary, too large or a link.

Errors

422validation_failedThe path is absolute or holds .., or the slug names projects in more than one of your workspaces.
404not_foundThe project, its upload with that hash, or the file does not exist.

GitHub

Link to List GitHub repositoriesList GitHub repositories

GET/v1/workspaces/{workspace_id}/github/repositories

List the GitHub repositories a workspace linked, which its members reach and gave Scaffold's GitHub App, for github.connect.

Alsogithub_repository_list in project_readscaffold.github.repository_list()Read

Path parameters

workspace_idstringrequired

Returns

The repositories, each with its id and default branch.

Errors

403forbiddenYou are not a member of the workspace.
501not_configuredThis Scaffold has no GitHub App set up.
502upstreamGitHub did not answer.

Link to Connect a GitHub repositoryConnect a GitHub repository

POST/v1/projects/{project_id}/github

Connect a project to a GitHub repository, so each push to its branch deploys. Replaces the repository it followed.

Alsogithub_connect in project_writescaffold.github.connect()Write

Path parameters

project_idstringrequired

Body parameters

repository_idintegerrequired

The id github.repository_list gives.

branchstring

The branch whose pushes deploy. Left out, the repository's default branch.

release_commandstring

Run before each pushed deploy goes live, after a dump of the database, as deploy.create runs its release_command. Left out, none.

Returns

The project's repository, branch and latest pushes.

Errors

422validation_failedThe branch is not a name git takes, the release command is blank or over 1,000 bytes, or the slug names projects in more than one of your workspaces.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or the repository among the workspace's linked GitHub repositories, does not exist.
501not_configuredThis Scaffold has no GitHub App set up.
502upstreamGitHub did not answer.

Link to Retrieve a project's GitHub sourceRetrieve a project's GitHub source

GET/v1/projects/{project_id}/github

Show a project's GitHub repository and branch, and its latest pushes with the deploy each started.

Alsogithub_get in project_readscaffold.github.get()Read

Path parameters

project_idstringrequired

Returns

The repository and branch, or null, and the newest 10 pushes.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Change the deployed branchChange the deployed branch

PATCH/v1/projects/{project_id}/github

Change the branch whose pushes deploy a project connected to GitHub.

Alsogithub_branch_set in project_writescaffold.github.branch_set()Write

Path parameters

project_idstringrequired

Body parameters

branchstringrequired

Returns

The project's repository, branch and latest pushes.

Errors

422validation_failedThe branch is not a name git takes.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or its GitHub connection, does not exist.

Link to Set the release commandSet the release command

PUT/v1/projects/{project_id}/github/release_command

Set the command, like a migration, that each pushed deploy of a project connected to GitHub runs before it goes live, after a dump of its database. Null for none.

Alsogithub_release_command_set in project_writescaffold.github.release_command_set()Write

Path parameters

project_idstringrequired

Body parameters

release_commandstring

Run with sh -c in each pushed deploy's sandbox, with its env and DATABASE_URL, before it goes live, like npx prisma migrate deploy. The database is dumped first. At most 1,000 bytes. Left out or null, pushed deploys run none.

Returns

The project's repository, branch, release command and latest pushes.

Errors

422validation_failedThe release command is blank or over 1,000 bytes.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or its GitHub connection, does not exist.

Link to Disconnect a GitHub repositoryDisconnect a GitHub repository

DELETE/v1/projects/{project_id}/github

Stop deploying a project from GitHub. Its uploads and deploys stay.

Alsogithub_disconnect in project_writescaffold.github.disconnect()Write

Path parameters

project_idstringrequired

Returns

The project's source, with no repository, and its latest pushes.

Errors

403project_suspendedScaffold suspended the project.
404not_foundThe project, or its GitHub connection, does not exist.

Link to Deploy from GitHubDeploy from GitHub

POST/v1/projects/{project_id}/github/deploy

Deploy the head of a connected project's branch now, as a push would. github.get shows the deploy it starts.

Alsogithub_deploy in project_writescaffold.github.deploy()Write

Path parameters

project_idstringrequired

Returns

The push, queued. Poll github.get until it deployed or failed.

Errors

403plan_requiredServer code needs the Paid plan.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or its GitHub connection, does not exist.

App databases

Link to Get the databaseGet the database

GET/v1/projects/{project_id}/database

Show a project's Postgres database: its state, version, stored size, and DATABASE_URL with the password masked.

Alsoapp_db_get in project_readscaffold.app_db.get()Read

Path parameters

project_idstringrequired

Returns

The database, or state none until the project's first deploy creates it.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
501not_configuredThis Scaffold has no customer Postgres set up.

Link to List backupsList backups

GET/v1/projects/{project_id}/database/backups

Paid plan: list a project database's backups, newest first: daily at 03:00 UTC, before each restore and before each deploy's migrations, each kept 6 days. Also its latest restore and dump.

Alsoapp_db_backup_list in project_readscaffold.app_db.backup_list()Read

Path parameters

project_idstringrequired

Returns

The backups, newest first, the latest restore with its progress, and the latest dump while it downloads.

Errors

403plan_requiredBackups need the Paid plan.
404not_foundNo project you can see has that id or slug.

Link to Restore a backupRestore a backup

POST/v1/projects/{project_id}/database/backups/{backup_id}/restore

Paid plan, owners only: put a backup in place of everything in a project's database, which is read-only from when the restore starts until it ends. Rows written since are lost, so the current data is backed up first as undo_backup_id; restoring that backup undoes this. A restore that fails leaves the database as it was.

Alsoapp_db_backup_restore in project_writescaffold.app_db.backup_restore()Write

Path parameters

backup_idstringrequired

A backup app_db.backup_list shows, of this project.

project_idstringrequired

Returns

The restore, started. app_db.backup_list shows its progress.

Errors

403plan_requiredBackups need the Paid plan.
403forbiddenYou are not an owner of the workspace.
403project_suspendedScaffold suspended the project.
404not_foundThe project has no kept backup with that id.
409conflictThe project has no database yet, or a restore of it is still running, by app_db.backup_restore or by deploy.rollback with restore_database.

Cron jobs

Link to Create a cron jobCreate a cron job

POST/v1/projects/{project_id}/cron-jobs

Paid plan: POST to a path of the project's live app on a cron schedule, waking it if asleep. Each fire runs once, signed by a Scaffold-Signature JWT the project's JWKS verifies. A project sends 2 fires at once and a workspace 8; times that pass while it waits show as one missed fire, and the newest runs.

Alsocron_create in project_writescaffold.cron.create()Write

Path parameters

project_idstringrequired

Body parameters

pathstringrequired

The app path to POST to, starting with /.

schedulestringrequired

Five cron fields, like */15 * * * * or 0 9 * * MON-FRI; every minute at most.

timezonestring

An IANA timezone, like Europe/Berlin. Left out, UTC.

Returns

The new cron job with when it fires next.

Errors

422validation_failedThe schedule is not five cron fields, the timezone is not an IANA one, or the path does not start with /.
403plan_requiredCron jobs call server code, which needs the Paid plan.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe project already has 20 cron jobs.

Link to List cron jobsList cron jobs

GET/v1/projects/{project_id}/cron-jobs

List a project's cron jobs with their next time and newest fires.

Alsocron_list in project_readscaffold.cron.list()Read

Path parameters

project_idstringrequired

Returns

The project's cron jobs, oldest first, each with its 10 newest fires.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Update a cron jobUpdate a cron job

PATCH/v1/cron-jobs/{cron_job_id}

Change a cron job's schedule, timezone or path, or pause and resume it.

Alsocron_update in project_writescaffold.cron.update()Write

Path parameters

cron_job_idstringrequired

Body parameters

enabledboolean

False pauses it, true resumes it from its next time.

pathstring
schedulestring
timezonestring

Returns

The cron job with when it fires next.

Errors

422validation_failedThe schedule is not five cron fields, the timezone is not an IANA one, or the path does not start with /.
403plan_requiredCron jobs call server code, which needs the Paid plan.
403project_suspendedScaffold suspended the project.
404not_foundNo cron job you can see has that id.

Link to Delete a cron jobDelete a cron job

DELETE/v1/cron-jobs/{cron_job_id}

Delete a cron job and its fires. It answers the job as it was.

Alsocron_delete in project_writescaffold.cron.delete()Write

Path parameters

cron_job_idstringrequired

Returns

The deleted cron job as it was.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo cron job you can see has that id.

Test runs

Link to Start a test runStart a test run

POST/v1/projects/{project_id}/test-runs

Start showing a test run of the project's code in the console, live: the command, who runs it and, when the runner knows, each test file and its test count. Report results with test_run.report as tests finish.

Alsotest_run_start in project_writescaffold.test_run.start()Write

Path parameters

project_idstringrequired

Body parameters

commandstringrequired

What runs the tests, like pnpm test.

agentstring

Who runs them, like Frontend agent.

filesobject[]

The test files and how many tests each holds, when the runner knows before they run.

pull_requeststring

What they test, like PR #214.

Returns

The run, running, with nothing reported yet.

Errors

422validation_failedThe command is empty or a file is planned twice.
402cap_reachedThe workspace stored the test runs its plan holds today: 20 MB on Free, 200 MB on Paid.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.

Link to Report test resultsReport test results

POST/v1/test-runs/{test_run_id}/results

Report tests that finished in a test run's latest attempt, up to 1,000 at once, each with its file, name, status and duration. done ends the attempt. A test reported again in the same attempt replaces its result.

Alsotest_run_report in project_writescaffold.test_run.report()Write

Path parameters

test_run_idstringrequired

Body parameters

resultsobject[]required

Tests that finished since the last report, at most 1,000.

doneboolean

True ends the attempt: every test it runs has reported.

Returns

The run with its passed and failed counts now.

Errors

422validation_failedA result has no file or name, or the run would pass 10,000 tests.
409conflictThe attempt has ended: start a rerun first.
402cap_reachedThe workspace stored the test runs its plan holds today: 20 MB on Free, 200 MB on Paid.
403project_suspendedScaffold suspended the project.
404not_foundNo test run you can see has that id.

Link to Show a test fixShow a test fix

PUT/v1/test-runs/{test_run_id}/fix

Show what you are doing to fix a test run's failures, over its graph: the test file, a short note and the files you changed with lines added and removed. Each call replaces the last.

Alsotest_run_fix in project_writescaffold.test_run.fix()Write

Path parameters

test_run_idstringrequired

Body parameters

filestringrequired

The test file whose failures it fixes.

editsobject[]

The files it changed so far.

notestring

What it is doing, like reading the failures.

Returns

The run as it stands.

Errors

422validation_failedThe run has no such test file.
409conflictThe latest attempt still runs.
403project_suspendedScaffold suspended the project.
404not_foundNo test run you can see has that id.

Link to Rerun testsRerun tests

POST/v1/test-runs/{test_run_id}/reruns

Start the next attempt of a test run once the last ended, of every file or the files named, then report it with test_run.report. A run reruns 19 times at most.

Alsotest_run_rerun in project_writescaffold.test_run.rerun()Write

Path parameters

test_run_idstringrequired

Body parameters

commandstringrequired

What runs them again, like pnpm test hero.test.tsx.

filesstring[]

The test files it runs again; left out, every file.

Returns

The run, running its new attempt.

Errors

422validation_failedThe command is empty or the run has no such test file.
409conflictThe latest attempt still runs, or the run reran 19 times.
403project_suspendedScaffold suspended the project.
404not_foundNo test run you can see has that id.

Link to List test runsList test runs

GET/v1/projects/{project_id}/test-runs

List a project's 20 newest test runs with their state and counts.

Alsotest_run_list in project_readscaffold.test_run.list()Read

Path parameters

project_idstringrequired

Returns

The project's newest test runs first, without their results.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Get a test runGet a test run

GET/v1/test-runs/{test_run_id}

Get a test run with every test's result in each attempt, the agent's fix and the files it changed.

Alsotest_run_get in project_readscaffold.test_run.get()Read

Path parameters

test_run_idstringrequired

Returns

The run with its files, tests, attempts and fix.

Errors

404not_foundNo test run you can see has that id.

Link to Delete a test runDelete a test run

DELETE/v1/test-runs/{test_run_id}

Delete a test run and every result it holds.

Alsotest_run_delete in project_irreversiblescaffold.test_run.delete()WriteAgents ask first

Path parameters

test_run_idstringrequired

Returns

The run as it was.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo test run you can see has that id.

File storage

Link to List filesList files

GET/v1/projects/{project_id}/storage

List the files a project's app stores, by name, or only those whose name starts with prefix, like avatars/.

Alsostorage_list in project_readscaffold.storage.list()Read

Path parameters

project_idstringrequired

Query parameters

limitinteger

1 to 100, 20 when omitted.

prefixstring

Only names starting with this, like avatars/.

starting_afterstring

The next_cursor of the page before.

Returns

A page of the project's files by name with has_more and next_cursor.

Errors

422validation_failedThe limit is not 1 to 100, or the slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Get storage useGet storage use

GET/v1/workspaces/{workspace_id}/storage

Show what the files of all a workspace's apps take together, and the cap its plan sets on them.

Alsostorage_usage_get in project_readscaffold.storage.usage_get()Read

Path parameters

workspace_idstringrequired

Returns

The bytes the workspace's files take as uploaded, its plan and the plan's cap: 1 GB on Free, 10 GB on Paid.

Link to Sign an upload URLSign an upload URL

POST/v1/projects/{project_id}/storage/upload-url

Sign a URL that uploads one file of up to 50 MB to a project, for 15 minutes or expires_in_seconds: PUT the bytes to it with their Content-Type, from the app's server or a user's browser. A name a file holds already is refused.

Alsostorage_upload_sign in project_writescaffold.storage.upload_sign()Write

Path parameters

project_idstringrequired

Body parameters

namestringrequired
expires_in_secondsinteger

How long the URL works, 60 seconds to 7 days. Defaults to 15 minutes.

Returns

The URL to PUT the file to, and when it expires.

Errors

422validation_failedThe name holds .., another character outside letters, digits, ., _, - and /, or expires_in_seconds is not 60 to 604800.
413storage_fullThe workspace's files are at its plan's cap: 1 GB on Free, 10 GB on Paid.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe project stores a file of that name, or one it would be a folder of.

Link to Sign a download URLSign a download URL

GET/v1/projects/{project_id}/storage/download-url

Sign a URL that downloads one of a project's files, for 15 minutes or expires_in_seconds, up to a week: link to it or put it in an img tag.

Alsostorage_download_sign in project_readscaffold.storage.download_sign()Read

Path parameters

project_idstringrequired

Query parameters

namestringrequired
expires_in_secondsinteger

How long the URL works, 60 seconds to 7 days. Defaults to 15 minutes.

Returns

The URL that answers the file, whole or one byte Range of it, and when it expires.

Errors

422validation_failedThe name breaks a rule, or expires_in_seconds is not 60 to 604800.
404not_foundThe project, or its file of that name, does not exist.

Link to Delete a fileDelete a file

DELETE/v1/projects/{project_id}/storage

Delete a project's stored file by name, so signed URLs answer not found and its bytes no longer count toward the workspace's cap.

Alsostorage_delete in project_irreversiblescaffold.storage.delete()WriteAgents ask first

Path parameters

project_idstringrequired

Query parameters

namestringrequired

Returns

The file's name, the bytes it freed and when it was deleted.

Errors

422validation_failedThe name breaks a rule.
403project_suspendedScaffold suspended the project.
404not_foundThe project, or its file of that name, does not exist.

Tokens

Link to Create a tokenCreate a token

POST/v1/tokens

Create a token for a workspace, or a test one for your sandbox. Its secret is shown once.

Alsotoken_create in account_writescaffold.token.create()Write

Body parameters

accessstringrequired

One of read, write

namestringrequired
workspace_idstringrequired
expires_atstring

RFC 3339 expiry, none if omitted, no later than the calling token's.

modestring

One of live, test

Returns

The token and its secret, shown only once.

Errors

422validation_failedThe name is blank or too long, or expires_at is past, outlives the calling token, or is over 30 days away for a test token.
403forbiddenAn OAuth app called, which cannot create personal tokens, or a test token asked for a live one.
409conflictYou already hold 100 tokens that still work, across your workspaces: revoke one first.
409secret_shownA retry under the same Idempotency-Key, whose secret was already shown.

Link to List tokensList tokens

GET/v1/tokens

List the tokens of a workspace, revoked ones included, without secrets.

Alsotoken_list in account_readscaffold.token.list()Read

Query parameters

workspace_idstringrequired

Returns

The workspace's tokens, revoked ones included, without secrets.

Link to Revoke a tokenRevoke a token

DELETE/v1/tokens/{token_id}

Revoke a token and every token it created, so their next request fails. A member may revoke only their own tokens, an owner any in the workspace.

Alsotoken_revoke in account_irreversiblescaffold.token.revoke()WriteAgents ask first

Path parameters

token_idstringrequired

Returns

The token's id and when it was revoked.

Errors

403forbiddenThe token is another member's and you are not an owner.
404not_foundNo token you can see has that id.
409conflictThe token is already revoked.

OAuth apps

Link to List OAuth appsList OAuth apps

GET/v1/oauth/grants

List the OAuth apps you approved, and as an owner every app in your workspaces.

Alsooauth_grant_list in account_readscaffold.oauth.grant_list()Read

Returns

The OAuth apps you approved, and as an owner every app in your workspaces.

Link to Revoke an OAuth appRevoke an OAuth app

DELETE/v1/oauth/grants/{grant_id}

Revoke an OAuth app you approved, or as an owner any app in your workspace, so its next request fails. oauth.grant_list gives each grant_id.

Alsooauth_grant_revoke in account_irreversiblescaffold.oauth.grant_revoke()WriteAgents ask first

Path parameters

grant_idstringrequired

Returns

The grant's id and when it was revoked.

Errors

404not_foundNo grant you can see has that id.
409conflictThe grant is already revoked.

Credits

Link to Retrieve the credit balanceRetrieve the credit balance

GET/v1/workspaces/{workspace_id}/credits

Show a workspace's credits: balance, held, available and the monthly cap.

Alsocredit_balance_get in billing_readscaffold.credit.balance_get()Read

Path parameters

workspace_idstringrequired

Returns

The balance, held and available credits, the allowance and the monthly cap.

Link to List credit entriesList credit entries

GET/v1/workspaces/{workspace_id}/credits/ledger

List a workspace's latest 200 credit entries, newest first.

Alsocredit_ledger_list in billing_readscaffold.credit.ledger_list()Read

Path parameters

workspace_idstringrequired

Returns

The latest 200 credit entries, newest first.

Link to Set the monthly capSet the monthly cap

POST/v1/workspaces/{workspace_id}/credits/cap

Set or remove a workspace's monthly spending cap. Owners only.

Alsocredit_cap_set in billing_writescaffold.credit.cap_set()Write

Path parameters

workspace_idstringrequired

Body parameters

monthly_capinteger

Millicredits the workspace may spend per calendar month (UTC). None removes the cap.

Returns

The balance with the new monthly cap.

Errors

422validation_failedmonthly_cap is negative.
403forbiddenYou are not an owner of the workspace.
403plan_requiredA monthly cap needs the Paid plan.

Link to List credit packsList credit packs

GET/v1/credits/packs

List the credit packs a top-up can buy, with their prices.

Alsocredit_pack_list in billing_readscaffold.credit.pack_list()Read

Returns

Each pack's Stripe price, credits and price, smallest first.

Errors

502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Start a top-upStart a top-up

POST/v1/workspaces/{workspace_id}/credits/top-ups

Buy the credit pack of a Stripe price with the card the plan is paid with. Owners only.

Alsocredit_top_up_start in billing_irreversiblescaffold.credit.top_up_start()WriteAgents ask first

Path parameters

workspace_idstringrequired

Body parameters

express_startbooleanrequired

Must be true: the owner ticked a box asking for the credits at once, so withdrawing refunds only the unused ones.

price_idstringrequired

The Stripe Price of a top-up pack.

Returns

The top-up, added, failed with the reason, or waiting for the bank page to confirm it on, and the balance.

Errors

422validation_failedThe price is not a top-up pack, or express_start is false.
403forbiddenYou are not an owner of the workspace.
403plan_requiredTop-ups need the Paid plan.
409conflictThe plan is not paid with a card.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Retrieve a top-upRetrieve a top-up

GET/v1/workspaces/{workspace_id}/credits/top-ups/{top_up_id}

Show whether a top-up was added, failed or still waits for the bank.

Alsocredit_top_up_get in billing_readscaffold.credit.top_up_get()Read

Path parameters

top_up_idstringrequired
workspace_idstringrequired

Returns

The top-up's credits, status and any failure reason.

Errors

404not_foundThe workspace has no such top-up.

Link to Ask for a top-upAsk for a top-up

POST/v1/workspaces/{workspace_id}/credits/top-up-requests

Ask the workspace's owners to top up, in their inbox. Members only, once a day.

Alsocredit_top_up_request in billing_irreversiblescaffold.credit.top_up_request()WriteAgents ask first

Path parameters

workspace_idstringrequired

Returns

The owners asked, by name.

Errors

409conflictYou are an owner, so you top up yourself.

Link to Withdraw from a top-upWithdraw from a top-up

POST/v1/workspaces/{workspace_id}/credits/top-ups/{top_up_id}/withdraw

Withdraw from a top-up within 14 days and refund its unused credits, once any dispute ends. Owners only.

Alsocredit_top_up_withdraw in billing_irreversiblescaffold.credit.top_up_withdraw()WriteAgents ask first

Path parameters

top_up_idstringrequired

The top-up's, as billing.get lists it.

workspace_idstringrequired

Returns

The credits the refund keeps, the refund and the new balance.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe workspace has no such top-up.
409conflictThe top-up is unpaid, withdrawn already, taken back by a refund or dispute, or past its 14 days, or its credits are all used or held by running work.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Billing

Link to Retrieve billingRetrieve billing

GET/v1/workspaces/{workspace_id}/billing

Show a workspace's plan, Free or Paid: price, card, renewal or end, a failed renewal's fix-by date, withdrawal deadlines and any unpaid payment page.

Alsobilling_get in billing_readscaffold.billing.get()Read

Path parameters

workspace_idstringrequired

Returns

The workspace's plan, card, renewal and any unpaid payment page.

Errors

502upstreamStripe failed while the plan can still be withdrawn from. Try again.

Link to Retrieve plan pricesRetrieve plan prices

GET/v1/billing/prices

Show yearly and monthly Paid plan prices before tax, the credits each grants a month (null when it grants none), and the 14-day withdrawal charge per credit.

Alsobilling_prices_get in billing_readscaffold.billing.prices_get()Read

Returns

The Paid plan's yearly and monthly prices, the credits each grants a month, and what withdrawing charges per credit.

Errors

502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Subscribe to the Paid planSubscribe to the Paid plan

POST/v1/workspaces/{workspace_id}/billing/subscribe

Open a Stripe payment page for the paid plan, yearly or monthly, which grants nothing before Stripe confirms. Owners only, on the free plan.

Alsobilling_subscribe_start in billing_writescaffold.billing.subscribe_start()Write

Path parameters

workspace_idstringrequired

Body parameters

express_startbooleanrequired

Must be true: the owner ticked a box asking for the plan at once, so withdrawing refunds less the credits used.

intervalstringrequired

One of yearly, monthly

device_idstring

A random id the browser keeps, to stop repeat withdrawals.

Returns

The Stripe payment page to pay at.

Errors

422validation_failedexpress_start is not true.
403forbiddenYou are not an owner of the workspace.
409conflictThe workspace already has a paid plan or a subscription that may still start.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Abandon a payment pageAbandon a payment page

POST/v1/workspaces/{workspace_id}/billing/subscribe/cancel

Give up on the plan's unpaid Stripe payment page, so it can no longer be paid. Owners only.

Alsobilling_subscribe_cancel in billing_irreversiblescaffold.billing.subscribe_cancel()WriteAgents ask first

Path parameters

workspace_idstringrequired

Returns

The workspace's billing.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe workspace has no payment page for the plan.
409conflictThe payment page was already paid.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Cancel the Paid planCancel the Paid plan

POST/v1/workspaces/{workspace_id}/billing/cancel

End the Paid plan when its paid period ends. Owners only.

Alsobilling_cancel in billing_writescaffold.billing.cancel()Write

Path parameters

workspace_idstringrequired

Returns

The workspace's billing, ending with its paid period.

Errors

403forbiddenYou are not an owner of the workspace.
409conflictThe workspace is on the Free plan.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Keep the Paid planKeep the Paid plan

POST/v1/workspaces/{workspace_id}/billing/resume

Keep a cancelled Paid plan, so it renews again. Owners only, before its period ends.

Alsobilling_resume in billing_writescaffold.billing.resume()Write

Path parameters

workspace_idstringrequired

Returns

The workspace's billing, renewing again.

Errors

403forbiddenYou are not an owner of the workspace.
409conflictThe workspace is on the Free plan.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Open the billing portalOpen the billing portal

POST/v1/workspaces/{workspace_id}/billing/portal

Open Stripe's billing portal to change or cancel the plan. Owners only, once the workspace subscribed.

Alsobilling_portal_open in billing_irreversiblescaffold.billing.portal_open()WriteAgents ask first

Path parameters

workspace_idstringrequired

Returns

The Stripe billing portal's address.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe workspace never subscribed.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Withdraw from the Paid planWithdraw from the Paid plan

POST/v1/workspaces/{workspace_id}/billing/withdraw

Withdraw from the paid plan within 14 days of subscribing: cancel it now and refund it, less the credits used if the owner asked to start at once, once any dispute ends. Owners only.

Alsobilling_withdraw in billing_irreversiblescaffold.billing.withdraw()WriteAgents ask first

Path parameters

workspace_idstringrequired

Returns

The refunds, and whether one waits for a dispute.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundThe workspace has no subscription.
409conflictThe 14 days to withdraw have passed, a lost dispute returned the money, or it was withdrawn already.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Changes

Link to List changesList changes

GET/v1/workspaces/{workspace_id}/changes

List what changed in a workspace, newest first, 100 at a time. Pass the last position you saw as after to catch up oldest first.

Alsochange_list in workspace_readscaffold.change.list()Read

Path parameters

workspace_idstringrequired

Query parameters

actor_idstring
afterinteger

Only newer changes, oldest first.

agent_idstring

Only the changes this agent's runs made.

areastring

One of tasks, pages, projects, agents, settings

beforeinteger

Only older changes, newest first.

client_idstring
run_idstring

Only the changes this agent run made, and the settlements of what it made.

viastring

One of console, personal_token, oauth_app, app_user, agent, no_credential, cli

Returns

The workspace's changes, newest first or after a position.

Errors

422validation_failedBoth before and after are sent.
404not_foundThe agent to filter by does not exist.

Link to Retrieve a command's changesRetrieve a command's changes

GET/v1/commands/{command_id}/changes

List the record versions one command made, before and after.

Alsochange_command_get in workspace_readscaffold.change.command_get()Read

Path parameters

command_idstringrequired

Returns

Who ran the command, how, and each record before and after.

Errors

404not_foundNo command you can see changed records with that id.

Link to Export changesExport changes

GET/v1/workspaces/{workspace_id}/changes/export

Export a workspace's changes as CSV. Owners only.

Alsochange_export in workspace_readscaffold.change.export()Read

Path parameters

workspace_idstringrequired

Query parameters

actor_idstring
agent_idstring

Only the changes this agent's runs made.

areastring

One of tasks, pages, projects, agents, settings

client_idstring
daysinteger

The last 1 to 90 days. 30 when omitted.

viastring

One of console, personal_token, oauth_app, app_user, agent, no_credential, cli

Returns

The changes as a CSV file, with row counts.

Errors

422validation_faileddays is outside the kept history.
403forbiddenYou are not an owner of the workspace, or an agent run asked.
404not_foundThe agent to filter by does not exist.

Trash

Link to List the trashList the trash

GET/v1/workspaces/{workspace_id}/trash

List what was deleted in a workspace and can still be restored.

Alsotrash_list in workspace_readscaffold.trash.list()Read

Path parameters

workspace_idstringrequired

Query parameters

beforeinteger

Only what was deleted before this position.

Returns

What was deleted in the workspace and can still be restored.

Databases

Link to Create a databaseCreate a database

POST/v1/workspaces/{workspace_id}/databases

Create a database, which keeps a Title field; add each field asked for with field.create.

Alsodatabase_create in database_writescaffold.database.create()Write

Path parameters

workspace_idstringrequired

Body parameters

namestringrequired
templatestring

One of empty, tasks, bugs

Returns

The new database with its Title field.

Errors

422validation_failedThe name is blank or over 80 characters.

Link to List databasesList databases

GET/v1/workspaces/{workspace_id}/databases

List a workspace's databases with their fields and option ids.

Alsodatabase_list in database_readscaffold.database.list()Read

Path parameters

workspace_idstringrequired

Query parameters

include_archivedboolean

List archived databases too.

Returns

The workspace's databases with their fields and options.

Link to Rename a databaseRename a database

POST/v1/databases/{database_id}/rename

Rename a database.

Alsodatabase_rename in database_writescaffold.database.rename()Write

Path parameters

database_idstringrequired

Body parameters

namestringrequired

Returns

The renamed database.

Errors

422validation_failedThe name is blank or over 80 characters.
404not_foundNo database you can see has that id.
409conflictThe database is archived.

Link to Archive a databaseArchive a database

POST/v1/databases/{database_id}/archive

Archive a database, hiding it from database.list unless include_archived. It is erased after 30 days, and relation fields lose their links to it.

Alsodatabase_archive in database_writescaffold.database.archive()WriteAgents ask first

Path parameters

database_idstringrequired

Returns

The archived database.

Errors

404not_foundNo database you can see has that id.
409conflictThe database is already archived.

Link to Restore a databaseRestore a database

POST/v1/databases/{database_id}/restore

Restore an archived database.

Alsodatabase_restore in database_writescaffold.database.restore()Write

Path parameters

database_idstringrequired

Returns

The restored database.

Errors

404not_foundNo database you can see has that id.
409conflictThe database is not archived.

Fields

Link to Create a fieldCreate a field

POST/v1/databases/{database_id}/fields

Add a typed field to a database; its kind cannot change later. A select or multi_select takes options, a relation its relation_database_id.

Alsofield_create in database_writescaffold.field.create()Write

Path parameters

database_idstringrequired

Body parameters

kindstringrequired

One of text, number, select, multi_select, person, date, relation, checkbox

namestringrequired
optionsstring[]

A select's choices, in order.

relation_database_idstring

A relation's database, which may be this one.

Returns

The new field.

Errors

422validation_failedThe name, options or relation_database_id do not fit the field's kind.
404not_foundThe database, or the one to link to, does not exist.
409conflictThe database is archived.

Link to Rename a fieldRename a field

POST/v1/fields/{field_id}/rename

Rename a field. Record values stay keyed by its id.

Alsofield_rename in database_writescaffold.field.rename()Write

Path parameters

field_idstringrequired

Body parameters

namestringrequired

Returns

The renamed field.

Errors

422validation_failedThe name is blank or over 80 characters.
404not_foundNo field you can see has that id.
409conflictThe field or its database is archived.

Link to Set a field's optionsSet a field's options

POST/v1/fields/{field_id}/options

Set a select or multi_select field's options in order: keep or rename one by id, add one without. One left out is removed, refused while any record holds it, archived ones too.

Alsofield_options_set in database_writescaffold.field.options_set()Write

Path parameters

field_idstringrequired

Body parameters

optionsobject[]required

Every option it keeps, in order.

Returns

The field with its new options.

Errors

422validation_failedThe field is not a select, or an option is unknown, listed twice or badly named.
404not_foundNo field you can see has that id.
409conflictThe field or its database is archived, or a record holds an option left out.

Link to Set a relationSet a relation

POST/v1/fields/{field_id}/relation

Set the database a relation field links to, refused while records link through it, and two_way: whether that database shows its links back.

Alsofield_relation_set in database_writescaffold.field.relation_set()Write

Path parameters

field_idstringrequired

Body parameters

relation_database_idstringrequired

May be its own.

two_waybooleanrequired

Returns

The relation field with its new link.

Errors

422validation_failedThe field is not a relation field.
404not_foundThe field, or the database to link to, does not exist.
409conflictThe field or a database is archived, records link through it, or it is still filling links.

Link to Archive a fieldArchive a field

POST/v1/fields/{field_id}/archive

Archive a field, hiding its values. Search stops finding a text field's values within moments.

Alsofield_archive in database_writescaffold.field.archive()WriteAgents ask first

Path parameters

field_idstringrequired

Returns

The archived field.

Errors

404not_foundNo field you can see has that id.
409conflictThe field is already archived or is its database's title, or the database is archived.

Link to Restore a fieldRestore a field

POST/v1/fields/{field_id}/restore

Restore an archived field and show its values again. Search finds a text field's values again within moments.

Alsofield_restore in database_writescaffold.field.restore()Write

Path parameters

field_idstringrequired

Returns

The restored field.

Errors

404not_foundNo field you can see has that id.
409conflictThe field is not archived, or its database is.

Records

Link to Create a recordCreate a record

POST/v1/databases/{database_id}/records

Add a record to a database, with values keyed by field id.

Alsorecord_create in record_writescaffold.record.create()Write

Path parameters

database_idstringrequired

Body parameters

valuesobject

Values keyed by field id, as each field's kind describes.

Returns

The new record.

Errors

422validation_failedA value does not fit its field, or links a record outside the database its field links to.
404not_foundNo database you can see has that id.
409conflictThe database is archived.

Link to Query recordsQuery records

POST/v1/databases/{database_id}/query

Filter, sort and page a database's records.

Alsorecord_query in record_readscaffold.record.query()Read

Path parameters

database_idstringrequired

Body parameters

archivedboolean

List archived records instead of live ones.

filterobject[]

Up to 20 conditions every listed record meets.

limitinteger

At most 100, 20 when omitted.

sortobject

The manual order when omitted, which also breaks ties, reversed when descending.

starting_afterstring
todaystring

Your date as YYYY-MM-DD, UTC's when omitted.

Returns

A page of matching records with has_more and next_cursor.

Errors

422validation_failedA filter or sort does not fit its field, or limit is out of range.
404not_foundThe database, or the record to continue after, does not exist.

Link to Retrieve a recordRetrieve a record

GET/v1/records/{record_id}

Show a record with its version, live field values and subtasks.

Alsorecord_get in record_readscaffold.record.get()Read

Path parameters

record_idstringrequired

Returns

The record with its version, values and subtasks.

Errors

422validation_failedThe record key is in more than one of your workspaces: send the id.
404not_foundNo record you can see has that id or key.

Link to Update a recordUpdate a record

POST/v1/records/{record_id}

Change a record's values at the version you read.

Alsorecord_update in record_writescaffold.record.update()Write

Path parameters

record_idstringrequired

Body parameters

expected_versionintegerrequired

The version you read.

valuesobjectrequired

The fields to change, keyed by field id. null empties a field; others stay as they are.

Returns

The record at its new version.

Errors

422validation_failedA value does not fit its field, or values names no field.
404not_foundNo record you can see has that id.
409conflictThe record or its database is archived.
409stale_versionThe record changed since the version you read.

Link to Set subtasksSet subtasks

POST/v1/records/{record_id}/subtasks

Replace a record's subtasks with this checklist.

Alsorecord_subtasks_set in record_writescaffold.record.subtasks_set()Write

Path parameters

record_idstringrequired

Body parameters

subtasksobject[]required

In order, up to 100.

Returns

The record with its new subtasks.

Errors

422validation_failedThere are too many subtasks, or one is blank or too long.
404not_foundNo record you can see has that id.
409conflictThe record is archived.

Link to Archive a recordArchive a record

POST/v1/records/{record_id}/archive

Archive a record at the version you read.

Alsorecord_archive in record_writescaffold.record.archive()WriteAgents ask first

Path parameters

record_idstringrequired

Body parameters

expected_versionintegerrequired

The version you read.

Returns

The archived record.

Errors

404not_foundNo record you can see has that id.
409conflictThe record is already archived, or its database is.
409stale_versionThe record changed since the version you read.

Link to Restore a recordRestore a record

POST/v1/records/{record_id}/restore

Restore an archived record at the version you read.

Alsorecord_restore in record_writescaffold.record.restore()Write

Path parameters

record_idstringrequired

Body parameters

expected_versionintegerrequired

The version you read.

Returns

The restored record.

Errors

404not_foundNo record you can see has that id.
409conflictThe record is not archived, or its database is.
409stale_versionThe record changed since the version you read.

Link to Update recordsUpdate records

POST/v1/databases/{database_id}/records/bulk-update

Change records of one database in one command, each update shaped like record.update's input.

Alsorecord_bulk_update in record_writescaffold.record.bulk_update()Write

Path parameters

database_idstringrequired

Body parameters

updatesobject[]required

1 to 200 records of the database, each once; one refused writes none.

Returns

The command's id and the records at their new versions.

Errors

422validation_failedThe list is empty, too long or names a record twice, or a value does not fit its field.
404not_foundThe database does not exist, or a record is not in it.
409conflictA record or the database is archived.

Link to Create recordsCreate records

POST/v1/databases/{database_id}/records/bulk-create

Add records to one database in one command.

Alsorecord_bulk_create in record_writescaffold.record.bulk_create()Write

Path parameters

database_idstringrequired

Body parameters

recordsobject[]required

1 to 200 records, each its values keyed by field id.

Returns

The command's id and the new records.

Errors

422validation_failedThe list is empty or too long, or a value does not fit its field.
404not_foundNo database you can see has that id.
409conflictThe database is archived.

Link to Archive recordsArchive records

POST/v1/databases/{database_id}/records/bulk-archive

Archive records of one database in one command.

Alsorecord_bulk_archive in record_writescaffold.record.bulk_archive()WriteAgents ask first

Path parameters

database_idstringrequired

Body parameters

recordsobject[]required

1 to 200 records of the database, each once.

Returns

The command's id and the archived records.

Errors

422validation_failedThe list is empty, too long or names a record twice.
404not_foundThe database does not exist, or a record is not in it.
409conflictA record is already archived, or the database is.

Link to Restore recordsRestore records

POST/v1/databases/{database_id}/records/bulk-restore

Restore archived records of one database in one command.

Alsorecord_bulk_restore in record_writescaffold.record.bulk_restore()Write

Path parameters

database_idstringrequired

Body parameters

recordsobject[]required

1 to 200 records of the database, each once.

Returns

The command's id and the restored records.

Errors

422validation_failedThe list is empty, too long or names a record twice.
404not_foundThe database does not exist, or a record is not in it.
409conflictA record is not archived, or the database is.

Link to List a record's versionsList a record's versions

GET/v1/records/{record_id}/history

List a record's versions, newest first, 100 at a time, each with who made it, its command_id and each changed field before and after.

Alsorecord_history in record_readscaffold.record.history()Read

Path parameters

record_idstringrequired

Query parameters

before_versioninteger

Only versions older than this one. Omit it for the newest 100.

Returns

The record's versions, newest first, each with what changed.

Errors

404not_foundNo record you can see has that id.

Link to Undo a commandUndo a command

POST/v1/record-commands/{command_id}/undo

Undo one command's record changes by its command_id. Refused as a conflict if any of its records changed since. Undoing an undo redoes it.

Alsorecord_undo in record_writescaffold.record.undo()Write

Path parameters

command_idstringrequired

The command_id of a record change, as the change feed, record or history shows it.

Returns

The undo's id and the records it changed back.

Errors

422validation_failedThe command changed no records this way: undo it with the command it names.
404not_foundNo command you can see changed records with that id.
409conflictA record changed since, or an option or link it would bring back is gone.

Cards

Link to Move a cardMove a card

POST/v1/records/{record_id}/move

Move a record at the version you read, like a board card, after or before another of its database, setting values in the same write. Without after or before it stays put.

Alsocard_move in record_writescaffold.card.move()Write

Path parameters

record_idstringrequired

Body parameters

expected_versionintegerrequired

The version you read.

afterstring

Place it right after this record, like the card above.

beforestring

Or right before this one, like the card below.

valuesobject

Fields to change too, like a board's column field.

Returns

The moved record at its new version.

Errors

422validation_failedBoth after and before are sent, the record moves next to itself, or a value does not fit.
404not_foundThe record, or the one to move next to, does not exist.
409conflictThe record or its database is archived.
409stale_versionThe record changed since the version you read.

Link to List your assigned recordsList your assigned records

GET/v1/workspaces/{workspace_id}/records/assigned

List a workspace's open or done records that name you in a person field, across its databases.

Alsocard_assigned_list in record_readscaffold.card.assigned_list()Read

Path parameters

workspace_idstringrequired

Query parameters

doneboolean

The done records instead.

limitinteger

At most 100, 20 when omitted.

sortstring

Omit it for the sort you last saved.

One of due, database

starting_afterstring

Returns

A page of records that name you, with next_cursor and the sort.

Errors

422validation_failedlimit or a date is out of range.
404not_foundThe record to continue after does not exist.

Tasks

Link to List tasksList tasks

GET/v1/tasks

List a workspace's tasks, newest first.

Alsotask_list in task_readscaffold.task.list()Read

Query parameters

workspace_idstringrequired
assigneestring
labelstring
limitinteger

1 to 100, 20 when omitted.

starting_afterstring
statusstring

One of todo, doing, review, done

Returns

A page of tasks with has_more and next_cursor.

Errors

422validation_failedlimit is out of range.

Link to Create a taskCreate a task

POST/v1/tasks

Add a task. New labels stay after its undo.

Alsotask_create in task_writescaffold.task.create()Write

Body parameters

titlestringrequired
workspace_idstringrequired
assigneestring
database_idstring
duestring

YYYY-MM-DD.

labelsstring[]
statusstring

One of todo, doing, review, done

Returns

The new task.

Errors

422validation_failedThe title is blank or too long, or the database holds records, not tasks.
404not_foundThe database does not exist, or the workspace has no Tasks database.
409conflictThe database, or one of its task fields, is archived.

Link to Update a taskUpdate a task

PATCH/v1/tasks/{task_id}

Change a task's title, assignee or due date; null clears one.

Alsotask_update in task_writescaffold.task.update()Write

Path parameters

task_idstringrequired

Body parameters

assigneestring
duestring
expected_versioninteger
titlestring

Returns

The updated task.

Errors

422validation_failedThe title is blank or too long.
404not_foundNo task you can see has that id.
409conflictThe task, its database or one of its task fields is archived.
409stale_versionThe task changed since the expected_version you sent.

Link to Move a taskMove a task

POST/v1/tasks/{task_id}/move

Move a task to a column, at a position in it.

Alsotask_move in task_writescaffold.task.move()Write

Path parameters

task_idstringrequired

Body parameters

columnstringrequired

One of todo, doing, review, done

positioninteger

Returns

The task in its new column.

Errors

404not_foundNo task you can see has that id.
409conflictThe task, its database or one of its task fields is archived.

Views

Link to Create a viewCreate a view

POST/v1/databases/{database_id}/views

Save a view of a database. A board needs group_by, a timeline its dates, a sprint view its sprint source.

Alsoview_create in view_writescaffold.view.create()Write

Path parameters

database_idstringrequired

Body parameters

namestringrequired
settingsobjectrequired

Returns

The new view.

Errors

422validation_failedThe name is blank or too long, or a setting does not fit the view's kind or fields.
404not_foundNo database you can see has that id.
409conflictThe database is archived.

Link to List viewsList views

GET/v1/databases/{database_id}/views

List a database's views with their settings, oldest first.

Alsoview_list in view_readscaffold.view.list()Read

Path parameters

database_idstringrequired

Query parameters

include_archivedboolean

List archived views too.

Returns

The database's views with their settings.

Errors

404not_foundNo database you can see has that id.

Link to Update a viewUpdate a view

POST/v1/views/{view_id}

Replace a view's settings; its name stays.

Alsoview_update in view_writescaffold.view.update()Write

Path parameters

view_idstringrequired

Body parameters

settingsobjectrequired

Replaces every setting; the name stays.

Returns

The view with its new settings.

Errors

422validation_failedA setting does not fit the view's kind or fields.
404not_foundNo view you can see has that id.
409conflictThe view is archived.

Link to Rename a viewRename a view

POST/v1/views/{view_id}/rename

Rename a view.

Alsoview_rename in view_writescaffold.view.rename()Write

Path parameters

view_idstringrequired

Body parameters

namestringrequired

Returns

The renamed view.

Errors

422validation_failedThe name is blank or over 80 characters.
404not_foundNo view you can see has that id.
409conflictThe view is archived.

Link to Archive a viewArchive a view

POST/v1/views/{view_id}/archive

Archive a view, hiding it from view.list unless include_archived.

Alsoview_archive in view_writescaffold.view.archive()WriteAgents ask first

Path parameters

view_idstringrequired

Returns

The archived view.

Errors

404not_foundNo view you can see has that id.
409conflictThe view is already archived.

Link to Restore a viewRestore a view

POST/v1/views/{view_id}/restore

Restore an archived view.

Alsoview_restore in view_writescaffold.view.restore()Write

Path parameters

view_idstringrequired

Returns

The restored view.

Errors

404not_foundNo view you can see has that id.
409conflictThe view is not archived.

Link to List a view's recordsList a view's records

GET/v1/views/{view_id}/records

Page a view's records as its settings show them: a board column by group, a timeline from and to, my tasks for you, or the current sprint's records with that sprint.

Alsoview_record_list in view_readscaffold.view.record_list()Read

Path parameters

view_idstringrequired

Query parameters

fromstring

A timeline's window as YYYY-MM-DD, both days included. A timeline needs both.

groupstring

One group: an id the view's group_by field holds. Omit it for every group.

limitinteger

At most 100, 20 when omitted.

starting_afterstring
tostring
todaystring

Your date as YYYY-MM-DD, UTC's when omitted.

ungroupedboolean

The column of records whose group_by field is empty instead.

Returns

A page of the view's records, with next_cursor and any sprint.

Errors

422validation_failedgroup, ungrouped, from or to do not fit the view, or limit is out of range.
404not_foundThe view, or the record to continue after, does not exist.

Pages

Link to Create a pageCreate a page

POST/v1/workspaces/{workspace_id}/pages

Create a page in a workspace, or a record's body with record_id.

Alsopage_create in page_writescaffold.page.create()Write

Path parameters

workspace_idstringrequired

Body parameters

record_idstring

Makes the page this record's body instead, with no title of its own.

titlestring

A standalone page's title.

Returns

The new page.

Errors

422validation_failedNeither a title nor a record_id is sent, or the title is too long.
404not_foundNo record you can see has that record_id.
409conflictThe record or its database is archived, or the record already has a body.

Link to List pagesList pages

GET/v1/workspaces/{workspace_id}/pages

List a workspace's pages, oldest first, without blocks.

Alsopage_list in page_readscaffold.page.list()Read

Path parameters

workspace_idstringrequired

Query parameters

archivedboolean

List archived pages instead of live ones.

record_idstring

Only the body of this record.

Returns

The workspace's pages, without their blocks.

Link to Retrieve a pageRetrieve a page

GET/v1/pages/{page_id}

Read a page as Markdown, or with format blocks as blocks with stable ids, types, props, styled text and children, which page.edit targets.

Alsopage_get in page_readscaffold.page.get()Read

Path parameters

page_idstringrequired

Query parameters

formatstring

One of markdown, blocks

state_vectorstring

An editor's Yjs state vector (v1, base64): answers the update it lacks instead.

Returns

The page with its content in the format you asked for.

Errors

422validation_failedstate_vector is not a Yjs state vector.
404not_foundNo page you can see has that id.
409conflictThe page holds what Markdown cannot show: read it with format blocks.

Link to Rename a pageRename a page

POST/v1/pages/{page_id}/rename

Set a standalone page's title. A record's body has no title, since the record names it.

Alsopage_rename in page_writescaffold.page.rename()Write

Path parameters

page_idstringrequired

Body parameters

titlestringrequired

Returns

The renamed page.

Errors

422validation_failedThe title is too long, or the page is a record's body.
404not_foundNo page you can see has that id.
409conflictThe page is archived.

Link to Archive a pageArchive a page

POST/v1/pages/{page_id}/archive

Archive a page: it leaves page.list, takes no edits and is erased after 30 days. A record's body goes with its record through record.archive instead.

Alsopage_archive in page_writescaffold.page.archive()WriteAgents ask first

Path parameters

page_idstringrequired

Returns

The archived page.

Errors

422validation_failedThe page is a record's body: archive the record.
404not_foundNo page you can see has that id.
409conflictThe page is already archived.

Link to Restore a pageRestore a page

POST/v1/pages/{page_id}/restore

Restore an archived page with the content it had.

Alsopage_restore in page_writescaffold.page.restore()Write

Path parameters

page_idstringrequired

Returns

The restored page.

Errors

422validation_failedThe page is a record's body: restore the record.
404not_foundNo page you can see has that id.
409conflictThe page is not archived.

Link to Edit a pageEdit a page

POST/v1/pages/{page_id}/edit

Change a page's blocks by id with 1 to 100 ops that insert, update or delete blocks. An edit of over 10 blocks, or with preview true, changes nothing and answers each block before and after with a confirm token; send the same ops with it to apply them. It answers new block ids and the ops that undo it. An edit that could not be undone is refused, like deleting over about 256 KiB at once, so delete big sections in steps.

Alsopage_edit in page_writescaffold.page.edit()Write

Path parameters

page_idstringrequired

Body parameters

opsobject[]required
confirmstring

The confirm of a preview: applies the edit while the blocks it touches are unchanged.

previewboolean

Answer what the edit would change, and change nothing.

Returns

The page's new revision and how to undo it, or a preview to confirm.

Errors

422validation_failedThe ops are too many or too large, or a block or mention does not fit.
404not_foundThe page, or a block it targets, does not exist.
409conflictThe page or the record it is the body of is archived, or a new block's id is taken.

Link to Append to a pageAppend to a page

POST/v1/pages/{page_id}/blocks

Add Markdown at the end of a page or after a block. <@usr_...> mentions a member; an image alone in its paragraph adds an image block.

Alsopage_append in page_writescaffold.page.append()Write

Path parameters

page_idstringrequired

Body parameters

markdownstringrequired
afterstring

A block id. The end of the page when omitted.

Returns

The page's new revision and how to undo it.

Errors

422validation_failedThe Markdown holds no text, too many blocks or what a page cannot hold.
404not_foundThe page, or the block to add after, does not exist.
409conflictThe page or the record it is the body of is archived.

Link to Propose a page rewritePropose a page rewrite

POST/v1/pages/{page_id}/proposals

Propose a rewrite of a page with ops as page.edit takes them, for a person to accept or discard in the console. Nothing changes until they accept it, so propose rewrites a person should see first.

Alsopage_propose in page_writescaffold.page.propose()Write

Path parameters

page_idstringrequired

Body parameters

opsobject[]required

Ops as page.edit takes them.

Returns

The open proposal and the blocks it would change.

Errors

422validation_failedThe ops are too many or too large, or a block or mention does not fit.
404not_foundThe page, or a block it targets, does not exist.
409conflictThe page or the record it is the body of is archived, a new block's id is taken, or the page has 20 open proposals.

Link to Retrieve a page proposalRetrieve a page proposal

GET/v1/pages/{page_id}/proposals/{proposal_id}

Read a proposed rewrite of a page. While it is open it answers the page's blocks now and as accepting it would leave them, or that it is stale since a block it rewrites changed.

Alsopage_proposal_get in page_readscaffold.page.proposal_get()Read

Path parameters

page_idstringrequired
proposal_idstringrequired

Returns

The proposal, with the page before and after it while it is open.

Errors

404not_foundNo page you can see has that id, or no such proposal.

Link to List page proposalsList page proposals

GET/v1/pages/{page_id}/proposals

List the proposed rewrites of a page that wait for a person, oldest first.

Alsopage_proposal_list in page_readscaffold.page.proposal_list()Read

Path parameters

page_idstringrequired

Returns

The page's open proposals.

Errors

404not_foundNo page you can see has that id.

Link to Discard a page proposalDiscard a page proposal

POST/v1/pages/{page_id}/proposals/{proposal_id}/discard

Discard a proposed rewrite of a page and leave the page as it is. It answers the proposal's ops, which page.propose takes to propose it again.

Alsopage_proposal_discard in page_writescaffold.page.proposal_discard()Write

Path parameters

page_idstringrequired
proposal_idstringrequired

Returns

The discarded proposal.

Errors

404not_foundNo page you can see has that id, or no such proposal.
409conflictThe proposal was accepted or discarded already.

Models

Link to List modelsList models

GET/v1/models

List the models runs may use, their token prices now in millicredits per million, and the price version.

Alsomodel_list in run_readscaffold.model.list()Read

Returns

The models with their token prices and the price version.

Commands

Link to Describe a commandDescribe a command

GET/v1/commands/{name}

Describe a command by its catalog or MCP name: its MCP tool and action, what it does, how to undo it and the JSON schema of its input.

Alsocommand_describe in command_readscaffold.command.describe()Read

Path parameters

namestringrequired

A command as MCP names it, like task_create, or with a dot for the underscore.

Returns

The command's MCP tool and action, its description and its input schema.

Errors

404not_foundNo command you may run has that name.

App users

Link to List app usersList app users

GET/v1/projects/{project_id}/auth/users

List a project's app users in id order, a page at a time, with their status, last sign-in and live sessions, filtered by name or email and status. Counts the matches and all users.

Alsoapp_auth_user_list in project_readscaffold.app_auth.user_list()Read

Path parameters

project_idstringrequired

Query parameters

limitinteger

1 to 100, 20 when omitted.

searchstring

Only users whose name or email contains it.

starting_afterstring
statusstring

Returns

A page of the app's users with has_more and next_cursor.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Show an app userShow an app user

GET/v1/projects/{project_id}/auth/users/{user_id}

Show one app user: status, lock end, sign-up, last sign-in, sign-in methods and, while unconfirmed, when they are deleted.

Alsoapp_auth_user_show in project_readscaffold.app_auth.user_show()Read

Path parameters

project_idstringrequired
user_idstringrequired

Returns

The user with their status, lock end and sign-in methods.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.

Link to Unlock an app userUnlock an app user

POST/v1/projects/{project_id}/auth/users/{user_id}/unlock

Owners only: end the 15-minute lock five wrong passwords put on an app user's email.

Alsoapp_auth_user_unlock in project_irreversiblescaffold.app_auth.user_unlock()WriteAgents ask first

Path parameters

project_idstringrequired
user_idstringrequired

Returns

The unlocked user's id and when.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.
403forbiddenYou are not an owner of the workspace.
409conflictThe user is not locked.

Link to Email an app userEmail an app user

POST/v1/projects/{project_id}/auth/users/{user_id}/email

Email an app user a password reset, or their unconfirmed address's confirmation again. At most one of each a minute, counted like the user's own requests: 3 auth emails an hour per address, and the workspace's monthly quota while the address is unproven.

Alsoapp_auth_user_email_send in project_irreversiblescaffold.app_auth.user_email_send()WriteAgents ask first

Path parameters

project_idstringrequired
user_idstringrequired

Body parameters

emailstringrequired

One of recovery, confirmation

Returns

When the email was queued.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.
409conflictThey confirmed already, or this email went to them under a minute ago.
402cap_reachedThe address had its auth emails for the hour, or the workspace's apps their counted emails for the month.
403project_suspendedScaffold suspended the project.

Link to List an app user's sessionsList an app user's sessions

GET/v1/projects/{project_id}/auth/users/{user_id}/sessions

List an app user's live sessions with the device and place each signed in from.

Alsoapp_auth_user_session_list in project_readscaffold.app_auth.user_session_list()Read

Path parameters

project_idstringrequired
user_idstringrequired

Returns

The user's live sessions, most recently active first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.

Link to Revoke an app user's sessionRevoke an app user's session

DELETE/v1/projects/{project_id}/auth/users/{user_id}/sessions/{session_id}

End one of an app user's sessions.

Alsoapp_auth_user_session_revoke in project_irreversiblescaffold.app_auth.user_session_revoke()WriteAgents ask first

Path parameters

project_idstringrequired
session_idstringrequired
user_idstringrequired

Returns

The ended session's id and when it ended.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, its user or that user's live session does not exist.

Link to Sign an app user out everywhereSign an app user out everywhere

POST/v1/projects/{project_id}/auth/users/{user_id}/sign-out

End every session of an app user.

Alsoapp_auth_user_sign_out_everywhere in project_irreversiblescaffold.app_auth.user_sign_out_everywhere()WriteAgents ask first

Path parameters

project_idstringrequired
user_idstringrequired

Returns

The user's id, the sessions that ended and when.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.

Link to List app sign-in eventsList app sign-in events

GET/v1/projects/{project_id}/auth/sign-ins

List a project's app sign-in events of the last 90 days, newest first, 100 at a time: sign-ups, sign-ins, wrong passwords, locks, emails and sign-outs, with place and IP.

Alsoapp_auth_sign_in_event_list in project_readscaffold.app_auth.sign_in_event_list()Read

Path parameters

project_idstringrequired

Query parameters

beforestring

The id of the oldest event already seen. Omit it to start from the newest.

emailstring

Only users whose email contains it.

onlystring

One of failed, sign_ups, password_resets

user_idstring

Returns

A page of sign-in events, newest first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Delete an app userDelete an app user

DELETE/v1/projects/{project_id}/auth/users/{user_id}

Owners only: delete an app user. Their email, password and sign-in history are erased and every session ends.

Alsoapp_auth_user_delete in project_irreversiblescaffold.app_auth.user_delete()WriteAgents ask first

Path parameters

project_idstringrequired
user_idstringrequired

Returns

The deleted user's id and when they were erased.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundThe project, or its user with that id, does not exist.
403forbiddenYou are not an owner of the workspace.

Link to Retrieve app auth settingsRetrieve app auth settings

GET/v1/projects/{project_id}/auth/settings

Show where a project's auth emails may link to.

Alsoapp_auth_settings_get in project_readscaffold.app_auth.settings_get()Read

Path parameters

project_idstringrequired

Returns

Where the project's auth emails may link to.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Update app auth settingsUpdate app auth settings

POST/v1/projects/{project_id}/auth/settings

Replace the site URL a project's auth emails link to and the other URLs they may.

Alsoapp_auth_settings_update in project_writescaffold.app_auth.settings_update()Write

Path parameters

project_idstringrequired

Body parameters

redirect_urlsstring[]

At most 20, each like site_url. Replaces the whole list.

site_urlstring

An https URL, or http on localhost. Omit it to send codes without links.

Returns

The project's new auth email settings.

Errors

422validation_failedA URL is not valid or too long, or there are too many.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.

Link to Retrieve an app's email usageRetrieve an app's email usage

GET/v1/projects/{project_id}/auth/email-usage

Show the emails a project's app queued this month, its workspace's total against the plan's monthly quota, and its hourly email.send limit.

Alsoapp_auth_email_usage_get in project_readscaffold.app_auth.email_usage_get()Read

Path parameters

project_idstringrequired

Returns

The project's and its workspace's counted emails this month, the plan's quota, the hourly email.send limit and when the month resets.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to List suppressed addressesList suppressed addresses

GET/v1/projects/{project_id}/auth/email-suppressions

List the addresses a project's app no longer emails, after a bounce, a spam complaint or by hand.

Alsoapp_auth_email_suppression_list in project_readscaffold.app_auth.email_suppression_list()Read

Path parameters

project_idstringrequired

Returns

The addresses the project's app no longer emails, newest first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Suppress an addressSuppress an address

POST/v1/projects/{project_id}/auth/email-suppressions

Stop a project's app emailing an address: auth emails and email.send skip it.

Alsoapp_auth_email_suppression_add in project_writescaffold.app_auth.email_suppression_add()Write

Path parameters

project_idstringrequired

Body parameters

emailstringrequired

Returns

The suppressed address and when it was added.

Errors

422validation_failedThe email is not an address, or the slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
409conflictThe address is already suppressed.

Link to Unsuppress an addressUnsuppress an address

POST/v1/projects/{project_id}/auth/email-suppressions/remove

Let a project's app email a suppressed address again.

Alsoapp_auth_email_suppression_remove in project_writescaffold.app_auth.email_suppression_remove()Write

Path parameters

project_idstringrequired

Body parameters

emailstringrequired

Returns

The address and when the project's emails started reaching it again.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug, or the address is not suppressed.

Link to Retrieve an app's email senderRetrieve an app's email sender

GET/v1/projects/{project_id}/auth/sender

Show who a project's emails come from: its name beside the address every app sends from.

Alsoapp_auth_sender_get in project_readscaffold.app_auth.sender_get()Read

Path parameters

project_idstringrequired

Returns

The name inboxes show and the address the project's emails come from.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Email

Link to Send an emailSend an email

POST/v1/projects/{project_id}/email

Email one person from a project's app, like a receipt or a reminder, with the project's name as the sender. It counts against the workspace's monthly quota and the project's 100 an hour.

Alsoemail_send in project_irreversiblescaffold.email.send()WriteAgents ask first

Path parameters

project_idstringrequired

Body parameters

bodystringrequired

Plain text, at most 20,000 characters. A blank line starts a new paragraph.

subjectstringrequired

One line, at most 200 characters.

tostringrequired
reply_tostring

Where a reply goes, like the app's support address. Left out, replies go to the address every app sends from, which nobody reads.

Returns

The queued message's id and when it was queued.

Errors

422validation_failedAn address, the subject or the body is not valid, or the slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
403project_suspendedScaffold suspended the project.
409conflictThe address is suppressed after a bounce or complaint.
402cap_reachedThe workspace used this month's email quota, or the project sent 100 within the hour.

App payments

Link to Connect Stripe to an appConnect Stripe to an app

POST/v1/projects/{project_id}/payments/connect

Link a project's app to a Stripe account its customer owns and answer its setup page. Rerun for a new page.

Alsoapp_payments_connect_start in project_writescaffold.app_payments.connect_start()Write

Path parameters

project_idstringrequired

Body parameters

countrystring

Two-letter country like us, for the first connect.

Returns

The linked Stripe account and its setup page, which works once.

Errors

422validation_failedA first connect has no two-letter country, or the slug names projects in more than one of your workspaces.
403forbiddenYou are not an owner of the workspace.
403plan_requiredApp payments need the Paid plan.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe project already takes payments through another Stripe account.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Retrieve an app's Stripe accountRetrieve an app's Stripe account

GET/v1/projects/{project_id}/payments/account

Show if a project's Stripe account can charge and pay out, and what Stripe needs.

Alsoapp_payments_account_get in project_readscaffold.app_payments.account_get()Read

Path parameters

project_idstringrequired

Returns

Whether the project's Stripe account can charge and pay out, and what Stripe still needs.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Retrieve an app's revenueRetrieve an app's revenue

GET/v1/projects/{project_id}/payments/revenue

Show what a project's Stripe account took over 30 days, per currency.

Alsoapp_payments_revenue_get in project_readscaffold.app_payments.revenue_get()Read

Path parameters

project_idstringrequired

Returns

The Stripe account's payments and refunds, less failed refunds, of the last 30 days per currency, or no account when Stripe is not connected. Disputes are not counted. A read counts the newest 1,000 balance changes and sets truncated when there were more.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
403plan_requiredRevenue needs the Paid plan.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Link to Disconnect Stripe from an appDisconnect Stripe from an app

DELETE/v1/projects/{project_id}/payments/account

Unlink a project's app from its Stripe account; the customer keeps it.

Alsoapp_payments_disconnect in project_writescaffold.app_payments.disconnect()Write

Path parameters

project_idstringrequired

Returns

The unlinked Stripe account's id and when it was unlinked.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403forbiddenYou are not an owner of the workspace.
404not_foundNo project you can see has that id or slug, or it has no Stripe account linked.

Link to List Stripe deliveriesList Stripe deliveries

GET/v1/projects/{project_id}/payments/deliveries

List the Stripe events forwarded to a project's app, with each try.

Alsoapp_payments_webhook_delivery_list in project_readscaffold.app_payments.webhook_delivery_list()Read

Path parameters

project_idstringrequired

Returns

The newest 100 deliveries of 30 days, each with its tries, what the app answered and the next try.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Resend a Stripe eventResend a Stripe event

POST/v1/projects/{project_id}/payments/deliveries/{event_id}/resend

Forward a Stripe event to a project's app again now.

Alsoapp_payments_webhook_delivery_resend in project_irreversiblescaffold.app_payments.webhook_delivery_resend()WriteAgents ask first

Path parameters

event_idstringrequired

Stripe's id of the event, like evt_1Q8L.

project_idstringrequired

Returns

The delivery with this try added.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug, or no delivery of that event from its linked Stripe account.
502upstreamStripe failed. Try again.
501not_configuredThis Scaffold has no Stripe set up.

Realtime

Link to Publish a realtime messagePublish a realtime message

POST/v1/projects/{project_id}/realtime/channels/{channel}/messages

Send JSON to a channel of a project's app, reaching each of its signed-in users subscribed to the channel now. Nothing is stored, so a later subscriber never gets it. Any signed-in user of the app can subscribe to any of its channels, so never publish one user's private data to a guessable channel; per-user private channels are not built yet.

Alsorealtime_publish in project_irreversiblescaffold.realtime.publish()WriteAgents ask first

Path parameters

channelstringrequired

Up to 100 letters, digits and _-.:, like orders:42.

project_idstringrequired

Body parameters

dataanyrequired

Any JSON, at most 32 KiB, which subscribers get as the message's data.

Returns

The channel and how many subscriptions the message was sent to.

Errors

422validation_failedThe channel name or data is too long or holds other characters, or the slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.
403project_suspendedScaffold suspended the project.

Link to List realtime channelsList realtime channels

GET/v1/projects/{project_id}/realtime/channels

List the realtime channels of a project's app that its users subscribe to now, with each one's subscriptions and the project's cap.

Alsorealtime_channel_list in project_readscaffold.realtime.channel_list()Read

Path parameters

project_idstringrequired

Returns

The open subscriptions by channel, their total and the project's cap.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Agent runs

Link to Start an agent runStart an agent run

POST/v1/runs

Start a run of an agent. It holds the top of its estimate, or its first model call's cost if more, from the workspace's credits and gives back what it does not spend.

Alsorun_create in run_writescaffold.run.create()WriteSpends credits

Body parameters

agentstringrequired

Who does the work.

One of planner, qa, triage

promptstringrequired

What to do, at most 20000 characters.

workspace_idstringrequired
ask_before_changesboolean

Ask a person before each change.

contextstring[]

Pages, tasks, records, databases, projects or deploys to read first, at most 10.

modelstring

Left out, the agent's default. Advanced and Max need the Paid plan.

One of standard, advanced, max

project_idstring

The project of the workspace the run is for, whose costs count its credits.

Returns

The run, with its estimate and the credits held.

Errors

422validation_failedThe prompt is blank or too long, or context names too many or the wrong things.
402credits_exhaustedThe workspace lacks the credits the run would hold.
402cap_reachedThe hold would pass the workspace's monthly cap, the agent's monthly limit or Scaffold's daily limit.
403plan_requiredAdvanced and Max need the Paid plan.
404not_foundSomething in context does not exist.
409conflictThe agent is paused.

Link to Price an agent runPrice an agent run

POST/v1/runs/quote

Price a run: its estimate, what run.create would hold, the credits available and which cap, limit or shortfall would refuse it.

Alsorun_quote in run_readscaffold.run.quote()Read

Body parameters

agentstringrequired

Who does the work.

One of planner, qa, triage

promptstringrequired

What to do, at most 20000 characters.

workspace_idstringrequired
ask_before_changesboolean

Ask a person before each change.

contextstring[]

Pages, tasks, records, databases, projects or deploys to read first, at most 10.

modelstring

Left out, the agent's default. Advanced and Max need the Paid plan.

One of standard, advanced, max

project_idstring

The project of the workspace the run is for, whose costs count its credits.

Returns

The estimate, what run.create would hold, the credits available and what would refuse the hold.

Errors

422validation_failedThe prompt is blank or too long, or context names too many or the wrong things.
403plan_requiredAdvanced and Max need the Paid plan.
404not_foundSomething in context does not exist.
409conflictThe agent is paused.

Link to List agent runsList agent runs

GET/v1/runs

List agent runs, newest first.

Alsorun_list in run_readscaffold.run.list()Read

Query parameters

workspace_idstringrequired
agentstring

Only the runs of this agent.

One of planner, qa, triage

contextstring

Only the runs started for this.

limitinteger

1 to 100, 20 when omitted.

starting_afterstring

Returns

A page of runs, newest first, with has_more and next_cursor.

Link to Retrieve a runRetrieve a run

GET/v1/runs/{run_id}

Read an agent run: status, steps with what each spent, credits, approvals and edits an undo keeps.

Alsorun_get in run_readscaffold.run.get()Read

Path parameters

run_idstringrequired

Returns

The run with its steps, credits, approvals and the edits an undo keeps. What each call said and read shows only to its starter and owners.

Errors

404not_foundNo run you can see has that id.

Link to Stop a runStop a run

POST/v1/runs/{run_id}/stop

Stop a running or waiting run. Its edits stay until run.undo.

Alsorun_stop in run_writescaffold.run.stop()Write

Path parameters

run_idstringrequired

Returns

The stopped run.

Errors

403forbiddenYou neither started the run nor own its workspace.
404not_foundNo run you can see has that id.
409conflictThe run already ended.

Link to List approvalsList approvals

GET/v1/workspaces/{workspace_id}/approvals

List the changes waiting for your approval: your runs', and every member's for a workspace owner.

Alsorun_approval_list in run_readscaffold.run.approval_list()Read

Path parameters

workspace_idstringrequired

Returns

The changes runs wait to have approved, oldest first, each with who started its run.

Link to Deny a changeDeny a change

POST/v1/runs/{run_id}/deny

Deny the change a run waits on and stop the run.

Alsorun_deny in run_writescaffold.run.deny()WriteSpends credits

Path parameters

run_idstringrequired

Body parameters

approvalintegerrequired
reasonstring

At most 1000 characters.

Returns

The stopped run.

Errors

422validation_failedThe reason is too long.
403forbiddenYou neither started the run nor own its workspace.
404not_foundNo run you can see has that id.
409conflictThe run waits on no such approval.

Link to Resume a runResume a run

POST/v1/runs/{run_id}/resume

Resume a run stopped by a person, a limit or its credits.

Alsorun_resume in run_writescaffold.run.resume()WriteSpends credits

Path parameters

run_idstringrequired

Body parameters

legintegerrequired

Returns

The run, going on.

Errors

403forbiddenYou did not start the run.
404not_foundNo run you can see has that id.
409conflictThe run is not stopped by a person, a limit or its credits, went on since, was undone, its agent is paused or its starter left.

Link to Follow up on a runFollow up on a run

POST/v1/runs/{run_id}/follow-up

Ask a done or denied run more; its agent goes on in the same run.

Alsorun_follow_up in run_writescaffold.run.follow_up()WriteSpends credits

Path parameters

run_idstringrequired

Body parameters

legintegerrequired
promptstringrequired

At most 20000 characters.

Returns

The run, going on.

Errors

422validation_failedThe follow-up is blank or too long.
403forbiddenYou did not start the run.
404not_foundNo run you can see has that id.
409conflictThe run is not done or denied, went on since, was undone, its agent is paused or its starter left.

Link to Undo a runUndo a run

POST/v1/runs/{run_id}/undo

Take back every edit of an ended run as one change. Refused while run.get lists later edits, unless keep_changed.

Alsorun_undo in run_irreversiblescaffold.run.undo()WriteAgents ask first

Path parameters

run_idstringrequired

Body parameters

legintegerrequired
keep_changedboolean

Leave things edited since the run as they are.

Returns

The run, undone.

Errors

404not_foundNo run you can see has that id.
409conflictThe run is still going or already undone, or later edits would be overwritten.

Agents

Link to List agentsList agents

GET/v1/workspaces/{workspace_id}/agents

List a workspace's agents, their settings and whether each is paused or working. Which models agents may use and what they cost is model.list's answer.

Alsoagent_list in run_readscaffold.agent.list()Read

Path parameters

workspace_idstringrequired

Returns

The workspace's agents with their settings.

Link to Retrieve an agentRetrieve an agent

GET/v1/agents/{agent_id}

Read an agent: what it does, may do and asks before doing, and its settings.

Alsoagent_get in run_readscaffold.agent.get()Read

Path parameters

agent_idstringrequired

Returns

The agent with what it does, may do and asks before doing.

Errors

404not_foundNo agent you can see has that id.

Link to Update an agentUpdate an agent

PATCH/v1/agents/{agent_id}

Owners only: change what an agent asks before doing, its default model or its monthly limit in millicredits.

Alsoagent_update in run_writescaffold.agent.update()Write

Path parameters

agent_idstringrequired

Body parameters

asks_beforestring

One of big_changes, every_change

default_modelstring

Advanced and Max need the Paid plan.

One of standard, advanced, max

monthly_limitinteger

Millicredits a month; null removes the limit. Left out, it stays.

Returns

The agent with its new settings.

Errors

422validation_failedmonthly_limit is negative.
403forbiddenYou are not an owner of the workspace.
403plan_requiredAdvanced and Max need the Paid plan.
404not_foundNo agent you can see has that id.

Link to Pause an agentPause an agent

POST/v1/agents/{agent_id}/pause

Owners only: pause an agent. It starts no runs and skips its schedules; runs going now finish.

Alsoagent_pause in run_writescaffold.agent.pause()Write

Path parameters

agent_idstringrequired

Returns

The paused agent.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundNo agent you can see has that id.

Link to Resume an agentResume an agent

POST/v1/agents/{agent_id}/resume

Owners only: resume a paused agent. A stopped run resumes by run.resume.

Alsoagent_resume in run_writescaffold.agent.resume()Write

Path parameters

agent_idstringrequired

Returns

The resumed agent.

Errors

403forbiddenYou are not an owner of the workspace.
404not_foundNo agent you can see has that id.

Schedules

Link to List schedulesList schedules

GET/v1/workspaces/{workspace_id}/schedules

List a workspace's schedules, oldest first, with when each runs next.

Alsoschedule_list in run_readscaffold.schedule.list()Read

Path parameters

workspace_idstringrequired

Returns

The workspace's schedules with when each runs next.

Link to Create a scheduleCreate a schedule

POST/v1/workspaces/{workspace_id}/schedules

Paid plan: run an agent on a repeating time, as you. A run it cannot start, as while the agent is paused, is skipped.

Alsoschedule_create in run_writescaffold.schedule.create()Write

Path parameters

workspace_idstringrequired

Body parameters

agentstringrequired

One of planner, qa, triage

promptstringrequired

What each run does, at most 20000 characters.

repeatsobjectrequired
modelstring

Left out, the agent's default model when the schedule is made.

One of standard, advanced, max

Returns

The new schedule with when it runs next.

Errors

422validation_failedThe prompt is blank or too long, or the time or timezone is not valid.
403plan_requiredSchedules need the Paid plan.
409conflictThe workspace already has 50 schedules.

Link to Update a scheduleUpdate a schedule

PATCH/v1/schedules/{schedule_id}

Change a schedule. Only its maker and owners may, and only its maker its prompt or agent, as it runs as them.

Alsoschedule_update in run_writescaffold.schedule.update()Write

Path parameters

schedule_idstringrequired

Body parameters

agentstring

One of planner, qa, triage

enabledboolean

False pauses it, true resumes it.

modelstring

One of standard, advanced, max

promptstring
repeatsobject

Returns

The schedule with when it runs next.

Errors

422validation_failedThe prompt is blank or too long, or the time or timezone is not valid.
403forbiddenYou neither made the schedule nor own the workspace, or you change the prompt or agent of a schedule someone else made.
403plan_requiredSchedules need the Paid plan.
404not_foundNo schedule you can see has that id.
409conflictThe schedule is deleted.

Link to Delete a scheduleDelete a schedule

DELETE/v1/schedules/{schedule_id}

Delete a schedule. Only its maker and owners may.

Alsoschedule_delete in run_writescaffold.schedule.delete()Write

Path parameters

schedule_idstringrequired

Returns

The deleted schedule.

Errors

403forbiddenYou neither made the schedule nor own the workspace.
404not_foundNo schedule you can see has that id.
409conflictThe schedule is already deleted.

Link to Restore a scheduleRestore a schedule

POST/v1/schedules/{schedule_id}/restore

Bring back a deleted schedule.

Alsoschedule_restore in run_writescaffold.schedule.restore()Write

Path parameters

schedule_idstringrequired

Returns

The restored schedule with when it runs next.

Errors

403forbiddenYou neither made the schedule nor own the workspace.
403plan_requiredSchedules need the Paid plan.
404not_foundNo schedule you can see has that id.
409conflictThe schedule is not deleted, or the workspace already has 50 schedules.

Link to Run a schedule nowRun a schedule now

POST/v1/schedules/{schedule_id}/run

Start a run of a schedule now, as you, without moving its next run.

Alsoschedule_run_now in run_writescaffold.schedule.run_now()WriteSpends credits

Path parameters

schedule_idstringrequired

Returns

The run it started.

Errors

402credits_exhaustedThe workspace lacks the credits the run would hold.
402cap_reachedThe hold would pass the workspace's monthly cap, the agent's monthly limit or Scaffold's daily limit.
403plan_requiredSchedules, or the schedule's model, need the Paid plan.
404not_foundNo schedule you can see has that id.
409conflictThe schedule is deleted or lost its prompt, or its agent is paused.

Onboarding

Link to Retrieve the setup checklistRetrieve the setup checklist

GET/v1/workspaces/{workspace_id}/onboarding

Show your setup checklist in a workspace and what ticked each step.

Alsoonboarding_get in account_readscaffold.onboarding.get()Read

Path parameters

workspace_idstringrequired

Returns

Your setup checklist in the workspace.

Link to Skip a setup stepSkip a setup step

POST/v1/workspaces/{workspace_id}/onboarding/{step}/skip

Put off a setup step that is not done. It still ticks if it happens.

Alsoonboarding_step_skip in account_writescaffold.onboarding.step_skip()Write

Path parameters

stepstringrequired

One of connect, first_command, first_deploy

workspace_idstringrequired

Returns

The checklist with the step skipped.

Errors

409conflictThe step is already done.

Link to Bring back a setup stepBring back a setup step

POST/v1/workspaces/{workspace_id}/onboarding/{step}/resume

Bring back a skipped setup step.

Alsoonboarding_step_resume in account_writescaffold.onboarding.step_resume()Write

Path parameters

stepstringrequired

One of connect, first_command, first_deploy

workspace_idstringrequired

Returns

The checklist with the step back.

Notifications

Link to List notificationsList notifications

GET/v1/workspaces/{workspace_id}/notifications

List your notifications in a workspace, newest first, by unread or source.

Alsonotification_list in workspace_readscaffold.notification.list()Read

Path parameters

workspace_idstringrequired

Query parameters

limitinteger

1 to 100, 20 when omitted.

sourcestring

One of approvals, deploys, mentions_and_assignments, credits

starting_afterstring
unreadboolean

Returns

A page of your notifications with has_more and next_cursor.

Errors

422validation_failedlimit is out of range.
404not_foundThe notification to continue after does not exist.

Link to Mark notifications readMark notifications read

POST/v1/workspaces/{workspace_id}/notifications/read

Mark your notifications read, answering those it changed.

Alsonotification_read in workspace_writescaffold.notification.read()Write

Path parameters

workspace_idstringrequired

Body parameters

notification_idsstring[]required

1 to 1000.

Returns

The ids of the notifications it changed.

Errors

422validation_failednotification_ids is empty or too long.
404not_foundA notification is not yours.

Link to Mark notifications unreadMark notifications unread

POST/v1/workspaces/{workspace_id}/notifications/unread

Mark your notifications unread, answering those it changed.

Alsonotification_unread in workspace_writescaffold.notification.unread()Write

Path parameters

workspace_idstringrequired

Body parameters

notification_idsstring[]required

1 to 1000.

Returns

The ids of the notifications it changed.

Errors

422validation_failednotification_ids is empty or too long.
404not_foundA notification is not yours.

Link to Mark all notifications readMark all notifications read

POST/v1/workspaces/{workspace_id}/notifications/read-all

Mark up to 1000 unread notifications read, newest first, answering them.

Alsonotification_read_all in workspace_writescaffold.notification.read_all()Write

Path parameters

workspace_idstringrequired

Returns

The ids of the notifications it changed.

Link to Count unread notificationsCount unread notifications

GET/v1/workspaces/{workspace_id}/notifications/unread-count

Count your unread notifications, in all and per source.

Alsonotification_unread_count in workspace_readscaffold.notification.unread_count()Read

Path parameters

workspace_idstringrequired

Returns

Your unread count, in all and per source.

Link to Retrieve notification preferencesRetrieve notification preferences

GET/v1/workspaces/{workspace_id}/notifications/preferences

Show how each source reaches you: in app, and by email at 18:00 UTC.

Alsonotification_preferences_get in workspace_readscaffold.notification.preferences_get()Read

Path parameters

workspace_idstringrequired

Returns

How each source reaches you.

Link to Set notification preferencesSet notification preferences

POST/v1/workspaces/{workspace_id}/notifications/preferences

Set whether a source reaches you in app and by email.

Alsonotification_preferences_set in workspace_writescaffold.notification.preferences_set()Write

Path parameters

workspace_idstringrequired

Body parameters

emailbooleanrequired

Only with in_app.

in_appbooleanrequired
sourcestringrequired

One of approvals, deploys, mentions_and_assignments, credits

Returns

How each source reaches you now.

Errors

422validation_failedEmail is on for a source whose in-app notifications are off.

Link to Search a workspaceSearch a workspace

GET/v1/workspaces/{workspace_id}/search

Find tasks, records, pages and runs by words or a record key, with counts per kind.

Alsosearch_query in workspace_readscaffold.search.query()Read

Path parameters

workspace_idstringrequired

Query parameters

querystringrequired

Words of 3 or more characters, or a record key, up to 200 characters in all.

bystring

Only what this member or agent changed last, or ran.

kindstring

One of task, record, page, run

limitinteger

1 to 100, 50 when omitted.

Returns

The hits, with counts per kind.

Errors

422validation_failedlimit is out of range, or by names no member or agent of the workspace.

Comments

Link to Create a commentCreate a comment

POST/v1/records/{record_id}/comments

Comment on a record.

Alsocomment_create in record_writescaffold.comment.create()Write

Path parameters

record_idstringrequired

Body parameters

bodystringrequired

Up to 10000 characters. <@usr_...> mentions and notifies a member.

Returns

The new comment.

Errors

422validation_failedThe body is blank or too long, or mentions too many or someone outside the workspace.
404not_foundNo record you can see has that id.
409conflictThe record is archived.

Link to List commentsList comments

GET/v1/records/{record_id}/comments

List a record's comments, oldest first.

Alsocomment_list in record_readscaffold.comment.list()Read

Path parameters

record_idstringrequired

Query parameters

limitinteger

1 to 100, 20 when omitted.

starting_afterstring

Returns

A page of the record's comments with has_more and next_cursor.

Errors

422validation_failedlimit is out of range.
404not_foundThe record, or the comment to continue after, does not exist.

Link to Delete a commentDelete a comment

DELETE/v1/comments/{comment_id}

Delete your comment.

Alsocomment_delete in record_writescaffold.comment.delete()Write

Path parameters

comment_idstringrequired

Returns

The deleted comment.

Errors

403forbiddenThe comment is another member's.
404not_foundNo comment you can see has that id.
409conflictThe comment is already deleted.

Link to Restore a commentRestore a comment

POST/v1/comments/{comment_id}/restore

Bring back your deleted comment.

Alsocomment_restore in record_writescaffold.comment.restore()Write

Path parameters

comment_idstringrequired

Returns

The restored comment.

Errors

403forbiddenThe comment is another member's.
404not_foundNo comment you can see has that id.
409conflictThe comment is not deleted.

Status

Link to Retrieve the statusRetrieve the status

GET/v1/status

Show Scaffold's status overall and per component, open incidents, planned maintenance and console notices. Needs no sign-in.

Alsostatus_get in project_readscaffold.status.get()Read

Returns

How Scaffold is doing overall and per component, with open incidents and notices.

Link to Retrieve the versionRetrieve the version

GET/v1/version

Show which build of Scaffold answers: its git commit and when it was built. Needs no sign-in.

Alsostatus_version_get in project_readscaffold.status.version_get()Read

Returns

The commit the running build was made from and when, both null on a build the release pipeline did not make.

Link to List incidentsList incidents

GET/v1/status/incidents

List incidents and maintenance open in the last 90 days, newest first, with updates. Needs no sign-in.

Alsostatus_incident_list in project_readscaffold.status.incident_list()Read

Query parameters

daysinteger

1 to 90 days, 90 when omitted, listing every incident open in them and all upcoming maintenance.

Returns

The incidents and maintenance of the days asked for, newest first.

Errors

422validation_faileddays is out of range.

Link to Retrieve an incidentRetrieve an incident

GET/v1/status/incidents/{incident_id}

Show one incident or maintenance window with every update and any write-up. Needs no sign-in.

Alsostatus_incident_get in project_readscaffold.status.incident_get()Read

Path parameters

incident_idstringrequired

Returns

The incident or maintenance with every update and any write-up.

Errors

404not_foundNo incident has that id.

Deploys

Link to Create a deployCreate a deploy

POST/v1/projects/{project_id}/deploys

Build a project's upload in a sandbox, a Node app or a static site, and put it live once it serves. It needs only the upload's sha256 from source.list, or none for the newest, and answers the deploy with its status and URL. The live deploy stays ready for deploy.rollback. A Node app needs the Paid plan and takes the env as it is now, plus DATABASE_URL; an optional release command runs first, after a dump of the database. A deploy of the project not yet live fails in its favour. package.json "scaffold": {"kind": "worker"} makes a worker: no web page, never sleeps, Paid only.

Alsodeploy_create in project_writescaffold.deploy.create()WriteAgents ask first

Path parameters

project_idstringrequired

Body parameters

release_commandstring

Run with sh -c in the deploy's sandbox, with its env and DATABASE_URL, before it goes live, like npx prisma migrate deploy. The project's database is dumped first, as before every first start, and the dump kept 6 days. If it fails, the deploy fails and the live one keeps serving. At most 1,000 bytes; it may run for 10 minutes.

sha256string

The upload to build, as source.list gives its sha256. Left out, the newest upload.

Returns

The deploy, queued. Poll deploy.get until it is live or failed; its build log holds the build's output.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id. Or the release command is blank, holds a NUL or passes 1,000 bytes.
403project_suspendedScaffold suspended the project.
403plan_requiredA Free workspace made 15 deploys in 24 hours or built for 120 minutes this month.
402cap_reachedA Paid workspace built for 1,000 minutes this month.
404not_foundThe project, or the upload with that hash, does not exist.
409conflictThe project has no address yet, or its env holds a name the runtime sets or more than a deploy takes.
502upstreamThis Scaffold has no tenant runtime set up to run deploys.

Link to List deploysList deploys

GET/v1/projects/{project_id}/deploys

List a project's deploys, newest first.

Alsodeploy_list in project_readscaffold.deploy.list()Read

Path parameters

project_idstringrequired

Returns

The project's deploys, newest first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to List each project's newest deployList each project's newest deploy

GET/v1/workspaces/{workspace_id}/deploys

List the newest deploy of each project in a workspace, newest first, with its status, so one read shows where every project stands.

Alsodeploy_recent_list in project_readscaffold.deploy.recent_list()Read

Path parameters

workspace_idstringrequired

Returns

One deploy per project that has any, newest first.

Errors

403forbiddenYou are not a member of the workspace.

Link to Retrieve a deployRetrieve a deploy

GET/v1/deploys/{deploy_id}

Show a deploy and its status: queued, building, starting, live, superseded, rolled_back or failed with its reason.

Alsodeploy_get in project_readscaffold.deploy.get()Read

Path parameters

deploy_idstringrequired

Returns

The deploy.

Errors

404not_foundNo deploy you can see has that id.

Link to Roll back a deployRoll back a deploy

POST/v1/deploys/{deploy_id}/rollback

Undo a deploy.create: put an earlier deploy of the project back live, without a rebuild, and its database too with restore_database, which only an owner on the Paid plan may ask. A static site goes back on any plan, a Node app needs the Paid plan. The deploy it replaces can be rolled back to in turn, and a deploy not yet live fails. While the database is put back, the project's address shows the maintenance page.

Alsodeploy_rollback in project_writescaffold.deploy.rollback()WriteAgents ask first

Path parameters

deploy_idstringrequired

An earlier deploy of the project that was live before.

Body parameters

restore_databaseboolean

Also put back the project's database as its restorable_dump holds it. Rows written since are lost, so the database as it is now is dumped first, which rolling forward again with restore_database puts back.

Returns

The earlier deploy, live again.

Errors

403plan_requiredThe deploy is a Node app, or restore_database was asked, and either needs the Paid plan.
403forbiddenrestore_database was asked and you are not an owner of the workspace.
403project_suspendedScaffold suspended the project.
404not_foundNo deploy you can see has that id.
409conflictThe deploy was never live, so it cannot go back live. Or restore_database was asked but no kept dump holds the database as it was then, or the database is being restored.

Link to Read deploy logsRead deploy logs

GET/v1/deploys/{deploy_id}/logs

Read a deploy's log a page at a time: its app's output, each line with its time and newest first read, or its build steps. range keeps the last 15m, 1h, 24h or 7d; pass next as after to read on. Over HTTP, follow it as a stream to get each new page as the log grows.

Alsodeploy_logs in project_readscaffold.deploy.logs()Read

Path parameters

deploy_idstringrequired

Query parameters

afterinteger

A page's next, to read on from there. Left out, the newest runtime lines or every build line.

kindstring

runtime, the app's output, or build, the deploy's steps to live. Left out, runtime.

One of runtime, build

max_bytesinteger

The most bytes of runtime lines to read, 1 to 65,536 and by default all of that. A page behind by more skips to the newest lines.

rangestring

Only lines from the last 15m, 1h, 24h or 7d. Left out, all that is kept.

One of 15m, 1h, 24h, 7d

Returns

A page of timed lines with where the next one starts, whether more can come, and when the host dropped older lines early to keep its log disk within its cap.

Errors

422validation_failedmax_bytes is outside 1 to 65,536, range is not 15m, 1h, 24h or 7d, or after is no page's next.
404not_foundNo deploy you can see has that id.
502upstreamThe deploy's tenant host did not answer. Try again.

Custom domains

Link to Add a custom domainAdd a custom domain

POST/v1/projects/{project_id}/domains

Add a custom domain to a project's app. A Free workspace has 1 custom domain; more need the Paid plan. It waits for the DNS records it answers: a CNAME to Scaffold, or an A record at the apex, and a TXT record proving it is yours. Other projects' claims never block it, verified ones included: the project whose records verify the domain takes it from the rest, and a claim that never verifies expires after 7 days.

Alsodomain_add in project_writescaffold.domain.add()Write

Path parameters

project_idstringrequired

Body parameters

domainstringrequired

The domain to serve the project's app on, like shop.example.com or example.com.

Returns

The domain, waiting for DNS, with the records to set.

Errors

422validation_failedThe domain is not a domain name, or is under Scaffold's own.
403plan_requiredA Free workspace has 1 custom domain, and it has it.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe domain is on this project already, or the project holds the most domains it may, as the reason says.
502upstreamThis Scaffold has no edge for custom domains set up.

Link to List custom domainsList custom domains

GET/v1/projects/{project_id}/domains

List a project's custom domains, oldest first, with where each stands, the DNS records it needs and when its certificate renews.

Alsodomain_list in project_readscaffold.domain.list()Read

Path parameters

project_idstringrequired

Returns

The project's custom domains, oldest first.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Check a custom domainCheck a custom domain

POST/v1/domains/{domain_id}/check

Check a custom domain's DNS now. Once it points at Scaffold with its TXT record it is verified: it serves the project's live deploy and gets its certificate on its first visit, other projects' unverified claims on it are removed, and one that held it verified goes back to waiting. A wrong or missing record is named with its fix. Scaffold rechecks verified domains daily: one whose records are gone 3 days goes back to waiting and stops serving. A verified domain whose records point away from Scaffold is marked so, with the problem found, and gets no new certificate until a check finds them pointing back.

Alsodomain_check in project_writescaffold.domain.check()Write

Path parameters

domain_idstringrequired

Returns

The domain, waiting with the record it lacks, wrong with the problem found, or verified, marked when its records point away.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo domain you can see has that id.
502upstreamA DNS lookup failed, so check again, or no edge is set up.

Link to Remove a custom domainRemove a custom domain

DELETE/v1/domains/{domain_id}

Remove a custom domain from its project. The app stops answering there at once, its certificate is deleted within a day and never renewed, and any project can add it again with domain.add.

Alsodomain_remove in project_writescaffold.domain.remove()Write

Path parameters

domain_idstringrequired

Returns

The domain removed and when.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo domain you can see has that id.

Webhooks

Link to Create a webhook endpointCreate a webhook endpoint

POST/v1/projects/{project_id}/webhooks

Register an https endpoint for a project's deploy and app user events. Each is POSTed signed, under an event id to dedupe by. The signing secret is shown once.

Alsowebhook_endpoint_create in project_writescaffold.webhook.endpoint_create()Write

Path parameters

project_idstringrequired

Body parameters

event_typesstring[]required

The events it takes, at least one.

urlstringrequired

An https address without credentials, at most 2048 bytes.

Returns

The endpoint and its signing secret, shown only once. Each POST carries Scaffold-Webhook-Id, the same on every retry, and Scaffold-Signature as t=<unix seconds>,v1=<hex>: HMAC-SHA256 under the secret of <t>.<raw body>. Answer 2xx within 10 seconds; anything else is retried for about 3 days, and an endpoint that failed all that time is turned off.

Errors

422validation_failedThe URL is not https, holds credentials or points at a private address, no event type was named, or the slug names projects in more than one of your workspaces.
403project_suspendedScaffold suspended the project.
404not_foundNo project you can see has that id or slug.
409conflictThe project already has 10 webhook endpoints.
409secret_shownA retry under the same Idempotency-Key, whose secret was already shown.

Link to List webhook endpointsList webhook endpoints

GET/v1/projects/{project_id}/webhooks

List a project's webhook endpoints, oldest first, without secrets.

Alsowebhook_endpoint_list in project_readscaffold.webhook.endpoint_list()Read

Path parameters

project_idstringrequired

Returns

The project's endpoints with the events each takes and whether it is on.

Errors

422validation_failedThe slug names projects in more than one of your workspaces: send the id.
404not_foundNo project you can see has that id or slug.

Link to Update a webhook endpointUpdate a webhook endpoint

PATCH/v1/webhooks/{endpoint_id}

Change a webhook endpoint's URL or event types, or turn it off or on again. It keeps its signing secret.

Alsowebhook_endpoint_update in project_writescaffold.webhook.endpoint_update()Write

Path parameters

endpoint_idstringrequired

Body parameters

enabledboolean

False turns it off; true turns it on again, also after Scaffold turned it off.

event_typesstring[]

Replaces the whole list.

urlstring

Keeps the signing secret.

Returns

The endpoint as it is now.

Errors

422validation_failedThe URL is not https, holds credentials or points at a private address, or the event types are empty.
403project_suspendedScaffold suspended the project.
404not_foundNo webhook endpoint you can see has that id.

Link to Delete a webhook endpointDelete a webhook endpoint

DELETE/v1/webhooks/{endpoint_id}

Delete a webhook endpoint with its signing secret and delivery log. Nothing more is posted to it.

Alsowebhook_endpoint_delete in project_irreversiblescaffold.webhook.endpoint_delete()WriteAgents ask first

Path parameters

endpoint_idstringrequired

Returns

The deleted endpoint's id and when it was deleted.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo webhook endpoint you can see has that id.

Link to List webhook deliveriesList webhook deliveries

GET/v1/projects/{project_id}/webhook-deliveries

List a project's webhook deliveries of the last 30 days, newest first, with each try and what the endpoint answered.

Alsowebhook_delivery_list in project_readscaffold.webhook.delivery_list()Read

Path parameters

project_idstringrequired

Query parameters

endpoint_idstring

Only this endpoint's deliveries.

failedboolean

Only deliveries that failed for good.

limitinteger

1 to 100, 20 when omitted.

starting_afterstring

The next_cursor of the page before.

Returns

A page of deliveries, newest first, each with its body and tries, with has_more and next_cursor.

Errors

422validation_failedThe limit is out of range, or the slug names projects in more than one of your workspaces.
404not_foundNo project you can see has that id or slug.

Link to Resend a webhook deliveryResend a webhook delivery

POST/v1/webhook-deliveries/{delivery_id}/resend

Try a webhook delivery that has not succeeded again now, with the same event id and body.

Alsowebhook_delivery_resend in project_irreversiblescaffold.webhook.delivery_resend()WriteAgents ask first

Path parameters

delivery_idstringrequired

Returns

The delivery, its next try due now.

Errors

403project_suspendedScaffold suspended the project.
404not_foundNo webhook delivery you can see has that id.
409conflictThe delivery succeeded already, was tried 26 times, or its endpoint is off.