Async APIHarnessesRoute-accurate reference

Research Harness API

The public API accepts Research work asynchronously. Each API-key mutation returns an accepted thread/run identity, while durable execution and product reads continue outside the initial HTTP request.

Manage API keys

Stable public contract

Authentication

API key

Send x-api-key or a Bearer API key with research:write permission.

Mutation safety

Idempotent

Every POST requires an Idempotency-Key so a retry returns the original work.

Response

202 Accepted

The route acknowledges durable admission; it does not wait for research to finish.

1. Implemented route inventory

Method	Path	Purpose
POST	/research/run	Create a new persistent thread and its first asynchronous run.
POST	/research/threads/{thread_id}/run	Add a focused prompt to an owned thread.
POST	/research/runs/{run_id}/continue	Resume a partial, failed, or credit-exhausted run.
DELETE	/api/research/threads/{thread_id}/artifacts/{artifact_id}	Soft-delete an artifact through an authenticated browser session.

There are currently no documented public API GET routes for Research threads, runs, sources, or artifacts. Product reads occur through the authenticated application surface; do not build polling against an invented endpoint.

2. Create a thread or add a prompt

Use `POST /research/run` to create a new persistent thread with its first run. Use `POST /research/threads/{thread_id}/run` when a new question should join an existing owned collection. Both routes accept the same JSON request shape and require `Idempotency-Key`.

Send either `x-api-key: vb_live_...` or `Authorization: Bearer vb_live_...`, plus a JSON content type. The API key must carry `research:write`.

Field	Type	Required	Current contract
prompt	string	Required	The research question; 1–20,000 characters.
size	small \| medium \| large	Optional	Preset source targets: 15, 50, or 100.
target_sources	integer	Optional	Explicit source target from 1 through 1,000.
search_calls	integer	Optional	Bounded discovery call target from 1 through 100.
resource_kinds	paper[] \| web[]	Optional	One or both implemented discovery surfaces.
source_sites	string[]	Optional	Advisory reviewed-source preferences; unknown values are ignored.
include_domains / exclude_domains	string[]	Optional	Hostname-only hard allowlist or exclusion filters.
published_after / language	string	Optional	ISO date and language controls for discovery.
reference_artifact_ids	string[]	Optional	Up to 15 explicit durable artifacts to use as research context.

cURL

Create a Research thread

curl -X POST "https://vidbyte-backend.onrender.com/research/run" \
  -H "x-api-key: $VIDBYTE_API_KEY" \
  -H "Idempotency-Key: research-competitor-landscape-001" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Map the evidence and competitive landscape for AI tutoring",
    "size": "small",
    "resource_kinds": ["paper", "web"],
    "language": "en"
  }'

3. Handle the accepted response

A successful mutation returns `202 Accepted` after it has durably admitted the work and emitted the execution event. Store both identifiers: `thread_id` names the long-lived collection and `run_id` names this one execution envelope.

JSON

202 Accepted

{
  "thread_id": "rth_...",
  "run_id": "rrn_...",
  "status": "accepted"
}

4. Continue or curate research

Use `POST /research/runs/{run_id}/continue` with the same API-key and idempotency headers after a partial, failed, or credit-exhausted run can proceed. It preserves the run identity and uses durable membership to avoid recomputing ready artifacts.

Artifact deletion is intentionally separate: `DELETE /api/research/threads/{thread_id}/artifacts/{artifact_id}` is a browser-session route for the verified owner, not an API-key route.