Append a run to a thread

Add a new prompt and asynchronous run to an existing owned Research thread.

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

API keyAPI key with research:write

Required boundary headers

x-api-key or Authorization: BearerIdempotency-Key

Overview

What this route does

Use the encrypted thread token returned by create or portfolio reads to continue an investigation without creating a second 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/v1/research/threads/rth_public_token/run" \
  -H "x-api-key: $VIDBYTE_API_KEY" \
  -H "Idempotency-Key: research-append-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Compare the strongest counter-evidence"}'

Example response

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

Response

Response and errors

Returns 202 Accepted with the existing encrypted_id and the new run_id.
Prior artifact bodies are not automatically injected into the next model context.