Skip to content
StatefoldDocsChangelogOpen app

API

Authentication

Create a personal API token and send it as a bearer token.

The Statefold API lets scripts start threads, send follow-ups and read results. It authenticates with personal API tokens that act as you, within the scopes you choose.

Create a token

  1. Open Settings → API tokens and create a named token.
  2. Choose only the scopes the script needs.
  3. Copy the secret before closing the dialog. It is shown once; Statefold stores only its SHA-256 hash.

Keep the token in a secret manager, never in a thread, a repository, command history or a URL. Settings shows when each token was last used, including requests its scopes refused.

Send it

Send the token as a bearer token over HTTPS:

sh
export STATEFOLD_URL="https://staging.statefold.sh"
export STATEFOLD_TOKEN="sf_pat_YOUR_TOKEN"   # load it from your secret manager

curl --fail-with-body "$STATEFOLD_URL/api/v1/tasks" \
  -H "Authorization: Bearer $STATEFOLD_TOKEN"

STATEFOLD_URL is the origin of the Statefold you signed in to. Tokens start with sf_pat_.

What a token can do

All access is limited to your own threads, projects and connections, and to the endpoints in this reference. A personal token cannot manage account settings, upload workspace snapshots, open terminals, read conversation history, subscribe to transcript streams or send thread commands other than messages. Calls that start or wake a workspace spend machine credits, and the usual billing and validation limits apply.

Revoke

Revoke a token in Settings to reject its new requests immediately. Work it already started keeps running.

Identifiers you generate

Creating a thread uses identifiers you choose, so retries are safe. Generate fresh UUIDs for taskId, projectId (for a new project) and messageId. Pick an existing connection from statefold connections and a model it offers: credentials are never chosen for you.