API reference

Generated from the OpenAPI schema (app v0.2.0) by tools/gen_api_reference.py — do not edit by hand.

Auth: management endpoints (/api/*) take Authorization: Bearer fnp_… (personal access token, minted under avatar → API tokens). The public runtime (/v1/*) takes a per-function invoke key (fnk_…). Python SDK: fnai.Client (management) / fnai.Function (runtime).

New to the API? Start with the SDK quickstart; credential kinds are explained in sdk-auth.md.

functions

Functions, versions, lifecycle (submit/approve), playground.

`GET /api/functions`

list_functions — List Functions

parameter	in	type	required
`include_archived`	query	boolean	no

Returns: list of FunctionOut

`POST /api/functions`

create_function — Create Function

Request body: FunctionCreate

Returns: FunctionOut

`DELETE /api/functions/{fn_id}`

archive_function — Archive Function

Archive, not hard delete — versions, experiments, and traces are evidence and stay.

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`GET /api/functions/{fn_id}`

get_function — Get Function

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: FunctionOut

`PATCH /api/functions/{fn_id}`

patch_function — Patch Function

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: FunctionPatch

Returns: FunctionOut

`GET /api/functions/{fn_id}/types`

function_types — Function Types

fn types — caller-side types (TS interface / Python TypedDict) for the function’s contract. Prefers the ACTIVE deployment’s version (exactly what /v1 validates against), else the latest version, else fn-level schemas.

parameter	in	type	required
`fn_id`	path	integer	yes
`lang`	query	string	no

Returns: TypesOut

`GET /api/functions/{fn_id}/versions`

list_versions — List Versions

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of VersionOut

`POST /api/functions/{fn_id}/versions`

create_version — Create Version

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: VersionCreate

Returns: VersionOut

`GET /api/me`

me — Me

Returns: MeOut

`PUT /api/me/default-space`

set_default_space — Set Default Space

Personal preference — where this user lands on sign-in. Any member may set their own; the space must belong to the current account.

Request body: DefaultSpaceSet

Returns: DefaultSpaceOut

`GET /api/overview`

overview — Overview

Scope-aware landing data. Account-level roles (or platform admin) get per-space aggregates; space-level users get their space’s stats only. Aggregation temporarily re-points the RLS space GUC per space — legitimate, because the space list itself is derived from the user’s account rights.

Returns: OverviewOut

`GET /api/platform/overview`

platform_overview — Platform Overview

Vendor dashboard: every org with spaces/users/functions/experiments/spend. Aggregates by re-pointing the RLS GUCs per tenant+space — platform staff have no ambient data access; this endpoint is their explicit, guarded window.

Returns: JSON (shape documented in the handler)

`GET /api/platform/prompts`

list_platform_prompts — List Platform Prompts

Returns: list of PromptBriefOut

`POST /api/platform/prompts`

create_platform_prompt — Create Platform Prompt

Request body: JSON object

Returns: PromptCreatedOut

`GET /api/platform/users`

platform_users — Platform Users

Vendor console: every user with their org/space memberships. Filterable by org name and free-text (email/name). Platform staff only.

parameter	in	type	required
`account`	query	any	no
`q`	query	any	no

Returns: JSON (shape documented in the handler)

`POST /api/spaces`

create_space — Create Space

First-run onboarding: an org admin creates a space in their account. Account-scoped admin roles cover every space in the account, so no per-space membership is minted here.

Request body: SpaceCreate

Returns: SpaceCreatedOut

`GET /api/versions/{v_id}`

get_version — Get Version

parameter	in	type	required
`v_id`	path	integer	yes

Returns: VersionOut

`PUT /api/versions/{v_id}`

update_version — Update Version

parameter	in	type	required
`v_id`	path	integer	yes

Request body: VersionUpdate

Returns: VersionOut

`POST /api/versions/{v_id}/approve`

approve_version — Approve Version

parameter	in	type	required
`v_id`	path	integer	yes

Request body: ApproveRequest

Returns: VersionOut

`GET /api/versions/{v_id}/artifact`

get_artifact — Get Artifact

The compiled artifact — the exact executable form; also the future export bundle. Compiles on demand for versions saved before the compiler existed (drafts persist it).

parameter	in	type	required
`v_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`POST /api/versions/{v_id}/reject`

reject_version — Reject Version

Send a submitted version back to draft with a comment — the other half of the gate.

parameter	in	type	required
`v_id`	path	integer	yes

Request body: RejectRequest

Returns: VersionOut

`POST /api/versions/{v_id}/submit`

submit_version — Submit Version

parameter	in	type	required
`v_id`	path	integer	yes

Returns: VersionOut

scores

Per-function score library (checks/judges) and gate flags.

`GET /api/functions/{fn_id}/scores`

list_scores — List Scores

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of ScoreOut

`POST /api/functions/{fn_id}/scores`

create_score — Create Score

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: ScoreCreate

Returns: ScoreOut

`DELETE /api/scores/{score_id}`

delete_score — Delete Score

parameter	in	type	required
`score_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`PATCH /api/scores/{score_id}/gate`

toggle_gate — Toggle Gate

parameter	in	type	required
`score_id`	path	integer	yes

Request body: GatePatch

Returns: ScoreOut

planner

Measurement catalogue, plans, gate → plan → accept.

`GET /api/catalogue`

get_catalogue — Get Catalogue

The measurement catalogue as data — the browser groups these by dimension.

Returns: list of CatalogueEntryOut

`GET /api/functions/{fn_id}/plans`

list_plans — List Plans

Runnable plans for a function — a plan is a named collection of checks that an experiment can pin. Returns accepted plans (those with materialised checks) first.

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of PlanBriefOut

`POST /api/functions/{fn_id}/plans`

create_manual_plan — Create Manual Plan

A hand-built plan: an empty named collection of checks (add checks via the browser).

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: JSON object

Returns: PlanCreatedOut

`DELETE /api/plans/{plan_id}`

delete_plan — Delete Plan

Remove a plan and its checks (accept is non-idempotent, so duplicates happen). Checks referenced by past experiment results are detached into the library, not deleted.

parameter	in	type	required
`plan_id`	path	integer	yes

Returns: DeletePlanOut

`PATCH /api/plans/{plan_id}`

rename_plan — Rename Plan

parameter	in	type	required
`plan_id`	path	integer	yes

Request body: JSON object

Returns: PlanCreatedOut

`POST /api/plans/{plan_id}/accept`

accept_plan — Accept Plan

Turn the SELECTED proposed checks into Eval rows the harness will execute. body.indices picks a subset of plan.checks (all of them if omitted). Blocking checks become gates. Idempotency is the caller’s concern — re-accepting adds again.

parameter	in	type	required
`plan_id`	path	integer	yes

Request body: JSON object

Returns: AcceptPlanOut

`POST /api/plans/{plan_id}/clone`

clone_plan — Clone Plan

Copy a plan and its scores into a new named plan.

parameter	in	type	required
`plan_id`	path	integer	yes

Request body: JSON object

Returns: PlanCreatedOut

`GET /api/plans/{plan_id}/scores`

plan_scores — Plan Scores

parameter	in	type	required
`plan_id`	path	integer	yes

Returns: list of ScoreOut

`POST /api/plans/{plan_id}/scores`

add_plan_score — Add Plan Score

Add a score to a plan from the catalogue. body: {check, target, gate, params:{…}}.

parameter	in	type	required
`plan_id`	path	integer	yes

Request body: JSON object

Returns: ScoreOut

`DELETE /api/plans/{plan_id}/scores/{score_id}`

remove_plan_score — Remove Plan Score

parameter	in	type	required
`plan_id`	path	integer	yes
`score_id`	path	integer	yes

Returns: RemovePlanScoreOut

`POST /api/versions/{v_id}/gate`

run_gate — Run Gate

parameter	in	type	required
`v_id`	path	integer	yes

Returns: PlanOut

`GET /api/versions/{v_id}/plan`

get_plan — Get Plan

parameter	in	type	required
`v_id`	path	integer	yes

Returns: PlanOut

`POST /api/versions/{v_id}/plan`

run_plan — Run Plan

parameter	in	type	required
`v_id`	path	integer	yes

Request body: JSON object

Returns: PlanOut

experiments

Experiments over versions × models × repeats; findings.

`DELETE /api/experiments/{exp_id}`

delete_experiment — Delete Experiment

parameter	in	type	required
`exp_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`GET /api/experiments/{exp_id}`

get_experiment — Get Experiment

parameter	in	type	required
`exp_id`	path	integer	yes

Returns: ExperimentOut

`PATCH /api/experiments/{exp_id}`

patch_experiment — Patch Experiment

Rename and/or edit pins. Only drafts (queued, not yet run) may change pins.

parameter	in	type	required
`exp_id`	path	integer	yes

Request body: ExperimentPatch

Returns: ExperimentOut

`POST /api/experiments/{exp_id}/clone`

clone_experiment — Clone Experiment

Copy pins into a new draft. Finished experiments stay immutable.

parameter	in	type	required
`exp_id`	path	integer	yes

Returns: ExperimentOut

`GET /api/experiments/{exp_id}/findings`

list_findings — List Findings

parameter	in	type	required
`exp_id`	path	integer	yes

Returns: list of FindingOut

`POST /api/experiments/{exp_id}/run`

run_saved_experiment — Run Saved Experiment

Run a draft experiment once. After it finishes, clone to run again.

parameter	in	type	required
`exp_id`	path	integer	yes

Returns: ExperimentOut

`POST /api/findings/{finding_id}/add-score`

add_score_from_finding — Add Score From Finding

parameter	in	type	required
`finding_id`	path	integer	yes

Returns: ScoreOut

`POST /api/functions/import/one-shot-agent`

import_one_shot_agent — Import One Shot Agent

Request body: ImportRequest

Returns: ImportResultOut

`GET /api/functions/{fn_id}/experiments`

list_experiments — List Experiments

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of ExperimentOut

`POST /api/functions/{fn_id}/experiments`

create_experiment — Create Experiment

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: ExperimentCreate

Returns: ExperimentOut

`GET /api/functions/{fn_id}/score-results`

score_results — Score Results

Flexible cross-experiment view over the raw score-results fact table.

Default grain: one row per (version × model × temperature × score) aggregated across ALL of the function’s experiments — mean / std / pass_rate / n — so the client can rank, pivot and filter however it likes. RLS scopes every joined table to the caller’s space. Optional ?score=NAME narrows to one score for a per-score leaderboard.

Comparison controls:

?experiment_ids=1,2 restricts the aggregation to those experiments;
?group_by=experiment adds experiment identity to the grain, so “score X in experiment A vs experiment B” is answerable side by side.

Caveat: the default grain mixes inputs across experiments, so it isolates model/version only when those experiments shared inputs — n and experiments are returned so the caller can judge comparability.

parameter	in	type	required
`fn_id`	path	integer	yes
`score`	query	any	no
`experiment_ids`	query	any	no
`group_by`	query	any	no

Returns: list of ScoreResultOut

`GET /api/tools`

list_tools — List Tools

Returns: list of ToolInfoOut

`POST /api/versions/{v_id}/playground/run`

playground_run — Playground Run

parameter	in	type	required
`v_id`	path	integer	yes

Request body: PlaygroundRun

Returns: PlaygroundOut

datasets

Datasets, rows, snapshots, uploads.

`DELETE /api/datasets/{ds_id}`

delete_dataset — Delete Dataset

Hard delete — only when no experiment pins a snapshot of this dataset; archive otherwise.

parameter	in	type	required
`ds_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`PATCH /api/datasets/{ds_id}`

patch_dataset — Patch Dataset

parameter	in	type	required
`ds_id`	path	integer	yes

Request body: DatasetPatch

Returns: DatasetOut

`GET /api/datasets/{ds_id}/rows`

list_rows — List Rows

parameter	in	type	required
`ds_id`	path	integer	yes

Returns: list of RowOut

`POST /api/datasets/{ds_id}/rows`

add_row — Add Row

parameter	in	type	required
`ds_id`	path	integer	yes

Request body: RowIn

Returns: RowOut

`POST /api/datasets/{ds_id}/snapshot`

snapshot_dataset — Snapshot Dataset

parameter	in	type	required
`ds_id`	path	integer	yes

Request body: JSON object

Returns: SnapshotOut

`GET /api/datasets/{ds_id}/snapshots`

list_snapshots — List Snapshots

Version history: every frozen snapshot, newest first, with the experiments pinning it.

parameter	in	type	required
`ds_id`	path	integer	yes

Returns: list of SnapshotHistoryOut

`POST /api/datasets/{ds_id}/upload`

upload_rows — Upload Rows

Bulk-load rows from a spreadsheet. Mapping is explicit — columns are never guessed. Values are coerced to the types declared by the function’s input schema (latest version’s schema, falling back to the function-level one).

parameter	in	type	required
`ds_id`	path	integer	yes

Request body: JSON object

Returns: UploadResultOut

`GET /api/functions/{fn_id}/datasets`

list_datasets — List Datasets

parameter	in	type	required
`fn_id`	path	integer	yes
`include_archived`	query	boolean	no

Returns: list of DatasetOut

`POST /api/functions/{fn_id}/datasets`

create_dataset — Create Dataset

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: DatasetCreate

Returns: DatasetOut

`DELETE /api/rows/{row_id}`

delete_row — Delete Row

parameter	in	type	required
`row_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`PATCH /api/rows/{row_id}`

update_row — Update Row

parameter	in	type	required
`row_id`	path	integer	yes

Request body: RowUpdate

Returns: RowOut

deployments

Deploy/rollback/history + per-function invoke keys (fnk_*).

`POST /api/functions/{fn_id}/deploy`

deploy — Deploy

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: JSON object

Returns: DeploymentOut

`GET /api/functions/{fn_id}/deployment`

current_deployment — Current Deployment

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: DeploymentOut

`GET /api/functions/{fn_id}/deployments`

deployment_history — Deployment History

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of DeploymentOut

`GET /api/functions/{fn_id}/invoke-keys`

list_api_keys — List Api Keys

parameter	in	type	required
`fn_id`	path	integer	yes

Returns: list of InvokeKeyOut

`POST /api/functions/{fn_id}/invoke-keys`

create_api_key — Create Api Key

Mints fnk_<32 hex>; the plaintext appears ONCE in this response and is never retrievable again — only its SHA-256 is stored.

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: JSON object

Returns: InvokeKeyMintedOut

`POST /api/functions/{fn_id}/rollback`

rollback — Rollback

Re-point to a prior version. Default target: the most recently deployed version different from the current one; or pass {version_id} explicitly.

parameter	in	type	required
`fn_id`	path	integer	yes

Request body: JSON object

Returns: DeploymentOut

`DELETE /api/invoke-keys/{key_id}`

revoke_api_key — Revoke Api Key

parameter	in	type	required
`key_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

traces

Trace explorer, function health, flag-to-dataset flywheel.

`GET /api/functions/{fn_id}/health`

function_health — Function Health

The ‘is my function okay?’ rollup, computed from traces in the window: calls, error rate, p50/p95 latency, spend — total and per source/version.

parameter	in	type	required
`fn_id`	path	integer	yes
`window_hours`	query	integer	no

Returns: HealthOut

`GET /api/traces`

list_traces — List Traces

parameter	in	type	required
`function_id`	query	any	no
`source`	query	any	no
`limit`	query	integer	no

Returns: list of TraceSummaryOut

`GET /api/traces/{trace_id}`

get_trace — Get Trace

parameter	in	type	required
`trace_id`	path	string	yes

Returns: TraceDetailOut

`POST /api/traces/{trace_id}/flag`

flag_trace — Flag Trace

The flywheel button: a (bad) production output becomes a regression-test row. Lands in the function’s ‘{FLAG_DATASET_NAME}’ dataset (auto-created), input preserved verbatim, expected left EMPTY — the user fills in what the output SHOULD have been.

parameter	in	type	required
`trace_id`	path	string	yes

Returns: TraceFlagOut

costs

Model price catalogue and spend summaries.

`GET /api/costs/catalogue`

get_catalog — Get Catalog

Returns: list of PriceOut

`GET /api/costs/summary`

get_summary — Get Summary

Spend for the current scope (RLS does the filtering): totals + per model/source.

Returns: CostSummaryOut

keys

BYOK provider keys (org/space scope) — model calls run on these.

`GET /api/provider-keys`

list_keys — List Keys

Returns: list of KeyOut

`POST /api/provider-keys`

create_key — Create Key

Request body: KeyCreate

Returns: KeyOut

`GET /api/provider-keys/console`

keys_console — Keys Console

The org admin’s master view: every key in the account — org-wide keys plus each space’s keys (labeled). Account admins only.

Returns: ConsoleOut

`DELETE /api/provider-keys/{key_id}`

delete_key — Delete Key

parameter	in	type	required
`key_id`	path	integer	yes

Returns: JSON (shape documented in the handler)

`PATCH /api/provider-keys/{key_id}`

patch_key — Patch Key

parameter	in	type	required
`key_id`	path	integer	yes

Request body: KeyPatch

Returns: KeyOut

`POST /api/provider-keys/{key_id}/assign`

assign_key — Assign Key

Org-admin control over which space owns a key: move it between spaces, promote to org-wide, or demote to one space. RLS makes a space→space move a two-step dance (source-space GUC → org-wide, target-space GUC → target).

parameter	in	type	required
`key_id`	path	integer	yes

Request body: KeyAssign

Returns: KeyOut

`POST /api/provider-keys/{key_id}/rotate`

rotate_key — Rotate Key

parameter	in	type	required
`key_id`	path	integer	yes

Request body: KeyRotate

Returns: KeyOut

`POST /api/provider-keys/{key_id}/test`

test_key — Test Key

parameter	in	type	required
`key_id`	path	integer	yes

Returns: KeyTestOut

auth

Sign-in coordinates + personal access tokens (fnp_*).

`GET /api/auth/config`

auth_config — Auth Config

Returns: AuthConfigOut

`GET /api/auth/tokens`

list_tokens — List Tokens

The caller’s own tokens — hashes never leave the store.

Returns: list of TokenOut

`POST /api/auth/tokens`

mint_token — Mint Token

Mint a personal access token. The plaintext is in this response ONLY.

Request body: JSON object

Returns: TokenMintedOut

`DELETE /api/auth/tokens/{token_id}`

revoke_token — Revoke Token

Revoke (keeps the row for audit). Own tokens only — others 404.

parameter	in	type	required
`token_id`	path	string	yes

Returns: JSON (shape documented in the handler)

run

Public runtime surface (/v1) — invoke key auth, not PAT.

`POST /v1/run/{fn_slug}`

run — Run

parameter	in	type	required
`fn_slug`	path	string	yes

Request body: JSON object

Returns: RunOut

`GET /v1/run/{fn_slug}/contract`

contract — Contract

Contract discovery for callers: the input/output schemas of the ACTIVE deployment — exactly what POST /v1/run validates against. Same auth and 404 semantics as the invoke path; the contract changes atomically with deploys and rollbacks.

parameter	in	type	required
`fn_slug`	path	string	yes

Returns: ContractOut

untagged

`GET /api/health`

health — Health

Returns: JSON (shape documented in the handler)