Create a workspace run

Create a durable Research thread and first run from the authenticated browser workspace.

POST/api/research/run

Browser sessionAuthenticated browser session

Required boundary headers

Cookie: authenticated browser sessionIdempotency-Key

Overview

What this route does

This is the session equivalent of the public create route. The browser submits the same bounded request policy, while authentication and owner identity come from the session boundary.

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/run" \
  -H "Cookie: authenticated-session" \
  -H "Idempotency-Key: workspace-run-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Review evidence for a workspace question"}'

Example response

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

Response

Response and errors

Returns 202 Accepted with encrypted_id, run_id, and status.
The session owner is derived from authentication, never from request fields.