Research a Company or Person by URL
Queues a run that researches the company, Product, Service, or person at url and writes its aVenture profile, owned by the caller. A url a current record owns enriches that record; any other url researches a new one, so this is how to add a subject that POST /v1/lookup answers NO_MATCH (CLI: lookup). Send name when known. A new run spends one company or person research unit; a run already queued or running for the same subject is returned instead, uncharged. A url that matches more than one record answers 409, and a spent allowance 429. Check progress with GET /v1/harness/runs/{runId} (CLI: harness runs get); the caller is notified when the run completes. Without an admin credential a caller may set only url, name, model, mode, userPrompt, and taskPresetKey; any other field is refused with 403, and a userPrompt longer than 2000 characters is refused with 400. An admin bearer credential files a run it owns with any field; an admin API key files one owned by the back-end’s Clerk machine.
Authentication
Your aVenture API key (https://aventure.vc/settings/api-keys) or OAuth access token
Request
Official website or profile URL of the company, Product, Service, or person to research; a URL no current record owns researches a new one
Optional orchestrator model override; omitted uses the configured role default
Name of the subject at url, such as Clarity Health; the run verifies it and uses it to pick the right subject when the site names several
Response headers
Requests allowed per client IP in the current rate-limit window.
Requests left before the tightest applicable rate-limit bucket rejects.
Seconds until the exhausted rate-limit bucket admits another request; 0 when none is exhausted.
Response
True when the chassis router, not a caller, picked chassis
Parallel read-only scout fan-out width N
Read-only research, cohort, and completion sub-agent model id
Run kind derived from task-key presence: ENRICHMENT for a client-submitted comprehensive or preset-scoped run, TASK for a platform-scheduled micro-task execution
Typed terminal-failure class from the harness retry classifier (e.g. runtime_cap, escalated, provider_capacity, context_overflow); null unless failed
Latest enrich-loop status as an opaque JSON string
Earliest re-claim time when waiting on retry backoff
Instant past which a warm resume is no longer guaranteed; the harness writes it with session_resume from the model's cache window. Warm-resumable now iff failed/stopped and this is in the future. Null when there is no resume window.