API reference
Use Authorization: Bearer <key>.
API problem responses
Every non-success response includes a stable type, a safe message, and an actionable remediation. Retry only when the
remediation says it is safe, and reuse the same idempotency key for a retried mutation.
Agent quickstart
/mcp
and REST use the same API key. Mutating MCP calls require Idempotency-Key.
- Call
list_models. - Call
list_model_concepts. - Create and validate a dataset.
- Create and confirm a quote.
- Retrieve Report v2 (when requested), then the report.
Unrated coverage is not a calibrated claim.
Proba Agent API · 1.9.0
| Operation | Method | Path | Operation ID | Required scope | MCP tool |
|---|---|---|---|---|---|
| Get the organization credit balance and a snapshot-bound ledger page | GET | /v1/credits |
get_credits |
read |
yes |
| Create Stripe Checkout for one explicitly configured credit-pack SKU | POST | /v1/credits/purchases |
purchase_credits |
jobs:write |
no |
| List datasets owned by the authenticated organization | GET | /v1/datasets |
list_datasets |
read |
no |
| Create a direct dataset or a tenant-scoped signed-upload intent | POST | /v1/datasets |
create_dataset |
jobs:write |
yes |
| Get one organization-owned dataset | GET | /v1/datasets/{id} |
get_dataset |
read |
yes |
| Verify a signed upload and idempotently enqueue validation | POST | /v1/datasets/{id}/finalize |
finalize_dataset |
jobs:write |
yes |
| Resolve accepted canonical rows by 0-based index (at most 100 per request) | GET | /v1/datasets/{id}/rows |
get_dataset_rows |
read |
yes |
| Get a pinned SAE feature-group names document cited by Report v2, byte for byte | GET | /v1/feature_group_names/{version} |
get_feature_group_names |
read |
no |
| Get a pinned SAE feature-group table cited by Report v2, byte for byte | GET | /v1/feature_group_tables/{version} |
get_feature_group_table |
read |
no |
| Get operator-published candidate labels (automated hypotheses, not validated) for anonymous SAE export feature indices | GET | /v1/feature_labels |
get_feature_labels |
read |
yes |
| List jobs owned by the authenticated organization | GET | /v1/jobs |
list_jobs |
read |
no |
| Create a quote and immutable manifest for an evaluation job | POST | /v1/jobs |
create_job |
jobs:write |
yes |
| Get one organization-owned job | GET | /v1/jobs/{id} |
get_job |
read |
yes |
| Get short-lived tenant-checked URLs for a succeeded job's artifacts | GET | /v1/jobs/{id}/artifacts |
get_job_artifacts |
read |
yes |
| Confirm a quoted job and dispatch it exactly once | POST | /v1/jobs/{id}/confirm |
confirm_job |
jobs:write |
yes |
| Get the immutable canonical report bytes for a succeeded job | GET | /v1/jobs/{id}/report |
get_report |
read |
yes |
| Get Report v2 for a succeeded job: the findings document, signed links to its five documents, and its feature-group table | GET | /v1/jobs/{id}/report_v2 |
get_report_v2 |
read |
yes |
| Get the rows with the largest raw chosen-minus-rejected deltas per concept and primitive | GET | /v1/jobs/{id}/row_contributions |
get_job_row_contributions |
read |
yes |
| Get per-concept, per-primitive sign counts and order statistics of the stored raw deltas | GET | /v1/jobs/{id}/row_stats |
get_job_row_stats |
read |
yes |
| Get a per-checkpoint descriptive aggregation of the anonymous SAE feature export with candidate labels joined | GET | /v1/jobs/{id}/sae_feature_summary |
get_job_sae_feature_summary |
read |
yes |
| List models in the active immutable catalog projection | GET | /v1/models |
list_models |
read |
yes |
| List readable coverage facts for one active-catalog model | GET | /v1/models/{id}/concepts |
list_model_concepts |
read |
yes |
| Compare 2-5 succeeded jobs' reports side by side; reads are never averaged or ranked | GET | /v1/report_comparisons |
get_report_comparison |
read |
yes |
| List delivery obligations and append-only attempt metadata | GET | /v1/webhook_deliveries |
list_webhook_deliveries |
read |
no |
| Create a new obligation for one dead-lettered delivery | POST | /v1/webhook_deliveries/{id}/replay |
replay_webhook_delivery |
jobs:write |
no |
| List organization-owned outbound webhook endpoints | GET | /v1/webhook_endpoints |
list_webhook_endpoints |
read |
no |
| Create an outbound webhook endpoint and issue its signing secret once | POST | /v1/webhook_endpoints |
create_webhook_endpoint |
jobs:write |
no |
| Disable an outbound webhook endpoint | POST | /v1/webhook_endpoints/{id}/disable |
disable_webhook_endpoint |
jobs:write |
no |
OpenAPI document
{
"openapi": "3.1.0",
"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
"info": {
"title": "Proba Agent API",
"version": "1.9.0",
"description": "The implemented, organization-scoped launch surface. Configured credit-pack Checkout and webhook administration are REST-only and never MCP tools; raw pricing, provider credentials, storage references, and product caps are not exposed."
},
"servers": [{"url": "/"}],
"security": [{"ProductApiKey": []}],
"x-aurelius-blocked-operations": [
{"operationId": "get_price_or_cap", "reason": "Production prices, credit conversion, and workload caps are unresolved STOP items."}
],
"paths": {
"/v1/models": {
"get": {
"operationId": "list_models",
"summary": "List models in the active immutable catalog projection",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ModelPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/models/{id}/concepts": {
"get": {
"operationId": "list_model_concepts",
"summary": "List readable coverage facts for one active-catalog model",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConceptPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/datasets": {
"get": {
"operationId": "list_datasets",
"summary": "List datasets owned by the authenticated organization",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/DatasetPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
},
"post": {
"operationId": "create_dataset",
"summary": "Create a direct dataset or a tenant-scoped signed-upload intent",
"description": "Direct JSON Lines validate synchronously. A signed upload returns an exact PUT request and remains pending_upload until finalized.",
"x-mcp-description": "Create a direct dataset or a tenant-scoped signed-upload intent. Every JSONL row must contain exactly prompt, chosen, and rejected as non-empty strings. index is assigned only to row-read responses and is rejected during ingest.",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateDatasetRequest"}}}},
"responses": {
"201": {"description": "Dataset created and validated", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Dataset"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/datasets/{id}": {
"get": {
"operationId": "get_dataset",
"summary": "Get one organization-owned dataset",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {"description": "Dataset", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Dataset"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/datasets/{id}/finalize": {
"post": {
"operationId": "finalize_dataset",
"summary": "Verify a signed upload and idempotently enqueue validation",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"$ref": "#/components/parameters/IdempotencyKey"}
],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}},
"responses": {
"200": {"description": "Upload accepted for asynchronous validation", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Dataset"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/datasets/{id}/rows": {
"get": {
"operationId": "get_dataset_rows",
"summary": "Resolve accepted canonical rows by 0-based index (at most 100 per request)",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"name": "indices", "in": "query", "required": true, "description": "Comma-separated 0-based indices into the accepted canonical rows; at most 100, each below the dataset's canonical pair count.", "schema": {"type": "string"}}
],
"responses": {
"200": {
"description": "The requested accepted canonical rows, exactly as validated",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/DatasetRows"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs": {
"get": {
"operationId": "list_jobs",
"summary": "List jobs owned by the authenticated organization",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
},
"post": {
"operationId": "create_job",
"summary": "Create a quote and immutable manifest for an evaluation job",
"description": "Production quote price and workload caps remain disabled; the current implementation is explicitly fixture-gated.",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateJobRequest"}}}},
"responses": {
"201": {"description": "Quoted job with frozen quote and manifest", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateJobResponse"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}": {
"get": {
"operationId": "get_job",
"summary": "Get one organization-owned job",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {"description": "Job", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Job"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/confirm": {
"post": {
"operationId": "confirm_job",
"summary": "Confirm a quoted job and dispatch it exactly once",
"description": "This can spend only already-verified credits or an explicitly configured payment fallback; it never exposes purchase or credential operations.",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"$ref": "#/components/parameters/IdempotencyKey"}
],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}},
"responses": {
"200": {"description": "Confirmed job", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConfirmJobResponse"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/report": {
"get": {
"operationId": "get_report",
"summary": "Get the immutable canonical report bytes for a succeeded job",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"x-aurelius-canonical-bytes": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {
"description": "The stored App-F canonical report bytes; the server does not re-encode them",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"type": "object"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/report_v2": {
"get": {
"operationId": "get_report_v2",
"summary": "Get Report v2 for a succeeded job: the findings document, signed links to its five documents, and its feature-group table",
"description": "Built after the job succeeds for jobs that requested the SAE export. Reads are organization-scoped and audited. The signed links expire, so the response is never cached. A report_findings/v2 document names its feature groups; those names are machine-generated from public feature labels and are not validated.",
"x-mcp-description": "Get Report v2 for a succeeded job: the findings document (the whole-dataset feature-group table and up to five findings, each with a template headline and evidence row ids), short-lived signed links to its five documents, and the version and digest of the feature-group table it cites. In a report_findings/v2 document every finding and whole-dataset row also carries feature_group_name and name_source: a name whose name_source is namer is machine-generated from public feature labels and not validated, so always quote it with its feature group id and that caveat (feature_groups.names.note). When a job requested the SAE export (options.include_full_sae_feature_deltas=true), call this first after the job succeeds, then get_report. report_v2_pending means the build is still running: retry shortly. report_v2_unavailable means the job has no Report v2: use get_report. Resolve evidence row ids with get_dataset_rows.",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {
"description": "The decoded findings document with its digest, five signed document links, and the pinned feature-group table reference",
"headers": {
"Cache-Control": {"schema": {"type": "string", "const": "private, no-store"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReportV2"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/artifacts": {
"get": {
"operationId": "get_job_artifacts",
"summary": "Get short-lived tenant-checked URLs for a succeeded job's artifacts",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {"description": "Backend-independent signed artifact URLs; private storage is streamed through an expiring product API capability", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/JobArtifacts"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/row_contributions": {
"get": {
"operationId": "get_job_row_contributions",
"summary": "Get the rows with the largest raw chosen-minus-rejected deltas per concept and primitive",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{
"name": "top_k",
"in": "query",
"required": false,
"description": "Maximum nonzero rows selected per primitive before increase/decrease grouping. Defaults to 10; pass the job's canonical pair count to retrieve every nonzero row contribution.",
"schema": {"type": "integer", "minimum": 1}
}
],
"responses": {
"200": {
"description": "Derived top-delta rows per (concept, primitive); reads are never pooled across method families and carry no causal claim",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RowContributions"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/row_stats": {
"get": {
"operationId": "get_job_row_stats",
"summary": "Get per-concept, per-primitive sign counts and order statistics of the stored raw deltas",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [{"$ref": "#/components/parameters/Id"}],
"responses": {
"200": {
"description": "Descriptive sign counts and nearest-rank order statistics per (concept, primitive); distribution values are verbatim matrix decimals, never pooled across method families, and carry no quality, significance, or causal claim",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RowStats"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/jobs/{id}/sae_feature_summary": {
"get": {
"operationId": "get_job_sae_feature_summary",
"summary": "Get a per-checkpoint descriptive aggregation of the anonymous SAE feature export with candidate labels joined",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{
"name": "checkpoint",
"in": "query",
"required": false,
"schema": {"enum": ["gemma-scope-2-12b-it-resid-post-l24-width-65k-l0-medium", "gemma-scope-2-12b-it-resid-post-l31-width-65k-l0-medium"]},
"description": "Summarize only this frozen checkpoint; default summarizes both, separately and never pooled."
},
{
"name": "top_n",
"in": "query",
"required": false,
"schema": {"type": "integer", "minimum": 1, "maximum": 100},
"description": "Features returned per scope, ranked by row appearance count (default 25)."
},
{
"name": "groups",
"in": "query",
"required": false,
"schema": {"type": "string", "pattern": "^[a-z0-9_-]{1,32}:[0-9]+(,[0-9]+)*(;[a-z0-9_-]{1,32}:[0-9]+(,[0-9]+)*)*$"},
"description": "Read-time row-group mapping, e.g. contaminated:0,3,17;clean:1,2 — at most 8 groups and 200 disjoint dataset_row indices; ungrouped rows are reported as an explicit remainder. Never frozen into the manifest."
}
],
"responses": {
"200": {
"description": "Descriptive counts of top-k feature appearances per checkpoint with candidate labels (automated hypotheses) joined in the response only; the artifact itself stays anonymous by contract and the output carries no quality, significance, or causal claim",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/SaeFeatureSummary"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/feature_labels": {
"get": {
"operationId": "get_feature_labels",
"summary": "Get operator-published candidate labels (automated hypotheses, not validated) for anonymous SAE export feature indices",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{
"name": "checkpoint",
"in": "query",
"required": true,
"description": "One of the two frozen export checkpoint ids.",
"schema": {
"enum": [
"gemma-scope-2-12b-it-resid-post-l24-width-65k-l0-medium",
"gemma-scope-2-12b-it-resid-post-l31-width-65k-l0-medium"
]
}
},
{
"name": "indices",
"in": "query",
"required": true,
"description": "1-100 comma-separated anonymous source_feature_index values from the export artifact.",
"schema": {"type": "string", "pattern": "^[0-9]+(,[0-9]+)*$"}
}
],
"responses": {
"200": {
"description": "Candidate labels keyed by anonymous source feature index; unlabeled indices return explicit nulls. Labels never enter the export artifact, the canonical report, or the catalog.",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/FeatureLabels"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/feature_group_tables/{version}": {
"get": {
"operationId": "get_feature_group_table",
"summary": "Get a pinned SAE feature-group table cited by Report v2, byte for byte",
"description": "Serves the write-once table named by a Report v2 response's feature_groups.table_version, verified against its pinned digest. REST-only: the table is too large for a tool payload.",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [{"$ref": "#/components/parameters/TableVersion"}],
"responses": {
"200": {
"description": "The pinned feature-group table bytes, verbatim; the ETag is their sha256 digest",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"type": "object"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/feature_group_names/{version}": {
"get": {
"operationId": "get_feature_group_names",
"summary": "Get a pinned SAE feature-group names document cited by Report v2, byte for byte",
"description": "Serves the write-once names document named by a Report v2 response's feature_groups.names.names_version, verified against its pinned digest. Every name, description and keyword in it is machine-generated from public feature labels and is not validated. REST-only, like get_feature_group_table.",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [{"$ref": "#/components/parameters/NamesVersion"}],
"responses": {
"200": {
"description": "The pinned feature-group names document bytes, verbatim; the ETag is their sha256 digest",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private, immutable"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/FeatureGroupNamesDocument"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/report_comparisons": {
"get": {
"operationId": "get_report_comparison",
"summary": "Compare 2-5 succeeded jobs' reports side by side; reads are never averaged or ranked",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"name": "job_ids", "in": "query", "required": true, "description": "Comma-separated ids of 2 to 5 succeeded jobs belonging to the organization. All jobs must share the manifest-pinned model revision, catalog version, aggregation policy, report schema, and concept set.", "schema": {"type": "string"}}
],
"responses": {
"200": {
"description": "Derived side-by-side comparison of the selected jobs' canonical reports",
"headers": {
"ETag": {"schema": {"type": "string"}},
"Cache-Control": {"schema": {"type": "string", "const": "private"}}
},
"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReportComparison"}}}
},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/credits": {
"get": {
"operationId": "get_credits",
"summary": "Get the organization credit balance and a snapshot-bound ledger page",
"x-aurelius-scope": "read",
"x-mcp-tool": true,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "Credit balance and ledger page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Credits"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/credits/purchases": {
"post": {
"operationId": "purchase_credits",
"summary": "Create Stripe Checkout for one explicitly configured credit-pack SKU",
"description": "Credits are not granted by this response. They enter the append-only ledger only after a signature-verified, replay-protected provider webhook confirms this exact order.",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": false,
"parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreditPurchaseRequest"}}}},
"responses": {
"201": {"description": "Configured Checkout Session created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreditPurchase"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/webhook_endpoints": {
"get": {
"operationId": "list_webhook_endpoints",
"summary": "List organization-owned outbound webhook endpoints",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound endpoint page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpointPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
},
"post": {
"operationId": "create_webhook_endpoint",
"summary": "Create an outbound webhook endpoint and issue its signing secret once",
"description": "The raw secret is derived from the operator keyring and endpoint identity. It is returned only on the first successful call and is never persisted, including in the idempotency record.",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": false,
"parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateWebhookEndpointRequest"}}}},
"responses": {
"201": {"description": "Endpoint created; secret is present only when secret_returned is true", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpoint"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/webhook_endpoints/{id}/disable": {
"post": {
"operationId": "disable_webhook_endpoint",
"summary": "Disable an outbound webhook endpoint",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"$ref": "#/components/parameters/IdempotencyKey"}
],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}},
"responses": {
"200": {"description": "Disabled endpoint", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEndpoint"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/webhook_deliveries": {
"get": {
"operationId": "list_webhook_deliveries",
"summary": "List delivery obligations and append-only attempt metadata",
"x-aurelius-scope": "read",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Cursor"},
{"$ref": "#/components/parameters/Limit"}
],
"responses": {
"200": {"description": "One snapshot-bound delivery page", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDeliveryPage"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
},
"/v1/webhook_deliveries/{id}/replay": {
"post": {
"operationId": "replay_webhook_delivery",
"summary": "Create a new obligation for one dead-lettered delivery",
"x-aurelius-scope": "jobs:write",
"x-mcp-tool": false,
"parameters": [
{"$ref": "#/components/parameters/Id"},
{"$ref": "#/components/parameters/IdempotencyKey"}
],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false}}}},
"responses": {
"201": {"description": "Replay obligation queued", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookDelivery"}}}},
"default": {"$ref": "#/components/responses/Problem"}
}
}
}
},
"components": {
"securitySchemes": {
"ProductApiKey": {"type": "http", "scheme": "bearer", "bearerFormat": "Aurelius organization API key"}
},
"parameters": {
"Id": {"name": "id", "in": "path", "required": true, "schema": {"type": "string", "format": "uuid"}},
"Cursor": {"name": "cursor", "in": "query", "required": false, "description": "Opaque, snapshot-bound cursor", "schema": {"type": "string"}},
"Limit": {"name": "limit", "in": "query", "required": false, "description": "Page-size hint; the server may cap it", "schema": {"type": "integer", "minimum": 1}},
"TableVersion": {"name": "version", "in": "path", "required": true, "description": "A feature-group table version, as returned in a Report v2 response's feature_groups.table_version", "schema": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"}},
"NamesVersion": {"name": "version", "in": "path", "required": true, "description": "A feature-group names version, as returned in a Report v2 response's feature_groups.names.names_version", "schema": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"}},
"IdempotencyKey": {"name": "Idempotency-Key", "in": "header", "required": true, "schema": {"type": "string", "minLength": 1, "maxLength": 255}}
},
"responses": {
"Problem": {"description": "C0 problem", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}
},
"schemas": {
"Problem": {
"type": "object",
"additionalProperties": false,
"required": ["type", "message", "remediation", "doc_url"],
"properties": {
"type": {"type": "string"},
"message": {"type": "string"},
"remediation": {"type": "string"},
"doc_url": {"type": "string", "format": "uri"},
"details": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["path", "keyword"],
"properties": {
"path": {"type": "string"},
"keyword": {"type": "string"}
}
}
}
}
},
"PageCursor": {"type": ["string", "null"], "description": "Opaque cursor or null at the end"},
"Model": {
"type": "object",
"required": ["id", "model_ref", "revision", "display_name", "concept_count", "readable_concept_count", "primitive_count"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"model_ref": {"type": "string"},
"revision": {"type": "string"},
"display_name": {"type": "string"},
"concept_count": {"type": "integer"},
"readable_concept_count": {"type": "integer"},
"primitive_count": {"type": "integer"}
}
},
"ModelPage": {
"type": "object",
"required": ["catalog_version", "data", "next_cursor"],
"properties": {"catalog_version": {"type": "string"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/Model"}}, "next_cursor": {"$ref": "#/components/schemas/PageCursor"}}
},
"ConceptPage": {
"type": "object",
"required": ["catalog_version", "model", "data", "next_cursor"],
"additionalProperties": false,
"properties": {"catalog_version": {"type": "string"}, "model": {"$ref": "#/components/schemas/ModelIdentity"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/ConceptCoverage"}}, "next_cursor": {"$ref": "#/components/schemas/PageCursor"}}
},
"ConceptCoverage": {
"type": "object",
"additionalProperties": false,
"required": ["concept_id", "display_name", "description", "calibration_tier", "status", "primitive_count", "method_family_counts", "provenance_counts", "primitive_result_refs", "quality_floor"],
"properties": {
"concept_id": {"type": "string", "minLength": 1},
"display_name": {"type": "string", "minLength": 1},
"description": {"type": "string", "minLength": 1},
"calibration_tier": {"type": "string", "enum": ["unrated", "tier_a", "tier_b", "tier_c"]},
"status": {"type": "string", "enum": ["readable", "unreadable"]},
"primitive_count": {"type": "integer", "minimum": 0},
"method_family_counts": {"$ref": "#/components/schemas/StringCounts"},
"provenance_counts": {"$ref": "#/components/schemas/ProvenanceCounts"},
"primitive_result_refs": {"type": "array", "items": {"type": "string", "pattern": "^res_[0-9a-f]{64}$"}, "uniqueItems": true},
"quality_floor": {"$ref": "#/components/schemas/QualityFloor"}
}
},
"StringCounts": {
"type": "object",
"additionalProperties": {"type": "integer", "minimum": 0}
},
"ProvenanceCounts": {
"type": "object",
"additionalProperties": false,
"properties": {
"operator_curated": {"type": "integer", "minimum": 0},
"subnet_validated": {"type": "integer", "minimum": 0}
}
},
"QualityFloor": {
"type": "object",
"additionalProperties": false,
"required": ["intrinsic", "consumption_contract"],
"properties": {
"intrinsic": {"type": ["string", "null"], "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"consumption_contract": {"type": ["string", "null"], "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"}
}
},
"ModelIdentity": {
"type": "object",
"required": ["id", "model_ref", "revision", "display_name"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"model_ref": {"type": "string"},
"revision": {"type": "string"},
"display_name": {"type": "string"}
}
},
"CreateDatasetRequest": {
"type": "object",
"additionalProperties": false,
"properties": {
"jsonl": {
"type": "string",
"contentMediaType": "application/x-ndjson",
"description": "UTF-8 JSON Lines. Every non-empty line must conform to DatasetIngestRow; index is a server-assigned readback field and is not accepted.",
"examples": ["{\"prompt\":\"Compare these answers\",\"chosen\":\"The supported answer\",\"rejected\":\"The unsupported answer\"}\n"],
"x-aurelius-jsonl-row-schema": {"$ref": "#/components/schemas/DatasetIngestRow"}
},
"upload": {"$ref": "#/components/schemas/DatasetUploadIntent"}
},
"oneOf": [
{"required": ["jsonl"]},
{"required": ["upload"]}
]
},
"DatasetUploadIntent": {
"type": "object",
"additionalProperties": false,
"required": ["byte_count", "sha256", "content_type", "ttl_seconds"],
"properties": {
"byte_count": {"type": "integer", "minimum": 1},
"sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"content_type": {"type": "string", "const": "application/x-ndjson"},
"ttl_seconds": {"type": "integer", "minimum": 1}
}
},
"SignedUpload": {
"type": "object",
"additionalProperties": false,
"required": ["url", "method", "headers", "expires_at", "byte_count", "sha256"],
"properties": {
"url": {"type": "string", "format": "uri"},
"method": {"type": "string", "const": "PUT"},
"headers": {"type": "object", "additionalProperties": {"type": "string"}},
"expires_at": {"type": "string", "format": "date-time"},
"byte_count": {"type": "integer", "minimum": 1},
"sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
}
},
"Dataset": {
"type": "object",
"required": ["id", "status", "canonical_pair_count", "validation_report_ref", "validation_report"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"status": {"type": "string", "enum": ["pending_upload", "processing", "valid", "invalid"]},
"content_hash": {"type": ["string", "null"]},
"canonical_pair_count": {"type": "integer"},
"validation_report_ref": {"type": "string"},
"validation_report": {"type": ["object", "null"]},
"upload": {"$ref": "#/components/schemas/SignedUpload"}
}
},
"DatasetPage": {
"type": "object",
"required": ["data", "next_cursor"],
"properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Dataset"}}, "next_cursor": {"$ref": "#/components/schemas/PageCursor"}}
},
"DatasetIngestRow": {
"type": "object",
"description": "One JSON object per input line for direct or signed dataset ingest.",
"additionalProperties": false,
"required": ["prompt", "chosen", "rejected"],
"properties": {
"prompt": {"type": "string", "minLength": 1},
"chosen": {"type": "string", "minLength": 1},
"rejected": {"type": "string", "minLength": 1}
}
},
"DatasetRow": {
"type": "object",
"description": "A server-indexed row returned by GET /v1/datasets/{id}/rows. This is not the dataset ingest-row shape.",
"additionalProperties": false,
"required": ["index", "prompt", "chosen", "rejected"],
"properties": {
"index": {"type": "integer", "minimum": 0},
"prompt": {"type": "string", "minLength": 1},
"chosen": {"type": "string", "minLength": 1},
"rejected": {"type": "string", "minLength": 1}
}
},
"DatasetRows": {
"type": "object",
"additionalProperties": false,
"required": ["dataset_id", "content_hash", "rows"],
"properties": {
"dataset_id": {"type": "string", "format": "uuid"},
"content_hash": {"type": "string"},
"rows": {"type": "array", "items": {"$ref": "#/components/schemas/DatasetRow"}}
}
},
"ModelSelection": {
"type": "object",
"additionalProperties": false,
"required": ["model_ref", "revision"],
"properties": {"model_ref": {"type": "string"}, "revision": {"type": "string"}}
},
"JobOptions": {
"type": "object",
"description": "Closed job options. The SAE export is opt-in, applies only to the newly created job, and is never backfilled onto earlier jobs.",
"additionalProperties": false,
"properties": {
"include_raw_delta_matrix": {"type": "boolean", "default": true},
"include_full_sae_feature_deltas": {"type": "boolean", "default": false, "description": "When true, export the top 100 absolute signed chosen-minus-rejected deltas per pair at each of the fixed L24 and L31 checkpoints using last-non-padding-token semantics."},
"retention_policy_ref": {"type": "string", "minLength": 1}
}
},
"CreateJobRequest": {
"type": "object",
"additionalProperties": false,
"required": ["dataset_id", "model", "concept_set"],
"properties": {
"dataset_id": {"type": "string", "format": "uuid"},
"model": {"$ref": "#/components/schemas/ModelSelection"},
"concept_set": {"type": "array", "minItems": 1, "items": {"type": "string"}},
"options": {"$ref": "#/components/schemas/JobOptions"},
"parent_job_id": {"type": "string", "format": "uuid", "description": "Optional. Re-run on this job's prompt groups: a succeeded job of this organization whose Report v2 is ready. The new job must set options.include_full_sae_feature_deltas=true; its Report v2 grid lines up with the parent's. Refusals: parent_job_not_valid, parent_report_v2_unavailable, parent_report_v2_deleted, parent_job_requires_sae_export."}
}
},
"Job": {
"type": "object",
"required": ["id", "status", "dataset_id", "model", "concept_set", "mode", "options", "parent_job_id"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"status": {"type": "string", "enum": ["draft", "validating", "quoted", "confirmed", "queued", "running", "succeeded", "failed", "canceled"]},
"dataset_id": {"type": "string", "format": "uuid"},
"model": {"$ref": "#/components/schemas/ModelSelection"},
"concept_set": {"type": "array", "items": {"type": "string"}},
"mode": {"type": "string", "const": "operator_side"},
"options": {"$ref": "#/components/schemas/JobOptions"},
"payment_method": {"type": ["string", "null"]},
"failure_type": {"type": ["string", "null"]},
"parent_job_id": {"type": ["string", "null"], "format": "uuid", "description": "The job this job re-runs (create_job's parent_job_id), or null."}
}
},
"JobPage": {
"type": "object",
"required": ["data", "next_cursor"],
"properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Job"}}, "next_cursor": {"$ref": "#/components/schemas/PageCursor"}}
},
"CreateJobResponse": {
"type": "object",
"required": ["job", "quote", "manifest"],
"properties": {"job": {"$ref": "#/components/schemas/Job"}, "quote": {"type": "object"}, "manifest": {"type": "object"}}
},
"ConfirmJobResponse": {
"type": "object",
"required": ["job", "payment"],
"properties": {"job": {"$ref": "#/components/schemas/Job"}, "payment": {"type": "object"}}
},
"SignedArtifact": {
"type": "object",
"additionalProperties": false,
"required": ["url", "method", "headers", "expires_at", "byte_count", "sha256", "content_type"],
"properties": {
"url": {"type": "string", "format": "uri"},
"method": {"type": "string", "const": "GET"},
"headers": {"type": "object", "additionalProperties": {"type": "string"}},
"expires_at": {"type": "string", "format": "date-time"},
"byte_count": {"type": "integer", "minimum": 0},
"sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"content_type": {"type": "string", "minLength": 1}
}
},
"TopAbsSaeFeatureDeltaLabels": {
"type": "object",
"description": "Explicit machine-readable semantics for the opt-in feature-delta payload. Source feature indices are anonymous; no semantic labels or clusters are supplied.",
"additionalProperties": false,
"required": ["artifact_kind", "artifact_schema_version", "export_profile_id", "top_k", "ranking", "tie_break", "pair_operation", "token_selector", "feature_identity", "semantic_labels", "clustering", "checkpoint_ids"],
"properties": {
"artifact_kind": {"type": "string", "const": "top_abs_sae_feature_deltas"},
"artifact_schema_version": {"type": "string", "const": "0.3.0"},
"export_profile_id": {"type": "string", "const": "gemma-scope-2-12b-it-l24-l31-top100-abs-signed-last-token-v1"},
"top_k": {"type": "integer", "const": 100},
"ranking": {"type": "string", "const": "absolute_signed_delta_descending"},
"tie_break": {"type": "string", "const": "source_feature_index_ascending"},
"pair_operation": {"type": "string", "const": "chosen_minus_rejected"},
"token_selector": {"type": "string", "const": "last_non_padding"},
"feature_identity": {"type": "string", "const": "anonymous_source_feature_index"},
"semantic_labels": {"type": "string", "const": "none"},
"clustering": {"type": "string", "const": "none"},
"checkpoint_ids": {
"type": "array",
"prefixItems": [
{"type": "string", "const": "gemma-scope-2-12b-it-resid-post-l24-width-65k-l0-medium"},
{"type": "string", "const": "gemma-scope-2-12b-it-resid-post-l31-width-65k-l0-medium"}
],
"items": false,
"minItems": 2,
"maxItems": 2
}
}
},
"LabeledTopAbsSaeFeatureDeltaArtifact": {
"type": "object",
"additionalProperties": false,
"required": ["url", "method", "headers", "expires_at", "byte_count", "sha256", "content_type", "labels"],
"properties": {
"url": {"type": "string", "format": "uri"},
"method": {"type": "string", "const": "GET"},
"headers": {"type": "object", "additionalProperties": {"type": "string"}},
"expires_at": {"type": "string", "format": "date-time"},
"byte_count": {"type": "integer", "minimum": 0},
"sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"content_type": {"type": "string", "minLength": 1},
"labels": {"$ref": "#/components/schemas/TopAbsSaeFeatureDeltaLabels"}
}
},
"JobArtifacts": {
"type": "object",
"additionalProperties": false,
"required": ["delta_matrix"],
"properties": {
"delta_matrix": {"$ref": "#/components/schemas/SignedArtifact"},
"top_abs_sae_feature_deltas": {"$ref": "#/components/schemas/LabeledTopAbsSaeFeatureDeltaArtifact"}
}
},
"ReportV2": {
"type": "object",
"description": "Report v2 of one succeeded job (ADR-0326): the decoded findings document, its digest, short-lived signed links to the five stored documents, and the feature-group table the findings cite. The findings are report_findings/v1 (feature groups shown as \"Feature group N\") or report_findings/v2 (ADR-0327), whose feature groups carry machine-generated names that are not validated; feature_groups.names references the pinned names a v2 document cites and is null for v1.",
"additionalProperties": false,
"required": ["job_id", "findings_sha256", "findings", "documents", "feature_groups"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"findings_sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"findings": {"oneOf": [{"$ref": "#/components/schemas/ReportV2Findings"}, {"$ref": "#/components/schemas/ReportV2FindingsV2"}]},
"documents": {"$ref": "#/components/schemas/ReportV2Documents"},
"feature_groups": {"$ref": "#/components/schemas/ReportV2FeatureGroups"}
},
"if": {"required": ["findings"], "properties": {"findings": {"required": ["algorithm"], "properties": {"algorithm": {"const": "report_findings/v2"}}}}},
"then": {"properties": {"feature_groups": {"properties": {"names": {"$ref": "#/components/schemas/ReportV2FeatureGroupNames"}}}}},
"else": {"properties": {"feature_groups": {"properties": {"names": {"type": "null"}}}}}
},
"ReportV2Documents": {
"type": "object",
"description": "Signed downloads of the five Report v2 documents: findings.json, grid.json, grid-row-scores.json, prompt-groups.json and prompt-group-model.json.",
"additionalProperties": false,
"required": ["findings", "grid", "row_scores", "prompt_groups", "prompt_group_model"],
"properties": {
"findings": {"$ref": "#/components/schemas/SignedArtifact"},
"grid": {"$ref": "#/components/schemas/SignedArtifact"},
"row_scores": {"$ref": "#/components/schemas/SignedArtifact"},
"prompt_groups": {"$ref": "#/components/schemas/SignedArtifact"},
"prompt_group_model": {"$ref": "#/components/schemas/SignedArtifact"}
}
},
"ReportV2FeatureGroups": {
"type": "object",
"description": "The pinned feature-group table the findings cite; fetch it from path (get_feature_group_table). names references the pinned feature-group names a report_findings/v2 document cites (fetch them from names.path, get_feature_group_names), and is null for report_findings/v1.",
"additionalProperties": false,
"required": ["table_version", "table_sha256", "path", "names"],
"properties": {
"table_version": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"},
"table_sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"path": {"type": "string", "pattern": "^/v1/feature_group_tables/[A-Za-z0-9._+-]{1,256}$"},
"names": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ReportV2FeatureGroupNames"}]}
}
},
"ReportV2FeatureGroupNames": {
"type": "object",
"description": "The pinned feature-group names a report_findings/v2 document cites (ADR-0327): their version and digest, the path of get_feature_group_names, and the marking every name carries.",
"additionalProperties": false,
"required": ["names_version", "names_sha256", "path", "name_status", "note"],
"properties": {
"names_version": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"},
"names_sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"path": {"type": "string", "pattern": "^/v1/feature_group_names/[A-Za-z0-9._+-]{1,256}$"},
"name_status": {"type": "string", "const": "hypothesis"},
"note": {"type": "string", "const": "Machine-generated from public feature labels, not validated. A feature_group_name whose name_source is namer is a hypothesis: always show it with its feature group id and this caveat. Groups with too few labelled features, groups whose labels share no clear theme, and groups that could not be named keep the placeholder name \"Feature group N\" (name_source placeholder)."}
}
},
"ReportV2Findings": {
"type": "object",
"description": "The report_findings/v1 document (findings.json), unjudged or judged. Every number is an integer (ppm for fractions). An unjudged document has judged false, a null judge and null judgements; a judged one has the judge block.",
"additionalProperties": false,
"required": ["algorithm", "artifact_kind", "dataset_table", "findings", "inputs", "judge", "judged", "rules", "schema_version"],
"properties": {
"algorithm": {"type": "string", "const": "report_findings/v1"},
"artifact_kind": {"type": "string", "const": "report_findings"},
"dataset_table": {"type": "array", "maxItems": 10, "items": {"$ref": "#/components/schemas/ReportV2DatasetEntry"}},
"findings": {"type": "array", "maxItems": 5, "items": {"$ref": "#/components/schemas/ReportV2Finding"}},
"inputs": {"$ref": "#/components/schemas/ReportV2FindingsInputs"},
"judge": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ReportV2Judge"}]},
"judged": {"type": "boolean"},
"rules": {"$ref": "#/components/schemas/ReportV2FindingsRules"},
"schema_version": {"type": "string", "const": "1.0.0"}
},
"if": {"required": ["judged"], "properties": {"judged": {"const": false}}},
"then": {
"properties": {
"judge": {"type": "null"},
"findings": {"items": {"properties": {"judgement": {"type": "null"}}}}
}
},
"else": {"properties": {"judge": {"$ref": "#/components/schemas/ReportV2Judge"}}}
},
"ReportV2DatasetEntry": {
"type": "object",
"description": "One whole-dataset table row: a live feature group's mean, direction and sign-test badge.",
"additionalProperties": false,
"required": ["feature_group_id", "mean_ppm", "sign_sum", "direction", "present_count", "member_count", "rows_firing", "rows_leaning_chosen", "rows_leaning_rejected", "fire_ppm", "lean"],
"properties": {
"feature_group_id": {"type": "integer", "minimum": 1, "maximum": 500},
"mean_ppm": {"type": "integer"},
"sign_sum": {"type": "integer"},
"direction": {"type": "string", "enum": ["chosen", "rejected", "none"]},
"present_count": {"type": "integer", "minimum": 0},
"member_count": {"type": "integer", "minimum": 0},
"rows_firing": {"type": "integer", "minimum": 0},
"rows_leaning_chosen": {"type": "integer", "minimum": 0},
"rows_leaning_rejected": {"type": "integer", "minimum": 0},
"fire_ppm": {"type": "integer", "minimum": 0, "maximum": 1000000},
"lean": {"type": "string", "enum": ["chosen", "rejected", "balanced"]}
}
},
"ReportV2Finding": {
"type": "object",
"description": "One shortlisted (prompt topic, feature group) cell with its template headline, evidence row ids (0-based dataset rows) and optional judgement. rank is the shortlist rank, also in a judged document.",
"additionalProperties": false,
"required": ["rank", "prompt_group_id", "feature_group_id", "direction", "delta_ppm", "rows", "sign_sum", "present_count", "evidence_row_ids", "headline", "judgement"],
"properties": {
"rank": {"type": "integer", "minimum": 1, "maximum": 5},
"prompt_group_id": {"type": "integer", "minimum": 1},
"feature_group_id": {"type": "integer", "minimum": 1, "maximum": 500},
"direction": {"type": "string", "enum": ["chosen", "rejected"]},
"delta_ppm": {"type": "integer"},
"rows": {"type": "integer", "minimum": 1},
"sign_sum": {"type": "integer"},
"present_count": {"type": "integer", "minimum": 0},
"evidence_row_ids": {"type": "array", "maxItems": 5, "uniqueItems": true, "items": {"type": "integer", "minimum": 0}},
"headline": {"type": "string", "minLength": 1},
"judgement": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ReportV2FindingJudgement"}]}
}
},
"ReportV2FindingJudgement": {
"type": "object",
"description": "A judge's verdict on one finding; evidence_row_ids ascending, a subset of the finding's.",
"additionalProperties": false,
"required": ["verdict", "headline", "insight", "valence", "confidence_ppm", "evidence_row_ids"],
"properties": {
"verdict": {"type": "string", "enum": ["lesson", "style", "noise"]},
"headline": {"type": "string", "minLength": 1, "maxLength": 160},
"insight": {"type": "string", "minLength": 1, "maxLength": 1200},
"valence": {"type": "string", "enum": ["good", "harmful", "neutral"]},
"confidence_ppm": {"type": "integer", "minimum": 0, "maximum": 1000000},
"evidence_row_ids": {"type": "array", "minItems": 1, "maxItems": 5, "uniqueItems": true, "items": {"type": "integer", "minimum": 0}}
}
},
"ReportV2Judge": {
"type": "object",
"description": "Which judge answered, how, and the outcome counts (judged + failed + invalid = the number of findings).",
"additionalProperties": false,
"required": ["model_id", "model_digest", "prompt_version", "decoding", "judged", "failed", "invalid"],
"properties": {
"model_id": {"type": "string", "minLength": 1},
"model_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"prompt_version": {"type": "string", "minLength": 1},
"decoding": {
"type": "array",
"items": {
"type": "array",
"prefixItems": [{"type": "string", "minLength": 1}, {"type": "string", "minLength": 1}],
"items": false,
"minItems": 2,
"maxItems": 2
}
},
"judged": {"type": "integer", "minimum": 0},
"failed": {"type": "integer", "minimum": 0},
"invalid": {"type": "integer", "minimum": 0}
}
},
"ReportV2FindingsInputs": {
"type": "object",
"description": "What the findings were computed from: the grid, row-score and prompt-group document digests, the feature-group table, the dataset content hash and the export's job id.",
"additionalProperties": false,
"required": ["grid_digest", "row_scores_digest", "prompt_groups_digest", "table_version", "table_digest", "dataset_content_hash", "export_job_id"],
"properties": {
"grid_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"row_scores_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"prompt_groups_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"table_version": {"type": "string", "minLength": 1},
"table_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"dataset_content_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"export_job_id": {"type": "string", "minLength": 1}
}
},
"ReportV2FindingsRules": {
"type": "object",
"description": "The fixed shortlist and headline rules of report_findings/v1.",
"additionalProperties": false,
"required": ["candidate_limit", "dataset_top", "evidence_rows", "headline", "per_group_cap", "per_topic_cap", "shortlist"],
"properties": {
"candidate_limit": {"type": "integer", "const": 5},
"dataset_top": {"type": "integer", "const": 10},
"evidence_rows": {"type": "integer", "const": 5},
"headline": {"type": "string", "const": "template_headline/v1"},
"per_group_cap": {"type": "integer", "const": 2},
"per_topic_cap": {"type": "integer", "const": 2},
"shortlist": {"type": "string", "const": "report_shortlist/v1"}
}
},
"ReportV2FindingsV2": {
"type": "object",
"description": "The report_findings/v2 document (findings.json, ADR-0327), unjudged or judged: report_findings/v1 plus the pinned feature-group names it cites (inputs.names_version, inputs.names_digest) and each finding's and whole-dataset row's feature_group_name and name_source. A name whose name_source is namer is machine-generated from public feature labels and not validated; a placeholder keeps \"Feature group N\". Every number is an integer (ppm for fractions). An unjudged document has judged false, a null judge and null judgements; a judged one has the judge block.",
"additionalProperties": false,
"required": ["algorithm", "artifact_kind", "dataset_table", "findings", "inputs", "judge", "judged", "rules", "schema_version"],
"properties": {
"algorithm": {"type": "string", "const": "report_findings/v2"},
"artifact_kind": {"type": "string", "const": "report_findings"},
"dataset_table": {"type": "array", "maxItems": 10, "items": {"$ref": "#/components/schemas/ReportV2DatasetEntryV2"}},
"findings": {"type": "array", "maxItems": 5, "items": {"$ref": "#/components/schemas/ReportV2FindingV2"}},
"inputs": {"$ref": "#/components/schemas/ReportV2FindingsInputsV2"},
"judge": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ReportV2Judge"}]},
"judged": {"type": "boolean"},
"rules": {"$ref": "#/components/schemas/ReportV2FindingsRulesV2"},
"schema_version": {"type": "string", "const": "2.0.0"}
},
"if": {"required": ["judged"], "properties": {"judged": {"const": false}}},
"then": {
"properties": {
"judge": {"type": "null"},
"findings": {"items": {"properties": {"judgement": {"type": "null"}}}}
}
},
"else": {"properties": {"judge": {"$ref": "#/components/schemas/ReportV2Judge"}}}
},
"ReportV2DatasetEntryV2": {
"type": "object",
"description": "One report_findings/v2 whole-dataset table row: a live feature group's mean, direction and sign-test badge, with its pinned name. A name whose name_source is namer is machine-generated and not validated; a placeholder is \"Feature group N\".",
"additionalProperties": false,
"required": ["feature_group_id", "mean_ppm", "sign_sum", "direction", "present_count", "member_count", "rows_firing", "rows_leaning_chosen", "rows_leaning_rejected", "fire_ppm", "lean", "feature_group_name", "name_source"],
"properties": {
"feature_group_id": {"type": "integer", "minimum": 1, "maximum": 500},
"mean_ppm": {"type": "integer"},
"sign_sum": {"type": "integer"},
"direction": {"type": "string", "enum": ["chosen", "rejected", "none"]},
"present_count": {"type": "integer", "minimum": 0},
"member_count": {"type": "integer", "minimum": 0},
"rows_firing": {"type": "integer", "minimum": 0},
"rows_leaning_chosen": {"type": "integer", "minimum": 0},
"rows_leaning_rejected": {"type": "integer", "minimum": 0},
"fire_ppm": {"type": "integer", "minimum": 0, "maximum": 1000000},
"lean": {"type": "string", "enum": ["chosen", "rejected", "balanced"]},
"feature_group_name": {"type": "string", "minLength": 1, "maxLength": 80},
"name_source": {"type": "string", "enum": ["namer", "placeholder"]}
},
"if": {"required": ["name_source"], "properties": {"name_source": {"const": "placeholder"}}},
"then": {"properties": {"feature_group_name": {"pattern": "^Feature group [1-9][0-9]*$"}}}
},
"ReportV2FindingV2": {
"type": "object",
"description": "One report_findings/v2 shortlisted (prompt topic, feature group) cell with its template headline, evidence row ids (0-based dataset rows), optional judgement and the feature group's pinned name. A name whose name_source is namer is machine-generated and not validated: quote it with its feature group id. rank is the shortlist rank, also in a judged document.",
"additionalProperties": false,
"required": ["rank", "prompt_group_id", "feature_group_id", "direction", "delta_ppm", "rows", "sign_sum", "present_count", "evidence_row_ids", "headline", "judgement", "feature_group_name", "name_source"],
"properties": {
"rank": {"type": "integer", "minimum": 1, "maximum": 5},
"prompt_group_id": {"type": "integer", "minimum": 1},
"feature_group_id": {"type": "integer", "minimum": 1, "maximum": 500},
"direction": {"type": "string", "enum": ["chosen", "rejected"]},
"delta_ppm": {"type": "integer"},
"rows": {"type": "integer", "minimum": 1},
"sign_sum": {"type": "integer"},
"present_count": {"type": "integer", "minimum": 0},
"evidence_row_ids": {"type": "array", "maxItems": 5, "uniqueItems": true, "items": {"type": "integer", "minimum": 0}},
"headline": {"type": "string", "minLength": 1},
"judgement": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ReportV2FindingJudgement"}]},
"feature_group_name": {"type": "string", "minLength": 1, "maxLength": 80},
"name_source": {"type": "string", "enum": ["namer", "placeholder"]}
},
"if": {"required": ["name_source"], "properties": {"name_source": {"const": "placeholder"}}},
"then": {"properties": {"feature_group_name": {"pattern": "^Feature group [1-9][0-9]*$"}}}
},
"ReportV2FindingsInputsV2": {
"type": "object",
"description": "What report_findings/v2 findings were computed from: the grid, row-score and prompt-group document digests, the feature-group table, the dataset content hash, the export's job id and the pinned feature-group names (get_feature_group_names).",
"additionalProperties": false,
"required": ["grid_digest", "row_scores_digest", "prompt_groups_digest", "table_version", "table_digest", "dataset_content_hash", "export_job_id", "names_version", "names_digest"],
"properties": {
"grid_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"row_scores_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"prompt_groups_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"table_version": {"type": "string", "minLength": 1},
"table_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"dataset_content_hash": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"export_job_id": {"type": "string", "minLength": 1},
"names_version": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"},
"names_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
}
},
"ReportV2FindingsRulesV2": {
"type": "object",
"description": "The fixed shortlist and headline rules of report_findings/v2: those of report_findings/v1 with the named headline template_headline/v2.",
"additionalProperties": false,
"required": ["candidate_limit", "dataset_top", "evidence_rows", "headline", "per_group_cap", "per_topic_cap", "shortlist"],
"properties": {
"candidate_limit": {"type": "integer", "const": 5},
"dataset_top": {"type": "integer", "const": 10},
"evidence_rows": {"type": "integer", "const": 5},
"headline": {"type": "string", "const": "template_headline/v2"},
"per_group_cap": {"type": "integer", "const": 2},
"per_topic_cap": {"type": "integer", "const": 2},
"shortlist": {"type": "string", "const": "report_shortlist/v1"}
}
},
"FeatureGroupNamesDocument": {
"type": "object",
"description": "A write-once sae_feature_group_names document (ADR-0327 decision 7): one entry per feature group of the table it binds, with the label and namer provenance. Every title, description, keyword and note is machine-generated from public feature labels and is not validated (name_status hypothesis); a placeholder entry keeps \"Feature group N\". This schema is the published subset of the names codec's validation; the pinned, codec-verified bytes are authoritative.",
"additionalProperties": false,
"required": ["artifact_kind", "schema_version", "names_version", "name_status", "feature_group_table", "labels", "namer", "rules", "groups"],
"properties": {
"artifact_kind": {"type": "string", "const": "sae_feature_group_names"},
"schema_version": {"type": "string", "const": "1.0.0"},
"names_version": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"},
"name_status": {"type": "string", "const": "hypothesis"},
"feature_group_table": {
"type": "object",
"additionalProperties": false,
"required": ["table_version", "digest"],
"properties": {
"table_version": {"type": "string", "pattern": "^[A-Za-z0-9._+-]{1,256}$"},
"digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
}
},
"labels": {
"type": "object",
"description": "The public feature labels the names were generated from: the label table's version and digest, its source, the models that wrote the labels and the attribution.",
"additionalProperties": false,
"required": ["table_version", "digest", "source", "explanation_models", "attribution"],
"properties": {
"table_version": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$"},
"digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"source": {"type": "string", "enum": ["neuronpedia_export", "neuronpedia_import"]},
"explanation_models": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "minLength": 1, "maxLength": 120}},
"attribution": {"type": "string", "minLength": 1, "maxLength": 1000}
}
},
"namer": {
"type": "object",
"description": "The namer run: its model, prompt version and effort, the digest of its inputs, its submission ids and when it named the groups (UTC).",
"additionalProperties": false,
"required": ["model_id", "prompt_version", "effort", "inputs_digest", "batch_ids", "named_at"],
"properties": {
"model_id": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$"},
"prompt_version": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$"},
"effort": {"type": "string", "enum": ["none", "low", "medium", "high", "xhigh", "max"]},
"inputs_digest": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
"batch_ids": {"type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$"}},
"named_at": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"}
}
},
"rules": {
"type": "object",
"description": "The naming rules: a group is named only with at least min_labelled_members labelled members making at least min_labelled_ppm of its members; the namer's prompt carries at most sample_size labels; with placeholder_when_incoherent, a group whose labels share no clear theme keeps the placeholder.",
"additionalProperties": false,
"required": ["min_labelled_members", "min_labelled_ppm", "sample_size", "placeholder_when_incoherent"],
"properties": {
"min_labelled_members": {"type": "integer", "minimum": 1},
"min_labelled_ppm": {"type": "integer", "minimum": 0, "maximum": 1000000},
"sample_size": {"type": "integer", "minimum": 1, "maximum": 1000},
"placeholder_when_incoherent": {"type": "boolean"}
}
},
"groups": {"type": "array", "minItems": 1, "maxItems": 500, "items": {"$ref": "#/components/schemas/FeatureGroupName"}}
}
},
"FeatureGroupName": {
"type": "object",
"description": "One feature group's machine-generated name (name_source namer: a hypothesis, not validated) or its placeholder (name_source placeholder: \"Feature group N\", no description), with its keywords, the namer's notes and the member, labelled-member and prompt-feature counts.",
"additionalProperties": false,
"required": ["feature_group_id", "name_source", "title", "description", "keywords", "notes", "member_count", "labelled_count", "prompt_feature_count"],
"properties": {
"feature_group_id": {"type": "integer", "minimum": 1, "maximum": 500},
"name_source": {"type": "string", "enum": ["namer", "placeholder"]},
"title": {"type": "string", "minLength": 1, "maxLength": 80},
"description": {"type": ["string", "null"], "maxLength": 400},
"keywords": {"type": "array", "items": {"type": "string", "minLength": 1}},
"notes": {"type": ["string", "null"]},
"member_count": {"type": "integer", "minimum": 1},
"labelled_count": {"type": "integer", "minimum": 0},
"prompt_feature_count": {"type": "integer", "minimum": 0}
},
"if": {"required": ["name_source"], "properties": {"name_source": {"const": "placeholder"}}},
"then": {"properties": {"title": {"pattern": "^Feature group [1-9][0-9]*$"}}}
},
"ComparisonRead": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "direction", "aggregate_delta"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"direction": {"type": "string", "enum": ["increase", "decrease", "neutral", "undefined"]},
"aggregate_delta": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"}
}
},
"ComparisonCell": {
"type": "object",
"additionalProperties": false,
"required": ["method_family", "primitive_refs", "reads"],
"properties": {
"method_family": {"type": "string"},
"primitive_refs": {"type": "array", "items": {"type": "string"}},
"reads": {"type": "array", "items": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ComparisonRead"}]}}
}
},
"ComparisonConcept": {
"type": "object",
"additionalProperties": false,
"required": ["concept_id", "cells"],
"properties": {
"concept_id": {"type": "string"},
"cells": {"type": "array", "items": {"$ref": "#/components/schemas/ComparisonCell"}}
}
},
"ComparisonJob": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "report_id", "canonical_sha256", "generated_at", "dataset"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"report_id": {"type": "string"},
"canonical_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"generated_at": {"type": "string"},
"dataset": {
"type": "object",
"additionalProperties": false,
"required": ["dataset_id", "content_hash", "canonical_pair_count"],
"properties": {
"dataset_id": {"type": "string"},
"content_hash": {"type": "string"},
"canonical_pair_count": {"type": "integer", "minimum": 1}
}
}
}
},
"ComparisonCoverage": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "excluded_rows", "runtime_failures", "unreadable_concepts"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"excluded_rows": {"type": "integer", "minimum": 0},
"runtime_failures": {"type": "integer", "minimum": 0},
"unreadable_concepts": {"type": "integer", "minimum": 0}
}
},
"ReportComparison": {
"type": "object",
"additionalProperties": false,
"required": ["shared", "jobs", "grid", "coverage", "rating_note", "etag_sha256"],
"properties": {
"shared": {
"type": "object",
"additionalProperties": false,
"required": ["model", "catalog_version", "aggregation_policy_version", "report_schema_version", "concept_set"],
"properties": {
"model": {"type": "string"},
"catalog_version": {"type": "string"},
"aggregation_policy_version": {"type": "string"},
"report_schema_version": {"type": "string"},
"concept_set": {"type": "array", "items": {"type": "string"}}
}
},
"jobs": {"type": "array", "minItems": 2, "maxItems": 5, "items": {"$ref": "#/components/schemas/ComparisonJob"}},
"grid": {"type": "array", "items": {"$ref": "#/components/schemas/ComparisonConcept"}},
"coverage": {"type": "array", "items": {"$ref": "#/components/schemas/ComparisonCoverage"}},
"rating_note": {"type": "string"},
"etag_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
}
},
"RowContributionRow": {
"type": "object",
"additionalProperties": false,
"required": ["dataset_row", "delta"],
"properties": {
"dataset_row": {"type": "integer", "minimum": 0},
"delta": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"}
}
},
"RowContributionGroup": {
"type": "object",
"additionalProperties": false,
"required": ["direction", "rows"],
"properties": {
"direction": {"type": "string", "enum": ["increase", "decrease"]},
"rows": {"type": "array", "items": {"$ref": "#/components/schemas/RowContributionRow"}}
}
},
"RowContributionPrimitive": {
"type": "object",
"additionalProperties": false,
"required": ["result_ref", "method_family", "groups"],
"properties": {
"result_ref": {"type": "string"},
"method_family": {"type": "string"},
"groups": {"type": "array", "items": {"$ref": "#/components/schemas/RowContributionGroup"}}
}
},
"RowContributionConcept": {
"type": "object",
"additionalProperties": false,
"required": ["concept_id", "primitives"],
"properties": {
"concept_id": {"type": "string"},
"primitives": {"type": "array", "items": {"$ref": "#/components/schemas/RowContributionPrimitive"}}
}
},
"RowContributions": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "dataset_id", "dataset_content_hash", "matrix_sha256", "top_k", "rating_state", "language_note", "concepts"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"dataset_id": {"type": "string", "format": "uuid"},
"dataset_content_hash": {"type": "string"},
"matrix_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"top_k": {"type": "integer", "minimum": 1},
"rating_state": {"type": "string", "const": "unrated"},
"language_note": {"type": "string"},
"concepts": {"type": "array", "items": {"$ref": "#/components/schemas/RowContributionConcept"}}
}
},
"RowStatsDistribution": {
"type": "object",
"additionalProperties": false,
"required": ["min", "q1", "median", "q3", "max"],
"properties": {
"min": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"q1": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"median": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"q3": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"max": {"type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"}
}
},
"RowStatsPrimitive": {
"type": "object",
"additionalProperties": false,
"required": ["result_ref", "method_family", "row_count", "positive_count", "negative_count", "zero_count", "fraction_positive", "distribution"],
"properties": {
"result_ref": {"type": "string"},
"method_family": {"type": "string"},
"row_count": {"type": "integer", "minimum": 0},
"positive_count": {"type": "integer", "minimum": 0},
"negative_count": {"type": "integer", "minimum": 0},
"zero_count": {"type": "integer", "minimum": 0},
"fraction_positive": {"type": ["string", "null"], "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"distribution": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/RowStatsDistribution"}]}
}
},
"RowStatsConcept": {
"type": "object",
"additionalProperties": false,
"required": ["concept_id", "primitives"],
"properties": {
"concept_id": {"type": "string"},
"primitives": {"type": "array", "items": {"$ref": "#/components/schemas/RowStatsPrimitive"}}
}
},
"RowStats": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "dataset_id", "dataset_content_hash", "matrix_sha256", "matrix_row_count", "runtime_failure_count", "stats_policy_id", "rating_state", "language_note", "concepts"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"dataset_id": {"type": "string", "format": "uuid"},
"dataset_content_hash": {"type": "string"},
"matrix_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"matrix_row_count": {"type": "integer", "minimum": 0},
"runtime_failure_count": {"type": "integer", "minimum": 0},
"stats_policy_id": {"type": "string", "const": "row-stats-descriptive-v1"},
"rating_state": {"type": "string", "const": "unrated"},
"language_note": {"type": "string"},
"concepts": {"type": "array", "items": {"$ref": "#/components/schemas/RowStatsConcept"}}
}
},
"SaeFeatureSummary": {
"type": "object",
"additionalProperties": false,
"required": ["job_id", "dataset_id", "dataset_content_hash", "export_profile_id", "artifact_sha256", "pair_count", "summary_policy_id", "rating_state", "language_note", "checkpoints"],
"properties": {
"job_id": {"type": "string", "format": "uuid"},
"dataset_id": {"type": "string", "format": "uuid"},
"dataset_content_hash": {"type": "string"},
"export_profile_id": {"type": "string"},
"artifact_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"pair_count": {"type": "integer", "minimum": 0},
"summary_policy_id": {"const": "sae-feature-summary-descriptive-v1"},
"rating_state": {"const": "unrated"},
"language_note": {"type": "string"},
"checkpoints": {"type": "array", "items": {"$ref": "#/components/schemas/SaeFeatureSummaryCheckpoint"}}
}
},
"SaeFeatureSummaryCheckpoint": {
"type": "object",
"additionalProperties": false,
"required": ["checkpoint_id", "layer_index", "labels_available", "label_table_version", "label_table_sha256", "label_status", "overall"],
"properties": {
"checkpoint_id": {"enum": ["gemma-scope-2-12b-it-resid-post-l24-width-65k-l0-medium", "gemma-scope-2-12b-it-resid-post-l31-width-65k-l0-medium"]},
"layer_index": {"type": "integer"},
"labels_available": {"type": "boolean"},
"label_table_version": {"type": ["string", "null"]},
"label_table_sha256": {"type": ["string", "null"], "pattern": "^[0-9a-f]{64}$"},
"label_status": {"const": "hypothesis"},
"overall": {"$ref": "#/components/schemas/SaeFeatureSummaryScope"},
"groups": {"type": "array", "items": {"$ref": "#/components/schemas/SaeFeatureSummaryScope"}},
"ungrouped": {"$ref": "#/components/schemas/SaeFeatureSummaryScope"}
}
},
"SaeFeatureSummaryScope": {
"type": "object",
"additionalProperties": false,
"required": ["row_count", "features"],
"properties": {
"name": {"type": "string"},
"row_count": {"type": "integer", "minimum": 0},
"features": {"type": "array", "items": {"$ref": "#/components/schemas/SaeFeatureSummaryEntry"}}
}
},
"SaeFeatureSummaryEntry": {
"type": "object",
"additionalProperties": false,
"required": ["source_feature_index", "label", "explanation_model", "row_count", "positive_row_count", "negative_row_count", "zero_row_count", "appearance_fraction", "best_rank", "max_abs_signed_delta", "median_abs_signed_delta"],
"properties": {
"source_feature_index": {"type": "integer", "minimum": 0, "maximum": 65535},
"label": {"type": ["string", "null"]},
"explanation_model": {"type": ["string", "null"]},
"row_count": {"type": "integer", "minimum": 1},
"positive_row_count": {"type": "integer", "minimum": 0},
"negative_row_count": {"type": "integer", "minimum": 0},
"zero_row_count": {"type": "integer", "minimum": 0},
"appearance_fraction": {"type": ["string", "null"]},
"best_rank": {"type": "integer", "minimum": 1, "maximum": 100},
"max_abs_signed_delta": {"type": "string"},
"median_abs_signed_delta": {"type": "string"}
}
},
"FeatureLabelEntry": {
"type": "object",
"additionalProperties": false,
"required": ["source_feature_index", "label", "explanation_model"],
"properties": {
"source_feature_index": {"type": "integer", "minimum": 0, "maximum": 65535},
"label": {"type": ["string", "null"]},
"explanation_model": {"type": ["string", "null"]}
}
},
"FeatureLabelGenerator": {
"type": "object",
"additionalProperties": false,
"required": ["method", "imported_at", "explanation_models", "license_note"],
"properties": {
"method": {"type": "string", "const": "neuronpedia_import"},
"imported_at": {"type": "string"},
"explanation_models": {"type": "array", "items": {"type": "string"}},
"license_note": {"type": "string"}
}
},
"FeatureLabels": {
"type": "object",
"additionalProperties": false,
"required": ["checkpoint_id", "label_table_version", "label_table_sha256", "generator", "label_status", "rating_state", "language_note", "labels"],
"properties": {
"checkpoint_id": {"type": "string"},
"label_table_version": {"type": "string"},
"label_table_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"generator": {"$ref": "#/components/schemas/FeatureLabelGenerator"},
"label_status": {"type": "string", "const": "hypothesis"},
"rating_state": {"type": "string", "const": "unrated"},
"language_note": {"type": "string"},
"labels": {"type": "array", "items": {"$ref": "#/components/schemas/FeatureLabelEntry"}}
}
},
"LedgerEntry": {
"type": "object",
"required": ["id", "event_type", "amount_delta", "balance_after"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"event_type": {"type": "string"},
"amount_delta": {"type": "string"},
"balance_after": {"type": "string"},
"job_id": {"type": ["string", "null"]},
"provider_event_id": {"type": ["string", "null"]}
}
},
"Credits": {
"type": "object",
"required": ["balance", "ledger", "next_cursor"],
"properties": {"balance": {"type": "string"}, "ledger": {"type": "array", "items": {"$ref": "#/components/schemas/LedgerEntry"}}, "next_cursor": {"$ref": "#/components/schemas/PageCursor"}}
},
"CreditPurchaseRequest": {
"type": "object",
"additionalProperties": false,
"required": ["sku"],
"properties": {"sku": {"type": "string", "minLength": 1, "maxLength": 128}}
},
"CreditPurchase": {
"type": "object",
"additionalProperties": false,
"required": ["order_id", "status", "sku", "credits", "checkout_url", "expires_at"],
"properties": {
"order_id": {"type": "string", "format": "uuid"},
"status": {"type": "string", "enum": ["provider_created", "paid"]},
"sku": {"type": "string"},
"credits": {"type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$"},
"checkout_url": {"type": "string", "format": "uri"},
"expires_at": {"type": ["integer", "null"]}
}
},
"CreateWebhookEndpointRequest": {
"type": "object",
"additionalProperties": false,
"required": ["url", "event_types"],
"properties": {
"url": {"type": "string", "format": "uri", "maxLength": 2048},
"event_types": {
"type": "array",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true,
"items": {"type": "string", "enum": ["job.*", "dataset.validated", "credits.low"]}
}
}
},
"WebhookEndpoint": {
"type": "object",
"additionalProperties": false,
"required": ["id", "url", "event_types", "active", "key_id", "key_fingerprint", "disabled_at", "created_at"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"url": {"type": "string", "format": "uri"},
"event_types": {"type": "array", "items": {"type": "string"}},
"active": {"type": "boolean"},
"key_id": {"type": "string"},
"key_fingerprint": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
"disabled_at": {"type": ["string", "null"], "format": "date-time"},
"created_at": {"type": "string", "format": "date-time"},
"secret": {"type": "string", "description": "Present only on the first successful endpoint creation response"},
"secret_returned": {"type": "boolean"}
}
},
"WebhookEndpointPage": {
"type": "object",
"required": ["data", "next_cursor"],
"properties": {
"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookEndpoint"}},
"next_cursor": {"$ref": "#/components/schemas/PageCursor"}
}
},
"WebhookDeliveryAttempt": {
"type": "object",
"additionalProperties": false,
"required": ["id", "attempt_number", "resolved_ip", "outcome", "status_code", "response_byte_count", "error_code", "duration_ms", "created_at"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"attempt_number": {"type": "integer", "minimum": 1},
"resolved_ip": {"type": ["string", "null"]},
"outcome": {"type": "string", "enum": ["delivered", "retry_scheduled", "dead_lettered"]},
"status_code": {"type": ["integer", "null"], "minimum": 100, "maximum": 599},
"response_byte_count": {"type": "integer", "minimum": 0},
"error_code": {"type": ["string", "null"]},
"duration_ms": {"type": "integer", "minimum": 0},
"created_at": {"type": "string", "format": "date-time"}
}
},
"WebhookDelivery": {
"type": "object",
"additionalProperties": false,
"required": ["id", "endpoint_id", "event_id", "event_type", "state", "attempt_count", "replay_sequence", "replayed_from_id", "next_attempt_at", "delivered_at", "dead_lettered_at", "last_error_code", "created_at", "attempts"],
"properties": {
"id": {"type": "string", "format": "uuid"},
"endpoint_id": {"type": "string", "format": "uuid"},
"event_id": {"type": "string", "format": "uuid"},
"event_type": {"type": "string"},
"state": {"type": "string", "enum": ["pending", "delivering", "delivered", "dead_letter"]},
"attempt_count": {"type": "integer", "minimum": 0},
"replay_sequence": {"type": "integer", "minimum": 0},
"replayed_from_id": {"type": ["string", "null"], "format": "uuid"},
"next_attempt_at": {"type": ["string", "null"], "format": "date-time"},
"delivered_at": {"type": ["string", "null"], "format": "date-time"},
"dead_lettered_at": {"type": ["string", "null"], "format": "date-time"},
"last_error_code": {"type": ["string", "null"]},
"created_at": {"type": "string", "format": "date-time"},
"attempts": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDeliveryAttempt"}}
}
},
"WebhookDeliveryPage": {
"type": "object",
"required": ["data", "next_cursor"],
"properties": {
"data": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDelivery"}},
"next_cursor": {"$ref": "#/components/schemas/PageCursor"}
}
}
}
}
}