API reference

Three limits apply to every request, and none of them is configurable per experiment.

• 32 MB per request. Enforced by the server infrastructure and not raisable. A typical jsPsych dataset is 50 KB to 5 MB, so this bites mainly on base64 media. Gzipped request bodies are decompressed transparently, which effectively raises the ceiling for text data.
• 60 seconds per request. Every /api/* path runs behind a hosting layer with a hard 60-second ceiling. It is why /api/finalize returns immediately and does its work in the background rather than answering when the job is done.
• JSON bodies only. Send Content-Type: application/json. The three participant endpoints do not 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

Save a text file (CSV, JSON, etc.) to your experiment's storage. If you have validation rules configured, 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 are produced, rather than only at the end. A participant who abandons the experiment partway then leaves behind a recoverable partial session instead of nothing at all.

You will not usually call this directly — the jsPsychPipe plugin does it for you, along with the staging writes that follow. It is documented because those writes go to a Firebase Realtime Database rather than to this API, and this response is what tells a client where.

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 consume one from that limit — the count is still taken when a submission completes. A 503 with SESSION_START_ERROR means incremental upload is unavailable and the experiment should simply submit at the end, as it would otherwise.

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

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 a missing number is tolerated rather than treated 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 sequentially (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

Codes beginning OSF_ are historical names kept for backward compatibility. OSF_FILE_EXISTS, OSF_UPLOAD_ERROR and OSF_UPLOAD_EXCEPTION are returned for every storage provider, not only OSF. INVALID_OSF_TOKEN and INVALID_REFRESH_TOKEN occur only on experiments still collecting to OSF.

The same applies to the message text: several messages still name OSF whatever provider an experiment actually uses — a queued upload reports “Data received. OSF upload will be retried automatically” on Google Drive, Dataverse, and Zenodo alike. Read “OSF” in a message as “your storage provider”, and match on the error code rather than the message when you are writing code.

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 has not 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 is answered 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 is answered 405.

The response does not 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. The full vocabulary is:

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