Create a Research run

Create a persistent thread and admit its first asynchronous Research run.

POST/api/v1/research/run

API keyAPI key with research:write

Required boundary headers

x-api-key or Authorization: BearerIdempotency-Key

Overview

What this route does

Use this route when a new investigation needs its own durable thread. The service validates the request, admits bounded work, and returns before discovery finishes.

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/run" \
  -H "x-api-key: $VIDBYTE_API_KEY" \
  -H "Idempotency-Key: research-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Map evidence for AI tutoring","resource_kinds":["paper","web"]}'

Example response

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

Response

Response and errors

Returns 202 Accepted with encrypted_id, run_id, and status.
The run executes asynchronously after durable admission.