Append a workspace run

Append a prompt to a browser-session-owned Research thread.

POST/api/research/threads/{encrypted_id}/run

Browser sessionAuthenticated browser session

Required boundary headers

Cookie: authenticated browser sessionIdempotency-Key

Overview

What this route does

Use the encrypted thread token in the workspace when the next prompt belongs to the current evidence collection.

Contract

Request parameters

Request body

Only fields in this contract are accepted.

promptRequiredstring

Research question, from 1 through 20,000 characters.

request_schema_versionOptional1 | 2

Request contract version. Use version 2 when sending reference_artifact_ids.

Default: 2

sizeOptionalsmall | medium | large

Preset source and search-call targets.

target_sourcesOptionalinteger

Explicit source target from 1 through 1,000.

search_callsOptionalinteger

Discovery-call target from 1 through 100.

resource_kindsOptionalpaper[] | web[]

One or both implemented discovery surfaces.

Default: ["paper", "web"]

source_sitesOptionalstring[]

Advisory reviewed-source preferences; unknown values may be ignored.

include_domainsOptionalstring[]

Reviewed hostname-only allowlist, maximum 50 values.

exclude_domainsOptionalstring[]

Hostname-only exclusions, maximum 50 values; cannot overlap include_domains.

published_afterOptionalYYYY-MM-DD

Calendar-valid publication date filter.

languageOptionalstring

Language preference from 2 through 12 characters.

Default: en

max_run_cost_centsOptionalinteger

Run cap from 1 through 100,000 cents.

provider_keysOptionalstring[]

Optional server-side provider-key references; never place raw credentials in public requests.

reference_artifact_idsOptionalencrypted_id[]

Up to 15 unique public artifact tokens; requires request_schema_version 2.

Examples

Request and response

Example request

curl -X POST "https://vidbyte-backend.onrender.com/api/research/threads/rth_public_token/run" \
  -H "Cookie: authenticated-session" \
  -H "Idempotency-Key: workspace-append-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Investigate one remaining gap"}'

Example response

{
  "encrypted_id": "rth_public_token",
  "run_id": "rrun_workspace_append",
  "status": "accepted"
}

Response

Response and errors

Returns 202 Accepted with the existing encrypted_id and new run_id.
The route accepts public encrypted identifiers only.