beta

HTTP API reference

Generated from the OpenAPI document the API itself produces (Alive Healthtech API 1.0.0-beta). The machine-readable document is in the repository at contracts/openapi.json, and the typed TypeScript client @alive/sdk is generated from it.

Base URL: https://api.alivehealthtech.com (pilot access only during development). Authenticate with Authorization: Bearer <token>: a signed-in session or an API token. Errors always look like {code, message, details, request_id}; see errors and limits.

Public (no account needed)

GET/v1/healthpublic

Health

POST/v1/intakes/validatepublic

Validate Intake

GET/v1/modelspublic

Versioned model catalog. Proprietary implementation code is never included.

Parameters: category? (query, string | null)

GET/v1/models/{ref}public

Get Model

Parameters: ref (path, string)

GET/v1/prompts/{kind}public

Get Prompt

Parameters: kind (path, string)

GET/v1/schemas/{name}/{version}public

Get Schema

Parameters: name (path, string) · version (path, string)

POST/v1/world-specs/validatepublic

Schema, semantic and safety validation with resolved model locks. Never executes.

Projects, intake and plans

POST/v1/intakes/extractauth

Read and screen material without any AI call. Nothing is stored.

files?	string[] \| null
text?	string \| null

GET/v1/projectsauth

List Projects

Parameters: org_id? (query, string | null)

POST/v1/projectsauthIdempotency-Key

Create Project

org_id?	string \| null
title	string

GET/v1/projects/{project_id}auth

Get Project

Parameters: project_id (path, string)

GET/v1/projects/{project_id}/context/exportauth

Portable, minimal context manifest for another AI agent (spec §4).

Parameters: project_id (path, string)

POST/v1/projects/{project_id}/evaluation-plansauth

Create Plan

Parameters: project_id (path, string)

byok?	boolean
intake_revision?	integer \| null

GET/v1/projects/{project_id}/evaluation-plans/{plan_id}auth

Get Plan

Parameters: project_id (path, string) · plan_id (path, string)

POST/v1/projects/{project_id}/evaluation-plans/{plan_id}/approveauth

Approve one scope (paid inference, staging access, or execution) separately.

Parameters: project_id (path, string) · plan_id (path, string)

budget_limit_credits?	integer \| null
scope	ApprovalScope

POST/v1/projects/{project_id}/intakesauthIdempotency-Key

Save Intake

Parameters: project_id (path, string)

confirm?	boolean
intake	object
origin?	string

POST/v1/projects/{project_id}/intakes/parseauth

Draft an IntakeSpec with bounded AI. The draft is NOT saved; the user confirms it first.

Parameters: project_id (path, string)

byok_provider?	ProviderName \| null
evaluation_goal?	string \| null
external_ai_approved	boolean
files?	string[] \| null
text?	string \| null

GET/v1/projects/{project_id}/intakes/{revision}auth

Get Intake

Parameters: project_id (path, string) · revision (path, integer)

Worlds, runs and reviews

POST/v1/experiments/compareauth

Read stored paired comparisons from one completed run; never launch new work. Variants were executed together with common random numbers. Unrelated runs are not assumed comparable. Partial results retain the actual pair counts and null intervals.

run_id

string

POST/v1/projects/{project_id}/reviewsauthIdempotency-Key

Create Review

Parameters: project_id (path, string)

budget_limit_credits	integer
byok_provider?	ProviderName \| null
plan_id	string

POST/v1/projects/{project_id}/worldsauth

Store an immutable WorldSpec revision after full validation.

Parameters: project_id (path, string)

spec

object

GET/v1/reviews/{review_id}auth

Get Review

Parameters: review_id (path, string)

POST/v1/runsauthIdempotency-Key

Validate, reserve credits and queue a run. An explicit budget is the user's approval.

approval_id?	string \| null
budget_limit_credits	integer
world_revision_id	string

POST/v1/runs/estimateauth

Estimate Run

world_revision_id

string

GET/v1/runs/{run_id}auth

Get Run

Parameters: run_id (path, string)

POST/v1/runs/{run_id}/cancelauth

Cancel Run

Parameters: run_id (path, string)

GET/v1/runs/{run_id}/eventsauth

Run Events

Parameters: run_id (path, string) · variant? (query, string | null) · replication? (query, integer | null) · event_type? (query, string | null) · offset? (query, integer) · limit? (query, integer)

GET/v1/runs/{run_id}/exportauth

Run Export

Parameters: run_id (path, string)

GET/v1/runs/{run_id}/resultsauth

Run Results

Parameters: run_id (path, string)

GET/v1/world-revisions/{world_revision_id}auth

Get World

Parameters: world_revision_id (path, string)

Account, tokens and credits

GET/v1/credits/balanceauth

Credit Balance

Parameters: org_id? (query, string | null)

GET/v1/meauth

GET/v1/orgs/{org_id}/provider-keysauth

List Provider Keys

Parameters: org_id (path, string)

POST/v1/orgs/{org_id}/provider-keysauth

Add Provider Key

Parameters: org_id (path, string)

api_key	string
label	string
provider	ProviderName

DELETE/v1/orgs/{org_id}/provider-keys/{key_id}auth

Revoke Provider Key

Parameters: org_id (path, string) · key_id (path, string)

POST/v1/research/consentauth

Give Consent

level	string
org_id	string
policy_version	string
project_id?	string \| null

GET/v1/tokensauth

List Tokens

POST/v1/tokensauth

Create a scoped token for the CLI/SDK. The secret is returned once and never stored.

expires_in_days?	integer
name	string
org_id	string
scopes?	string[]

DELETE/v1/tokens/{token_id}auth

Revoke Token

Parameters: token_id (path, string)