API reference

Three limits apply to every request, and none of them can be changed per experiment.

• 32 MB per request. Enforced by the server infrastructure and not adjustable. A typical jsPsych dataset is 50 KB to 5 MB, so this mainly matters for base64 media. Gzipped request bodies are decompressed transparently, which in practice raises the ceiling for text data.
• 60 seconds per request. Every /api/* path runs behind a hosting layer with a hard 60-second ceiling. That's why /api/finalize returns immediately and finishes its work in the background instead of waiting for the job to end.
• JSON bodies only. Send Content-Type: application/json. The three participant endpoints don't check the HTTP method, so a request sent with the wrong verb arrives with an empty body and comes back as MISSING_PARAMETER rather than 405. The two authenticated endpoints below do check, and answer 405.

Compressing a request body yourself, and what the size limit means in practice. Request size limits

The trial size, session, abandonment, and file-size limits that apply only to incremental sessions. Save-as-you-go limits

Save a text file (CSV, JSON, etc.) to your experiment's storage. If you have validation rules set up, DataPipe checks the data before sending it on.

{
  "experimentID": "abc123",
  "filename": "subject01.csv",
  "data": "rt,response\n204,1\n389,0"
}

Open a session so an experiment can send trials as they happen, rather than only at the end. A participant who abandons the experiment partway through then leaves behind a recoverable partial session instead of nothing at all.

You won't usually call this yourself. The @jspsych/extension-pipe extension calls it by default, along with the staging writes that follow, and datapipe-client does the same when a plain JavaScript experiment starts a session with it. It's documented here because those writes go to a Firebase Realtime Database rather than to this API, and this response tells a client where to send them.

The same checks as /api/data/ run here, with the same error codes. The experiment must exist, not be finalized, be accepting data, and be under its session limit. Starting a session does not use up one of those sessions. The count is still taken when a submission completes. A 503 with SESSION_START_ERROR means incremental upload is unavailable, whether because the service is unreachable, because an experiment already has an unusually large number of sessions open at once, or because it has been switched off entirely. The experiment should submit at the end, as it would without streaming.

{
  "sessionId": "8fKq2mXpR7vNwLzB4cTy1dHs",
  "databaseURL": "https://<project>-default-rtdb.firebaseio.com",
  "maxTrialBytes": 16384,
  "maxTrials": 1000,
  "flushIntervalMs": 10000,
  "flushEveryNTrials": 10,
  "maxDisconnects": 20
}

Trials are then written to staging/<sessionId>/trials/<n> in that database, each one a JSON string, numbered from zero and never rewritten. The session is write-only. Nothing can read it back, and DataPipe tolerates a missing number rather than treating it as an error. Send sessionId with the final /api/data/ request to close it.

Save a binary file (audio, video, images) encoded as a base64 string. DataPipe decodes the string and stores the resulting file alongside the experiment's other data.

Get the next condition number for balanced assignment. Returns a value from 0 to n−1, cycling in order (0, 1, 2, ..., 0, 1, 2, ...).

{
  "message": "Success",
  "condition": 2
}

All responses are JSON. On failure, the body carries an error code from the table below and a message describing the problem. When metadata is on, write responses also include a metadataMessage field reporting what happened to the metadata file. It never affects whether the data itself was stored.

What DataPipe does with a queued submission, and how to get it back. When an upload fails

FILE_EXISTS, UPLOAD_ERROR, and UPLOAD_EXCEPTION are returned for every storage provider. INVALID_OSF_TOKEN occurs only on experiments still collecting to OSF, which is why it still names it.

INVALID_OSF_TOKEN, INVALID_REFRESH_TOKEN, and PROVIDER_TOKEN_EXPIRED no longer reject a submission. If a connected account's credential has expired, been revoked, or gone invalid, DataPipe queues the submission for retry (202, error: null), the same as a provider outage, because reconnecting the account fixes it. They are listed below because a queued entry's failureReason and the failure-notification email still name them. PROVIDER_NOT_CONNECTED is the one credential code still rejected outright: with no connection at all, a retry has nothing to succeed against.

The message text is human-readable only, and is reworded without notice. When writing code, match on the error code, not the message.

List the queued uploads DataPipe is holding for an experiment, or download them. This is the endpoint behind the queued files panel on the dashboard, and the scriptable way to recover data that hasn't reached your storage provider.

Unlike the three participant endpoints, this one is authenticated. Send a Firebase ID token for the account that owns the experiment as Authorization: Bearer <token>. Anything other than GET gets 405.

With no download or downloadAll, the response is 200 with an entries array and a count, newest first. Each entry carries id, filename, dataType, status, errorCode, retryCount, maxRetries, createdAt, lastAttemptAt, nextRetryAt, and failureReason. Only entries that are pending, processing, or failed are listed. A completed upload leaves the queue.

{
  "entries": [
    {
      "id": "abc123_subject01.csv",
      "filename": "subject01.csv",
      "dataType": "data",
      "status": "pending",
      "errorCode": 503,
      "retryCount": 2,
      "maxRetries": 5,
      "createdAt": "2026-08-22T14:03:11.000Z",
      "lastAttemptAt": "2026-08-22T17:03:44.000Z",
      "nextRetryAt": "2026-08-22T21:03:44.000Z",
      "failureReason": "Provider error 503: Service Unavailable"
    }
  ],
  "count": 1
}

Start finalizing an experiment: merge everything in its storage into one archive and permanently stop accepting submissions. This is the endpoint behind the Finalize control on the dashboard.

Authenticated the same way as queue status: Authorization: Bearer <token> for the owning account. Anything other than POST gets 405.

The response doesn't tell you the outcome. Merging a whole study takes longer than the 60-second request ceiling, so a successful call returns 202 with { "status": "queued" } and the work runs in the background. Watch the experiment's dashboard, which reports queued, then running, then the result. Calling again while a pass is in flight returns 202 with the current status rather than starting a second one.

Statuses the dashboard reports

The outcome lands on the experiment record. These are all the possible statuses:

What finalizing does to your files, and which providers support it. Finishing a study