AI-Cognitive-Leap/agnes-the-ai-analyst
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
agnes-the-ai-analyst/tests/snapshots/openapi.json
Vojtech c5948f26fc
fix(api): harden API surface before Swagger (issue #336) (#339) 
* fix(api): harden API surface before Swagger — 9 findings from issue #336

ADV-001: POST /api/sync/table-subscriptions now checks can_access() per
table entry, matching the gate already on POST /api/sync/settings.

ADV-002: GET /webhooks/jira/health gated behind require_admin; jira_domain
removed from response to prevent anonymous info disclosure.

ADV-003: GET /api/version no longer exposes commit_sha or schema_version.

ADV-005: /docs, /redoc, /openapi.json now require a valid session via custom
FastAPI routes (docs_url=None, redoc_url=None, openapi_url=None).

ADV-006: /cli/ and /webhooks/ added to _API_PATH_PREFIXES so future
auth-gated routes there return JSON 401 not an HTML redirect.

ADV-007: GET /api/catalog/tables wired to CatalogTablesResponse model.

ADV-008: TableSubscriptionUpdate.tables capped at max_length=500.

ADV-009: GET /api/users and GET /auth/admin/tokens accept limit/offset
(default 1000, max 10000); repositories updated accordingly.

Tests: 11 new regression tests in TestApiHardening336; test_jira_webhooks
fixture updated with seeded admin user; OpenAPI snapshot regenerated.

* fix(test): update test_journey_jira health check to use admin auth after ADV-002 gate

* fix(security): close /auth/bootstrap auth-bypass + BREAKING markers on ADV-002/003/005

Reviewer-flagged regression introduced by ADV-009's pagination on
UserRepository.list_all(): the silent default LIMIT 1000 broke the
bootstrap check at app/auth/router.py and the startup no-password
warning at app/main.py — both call list_all() with no args and depend
on exhaustive enumeration.

On an instance with >1000 users where no password-holder lands in
the email-sorted first page, [u for u in list_all() if
u.get('password_hash')] becomes empty → bootstrap re-opens → an
unauthenticated caller can claim admin via /auth/bootstrap. Real
auth-bypass on a security-sensitive boot path.

Fix:
- src/repositories/users.py: list_all() restored to no-arg, returns
  EVERY row (no LIMIT). Comment explicitly warns against re-adding
  pagination here. API-surface pagination moved to a new
  list_paginated(limit, offset) method with its own docstring.
- app/api/users.py: GET /api/users now calls list_paginated().
  Existing query-param validation (limit <= 10000) preserved.

Regression guards in tests/test_security.py::TestApiHardening336:
- test_users_list_all_returns_every_row_no_silent_limit asserts
  list_all() takes no params other than self (via inspect.signature)
  so a future cleanup can't accidentally re-add limit/offset.
- test_users_list_paginated_is_separate_method asserts the
  paginated variant is a distinct method, not an overload.

CHANGELOG: added **BREAKING** markers per CLAUDE.md release
discipline to three pre-existing ADV bullets that are observable
breaking changes for external consumers:
- ADV-002 (webhook health going from anonymous to admin-only)
- ADV-003 (/api/version dropping commit_sha + schema_version)
- ADV-005 (/docs, /redoc, /openapi.json going from anonymous to
  session-required)

* release: 0.54.25 — API hardening before Swagger (ADV-001..009) + bootstrap-bypass regression fix

---------

Co-authored-by: ZdenekSrotyr <zdenek.srotyr@keboola.com>
2026-05-18 15:13:21 +02:00

23743 lines
639 KiB
JSON
Raw Blame History

{
"components": {
"schemas": {
"AddMemberRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
}
},
"required": [
"email"
],
"title": "AddMemberRequest",
"type": "object"
},
"AddUserToGroupRequest": {
"properties": {
"group_id": {
"title": "Group Id",
"type": "string"
}
},
"required": [
"group_id"
],
"title": "AddUserToGroupRequest",
"type": "object"
},
"AdminActionRequest": {
"properties": {
"audience": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Audience"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
}
},
"title": "AdminActionRequest",
"type": "object"
},
"AdminInitialWorkspaceResponse": {
"description": "Admin-facing view; surfaces sync state + has_token (no secret leak).",
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Branch"
},
"configured": {
"default": false,
"title": "Configured",
"type": "boolean"
},
"file_count": {
"default": 0,
"title": "File Count",
"type": "integer"
},
"has_token": {
"default": false,
"title": "Has Token",
"type": "boolean"
},
"last_commit_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Commit Sha"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Synced At"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"title": "AdminInitialWorkspaceResponse",
"type": "object"
},
"AdminTokenItem": {
"description": "Admin list row: adds owner identity + last IP for incident response.",
"properties": {
"created_at": {
"title": "Created At",
"type": "string"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expires At"
},
"id": {
"title": "Id",
"type": "string"
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Used At"
},
"last_used_ip": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Used Ip"
},
"name": {
"title": "Name",
"type": "string"
},
"prefix": {
"title": "Prefix",
"type": "string"
},
"revoked_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Revoked At"
},
"user_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Email"
},
"user_id": {
"title": "User Id",
"type": "string"
}
},
"required": [
"id",
"name",
"prefix",
"created_at",
"expires_at",
"last_used_at",
"revoked_at",
"user_id"
],
"title": "AdminTokenItem",
"type": "object"
},
"AnalystInitialWorkspaceResponse": {
"description": "PAT-authed analyst view; what ``agnes init`` consumes.",
"properties": {
"configured": {
"default": false,
"title": "Configured",
"type": "boolean"
},
"files": {
"default": [],
"items": {
"type": "string"
},
"title": "Files",
"type": "array"
},
"synced": {
"default": false,
"title": "Synced",
"type": "boolean"
},
"synced_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Synced At"
},
"template_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template Sha"
},
"template_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template Source"
}
},
"title": "AnalystInitialWorkspaceResponse",
"type": "object"
},
"AppliedRequest": {
"description": "CLI audit event after the analyst's workspace has been extracted.",
"properties": {
"files_created": {
"default": 0,
"title": "Files Created",
"type": "integer"
},
"files_overwritten": {
"default": 0,
"title": "Files Overwritten",
"type": "integer"
},
"mode": {
"title": "Mode",
"type": "string"
},
"template_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Template Sha"
}
},
"required": [
"mode"
],
"title": "AppliedRequest",
"type": "object"
},
"BannerResponse": {
"properties": {
"content": {
"title": "Content",
"type": "string"
}
},
"required": [
"content"
],
"title": "BannerResponse",
"type": "object"
},
"BatchActionRequest": {
"properties": {
"action": {
"title": "Action",
"type": "string"
},
"audience": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Audience"
},
"item_ids": {
"items": {
"type": "string"
},
"title": "Item Ids",
"type": "array"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason"
}
},
"required": [
"item_ids",
"action"
],
"title": "BatchActionRequest",
"type": "object"
},
"Body_create_entity_api_store_entities_post": {
"properties": {
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"docs": {
"default": [],
"items": {
"contentMediaType": "application/octet-stream",
"type": "string"
},
"title": "Docs",
"type": "array"
},
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"photo": {
"anyOf": [
{
"contentMediaType": "application/octet-stream",
"type": "string"
},
{
"type": "null"
}
],
"title": "Photo"
},
"type": {
"title": "Type",
"type": "string"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Video Url"
}
},
"required": [
"file",
"type"
],
"title": "Body_create_entity_api_store_entities_post",
"type": "object"
},
"Body_import_bundle_api_store_import_bundle_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
},
"mode": {
"default": "merge",
"title": "Mode",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_import_bundle_api_store_import_bundle_post",
"type": "object"
},
"Body_import_metrics_api_admin_metrics_import_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_import_metrics_api_admin_metrics_import_post",
"type": "object"
},
"Body_password_login_web_auth_password_login_web_post": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"next": {
"default": "",
"title": "Next",
"type": "string"
},
"password": {
"default": "",
"title": "Password",
"type": "string"
}
},
"required": [
"email"
],
"title": "Body_password_login_web_auth_password_login_web_post",
"type": "object"
},
"Body_preview_entity_api_store_entities_preview_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"file",
"type"
],
"title": "Body_preview_entity_api_store_entities_preview_post",
"type": "object"
},
"Body_reset_confirm_auth_password_reset_confirm_post": {
"properties": {
"confirm_password": {
"title": "Confirm Password",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"password": {
"title": "Password",
"type": "string"
},
"token": {
"title": "Token",
"type": "string"
}
},
"required": [
"email",
"token",
"password",
"confirm_password"
],
"title": "Body_reset_confirm_auth_password_reset_confirm_post",
"type": "object"
},
"Body_reset_request_auth_password_reset_post": {
"properties": {
"email": {
"default": "",
"title": "Email",
"type": "string"
}
},
"title": "Body_reset_request_auth_password_reset_post",
"type": "object"
},
"Body_setup_confirm_auth_password_setup_confirm_post": {
"properties": {
"confirm_password": {
"title": "Confirm Password",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"name": {
"default": "",
"title": "Name",
"type": "string"
},
"password": {
"title": "Password",
"type": "string"
},
"token": {
"title": "Token",
"type": "string"
}
},
"required": [
"email",
"token",
"password",
"confirm_password"
],
"title": "Body_setup_confirm_auth_password_setup_confirm_post",
"type": "object"
},
"Body_setup_request_auth_password_setup_request_post": {
"properties": {
"email": {
"default": "",
"title": "Email",
"type": "string"
}
},
"title": "Body_setup_request_auth_password_setup_request_post",
"type": "object"
},
"Body_update_entity_api_store_entities__entity_id__put": {
"properties": {
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"file": {
"anyOf": [
{
"contentMediaType": "application/octet-stream",
"type": "string"
},
{
"type": "null"
}
],
"title": "File"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"photo": {
"anyOf": [
{
"contentMediaType": "application/octet-stream",
"type": "string"
},
{
"type": "null"
}
],
"title": "Photo"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Video Url"
}
},
"title": "Body_update_entity_api_store_entities__entity_id__put",
"type": "object"
},
"Body_upload_artifact_api_upload_artifacts_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_upload_artifact_api_upload_artifacts_post",
"type": "object"
},
"Body_upload_session_api_upload_sessions_post": {
"properties": {
"file": {
"contentMediaType": "application/octet-stream",
"title": "File",
"type": "string"
}
},
"required": [
"file"
],
"title": "Body_upload_session_api_upload_sessions_post",
"type": "object"
},
"BootstrapRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"name": {
"default": "",
"title": "Name",
"type": "string"
},
"password": {
"default": "",
"title": "Password",
"type": "string"
}
},
"required": [
"email"
],
"title": "BootstrapRequest",
"type": "object"
},
"BulkUpdateRequest": {
"description": "Apply ``updates`` to every id in ``item_ids``. Issue #62.",
"properties": {
"item_ids": {
"items": {
"type": "string"
},
"title": "Item Ids",
"type": "array"
},
"updates": {
"additionalProperties": true,
"title": "Updates",
"type": "object"
}
},
"required": [
"item_ids",
"updates"
],
"title": "BulkUpdateRequest",
"type": "object"
},
"CatalogTableItem": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"query_mode": {
"default": "local",
"title": "Query Mode",
"type": "string"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
},
"sync_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sync Strategy"
}
},
"required": [
"id",
"name"
],
"title": "CatalogTableItem",
"type": "object"
},
"CatalogTablesResponse": {
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"tables": {
"items": {
"$ref": "#/components/schemas/CatalogTableItem"
},
"title": "Tables",
"type": "array"
}
},
"required": [
"tables",
"count"
],
"title": "CatalogTablesResponse",
"type": "object"
},
"CategoriesResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/CategoryEntry"
},
"title": "Items",
"type": "array"
}
},
"required": [
"items"
],
"title": "CategoriesResponse",
"type": "object"
},
"CategoryEntry": {
"properties": {
"count": {
"title": "Count",
"type": "integer"
},
"icon_key": {
"title": "Icon Key",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name",
"count",
"icon_key"
],
"title": "CategoryEntry",
"type": "object"
},
"ClaudeMdResponse": {
"properties": {
"content": {
"title": "Content",
"type": "string"
}
},
"required": [
"content"
],
"title": "ClaudeMdResponse",
"type": "object"
},
"ColumnMetadataItem": {
"properties": {
"basetype": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Basetype"
},
"column_name": {
"title": "Column Name",
"type": "string"
},
"confidence": {
"default": "manual",
"title": "Confidence",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"required": [
"column_name"
],
"title": "ColumnMetadataItem",
"type": "object"
},
"ColumnMetadataSave": {
"properties": {
"columns": {
"items": {
"$ref": "#/components/schemas/ColumnMetadataItem"
},
"title": "Columns",
"type": "array"
}
},
"required": [
"columns"
],
"title": "ColumnMetadataSave",
"type": "object"
},
"CommandEntry": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "CommandEntry",
"type": "object"
},
"ConfigureRequest": {
"properties": {
"allowed_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Allowed Domain"
},
"bigquery_location": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bigquery Location"
},
"bigquery_project": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bigquery Project"
},
"data_source": {
"title": "Data Source",
"type": "string"
},
"instance_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Instance Name"
},
"keboola_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Keboola Token"
},
"keboola_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Keboola Url"
}
},
"required": [
"data_source"
],
"title": "ConfigureRequest",
"type": "object"
},
"CreateContradictionRequest": {
"properties": {
"explanation": {
"title": "Explanation",
"type": "string"
},
"item_a_id": {
"title": "Item A Id",
"type": "string"
},
"item_b_id": {
"title": "Item B Id",
"type": "string"
},
"severity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Severity"
},
"suggested_resolution": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Suggested Resolution"
}
},
"required": [
"item_a_id",
"item_b_id",
"explanation"
],
"title": "CreateContradictionRequest",
"type": "object"
},
"CreateGrantRequest": {
"properties": {
"group_id": {
"title": "Group Id",
"type": "string"
},
"resource_id": {
"title": "Resource Id",
"type": "string"
},
"resource_type": {
"title": "Resource Type",
"type": "string"
}
},
"required": [
"group_id",
"resource_type",
"resource_id"
],
"title": "CreateGrantRequest",
"type": "object"
},
"CreateGroupRequest": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "CreateGroupRequest",
"type": "object"
},
"CreateKnowledgeRequest": {
"properties": {
"category": {
"title": "Category",
"type": "string"
},
"content": {
"title": "Content",
"type": "string"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"entities": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"title",
"content",
"category"
],
"title": "CreateKnowledgeRequest",
"type": "object"
},
"CreateMarketplaceRequest": {
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Branch"
},
"curator_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Email"
},
"curator_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
},
"slug": {
"title": "Slug",
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Token"
},
"url": {
"title": "Url",
"type": "string"
}
},
"required": [
"name",
"slug",
"url"
],
"title": "CreateMarketplaceRequest",
"type": "object"
},
"CreateTokenRequest": {
"properties": {
"expires_in_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": 90,
"title": "Expires In Days"
},
"name": {
"title": "Name",
"type": "string"
},
"scope": {
"default": "general",
"title": "Scope",
"type": "string"
},
"ttl_seconds": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Ttl Seconds"
}
},
"required": [
"name"
],
"title": "CreateTokenRequest",
"type": "object"
},
"CreateTokenResponse": {
"properties": {
"created_at": {
"title": "Created At",
"type": "string"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expires At"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"prefix": {
"title": "Prefix",
"type": "string"
},
"token": {
"title": "Token",
"type": "string"
}
},
"required": [
"id",
"name",
"prefix",
"token",
"expires_at",
"created_at"
],
"title": "CreateTokenResponse",
"type": "object"
},
"CreateUserRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"send_invite": {
"default": false,
"title": "Send Invite",
"type": "boolean"
}
},
"required": [
"email",
"name"
],
"title": "CreateUserRequest",
"type": "object"
},
"CuratedPlugin": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"manifest_name": {
"title": "Manifest Name",
"type": "string"
},
"marketplace_id": {
"title": "Marketplace Id",
"type": "string"
},
"marketplace_slug": {
"title": "Marketplace Slug",
"type": "string"
},
"plugin_name": {
"title": "Plugin Name",
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
}
},
"required": [
"marketplace_id",
"marketplace_slug",
"plugin_name",
"manifest_name",
"enabled"
],
"title": "CuratedPlugin",
"type": "object"
},
"DatasetSettingRequest": {
"properties": {
"dataset": {
"title": "Dataset",
"type": "string"
},
"enabled": {
"title": "Enabled",
"type": "boolean"
}
},
"required": [
"dataset",
"enabled"
],
"title": "DatasetSettingRequest",
"type": "object"
},
"DeployScriptRequest": {
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Schedule"
},
"source": {
"title": "Source",
"type": "string"
}
},
"required": [
"name",
"source"
],
"title": "DeployScriptRequest",
"type": "object"
},
"DocEntry": {
"description": "One doc file shipped alongside a Store entity. URL points at the\nserving endpoint (``/api/store/entities/<id>/docs/<filename>``).",
"properties": {
"name": {
"title": "Name",
"type": "string"
},
"url": {
"title": "Url",
"type": "string"
}
},
"required": [
"name",
"url"
],
"title": "DocEntry",
"type": "object"
},
"EditRequest": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
}
},
"title": "EditRequest",
"type": "object"
},
"EffectiveAccessItem": {
"properties": {
"resource_id": {
"title": "Resource Id",
"type": "string"
},
"resource_type": {
"title": "Resource Type",
"type": "string"
},
"via_groups": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Via Groups",
"type": "array"
}
},
"required": [
"resource_type",
"resource_id",
"via_groups"
],
"title": "EffectiveAccessItem",
"type": "object"
},
"EffectiveAccessResponse": {
"properties": {
"is_admin": {
"title": "Is Admin",
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/EffectiveAccessItem"
},
"title": "Items",
"type": "array"
}
},
"required": [
"is_admin",
"items"
],
"title": "EffectiveAccessResponse",
"type": "object"
},
"FileEntry": {
"description": "One file in a plugin / skill / agent bundle. Path is relative to the\nbundle root; size is bytes (rendered with ``humanbytes`` on the client).",
"properties": {
"path": {
"title": "Path",
"type": "string"
},
"size": {
"title": "Size",
"type": "integer"
}
},
"required": [
"path",
"size"
],
"title": "FileEntry",
"type": "object"
},
"GrantResponse": {
"properties": {
"assigned_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Assigned At"
},
"assigned_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Assigned By"
},
"group_id": {
"title": "Group Id",
"type": "string"
},
"group_name": {
"title": "Group Name",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"resource_id": {
"title": "Resource Id",
"type": "string"
},
"resource_type": {
"title": "Resource Type",
"type": "string"
}
},
"required": [
"id",
"group_id",
"group_name",
"resource_type",
"resource_id"
],
"title": "GrantResponse",
"type": "object"
},
"GroupBrief": {
"properties": {
"id": {
"title": "Id",
"type": "string"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"origin": {
"default": "custom",
"title": "Origin",
"type": "string"
}
},
"required": [
"id",
"name"
],
"title": "GroupBrief",
"type": "object"
},
"GroupResponse": {
"properties": {
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"created_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created By"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"grant_count": {
"default": 0,
"title": "Grant Count",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"is_google_managed": {
"default": false,
"title": "Is Google Managed",
"type": "boolean"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"mapped_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mapped Email"
},
"member_count": {
"default": 0,
"title": "Member Count",
"type": "integer"
},
"name": {
"title": "Name",
"type": "string"
},
"origin": {
"default": "custom",
"title": "Origin",
"type": "string"
}
},
"required": [
"id",
"name"
],
"title": "GroupResponse",
"type": "object"
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
},
"HookEntry": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"name": {
"title": "Name",
"type": "string"
}
},
"required": [
"name"
],
"title": "HookEntry",
"type": "object"
},
"HybridQueryRequest": {
"properties": {
"register_bq": {
"additionalProperties": {
"type": "string"
},
"default": {},
"title": "Register Bq",
"type": "object"
},
"sql": {
"title": "Sql",
"type": "string"
}
},
"required": [
"sql"
],
"title": "HybridQueryRequest",
"type": "object"
},
"ImportBundleResponse": {
"properties": {
"errors": {
"default": [],
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Errors",
"type": "array"
},
"imported": {
"title": "Imported",
"type": "integer"
},
"replaced": {
"title": "Replaced",
"type": "integer"
},
"skipped": {
"title": "Skipped",
"type": "integer"
},
"stub_users_created": {
"title": "Stub Users Created",
"type": "integer"
}
},
"required": [
"imported",
"replaced",
"skipped",
"stub_users_created"
],
"title": "ImportBundleResponse",
"type": "object"
},
"InnerDetailResponse": {
"properties": {
"body": {
"title": "Body",
"type": "string"
},
"bundle_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bundle Size"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"cover_photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cover Photo Url"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"description_long_html": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description Long Html"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Display Name"
},
"docs": {
"default": [],
"items": {
"$ref": "#/components/schemas/DocEntry"
},
"title": "Docs",
"type": "array"
},
"files": {
"default": [],
"items": {
"$ref": "#/components/schemas/FileEntry"
},
"title": "Files",
"type": "array"
},
"invocation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Invocation"
},
"kind": {
"enum": [
"skill",
"agent"
],
"title": "Kind",
"type": "string"
},
"manifest_name": {
"default": "",
"title": "Manifest Name",
"type": "string"
},
"marketplace_id": {
"title": "Marketplace Id",
"type": "string"
},
"marketplace_name": {
"default": "",
"title": "Marketplace Name",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"parent_author_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Author Name"
},
"parent_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Display Name"
},
"parent_stack_count": {
"default": 0,
"title": "Parent Stack Count",
"type": "integer"
},
"parent_updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Updated At"
},
"plugin_name": {
"title": "Plugin Name",
"type": "string"
},
"relpath": {
"title": "Relpath",
"type": "string"
},
"sample_interaction": {
"anyOf": [
{
"$ref": "#/components/schemas/SampleInteraction"
},
{
"type": "null"
}
]
},
"tagline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tagline"
},
"telemetry": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Telemetry"
},
"use_cases": {
"default": [],
"items": {
"$ref": "#/components/schemas/UseCase"
},
"title": "Use Cases",
"type": "array"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Video Url"
},
"when_to_use_html": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "When To Use Html"
}
},
"required": [
"marketplace_id",
"plugin_name",
"kind",
"name",
"body",
"relpath"
],
"title": "InnerDetailResponse",
"type": "object"
},
"InnerItemSummary": {
"properties": {
"cover_photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cover Photo Url"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"detail_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Detail Url"
},
"distinct_users_30d": {
"default": 0,
"title": "Distinct Users 30D",
"type": "integer"
},
"invocations_30d": {
"default": 0,
"title": "Invocations 30D",
"type": "integer"
},
"name": {
"title": "Name",
"type": "string"
},
"parent_stack_count": {
"default": 0,
"title": "Parent Stack Count",
"type": "integer"
},
"trend_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Trend Pct"
}
},
"required": [
"name"
],
"title": "InnerItemSummary",
"type": "object"
},
"InstallActionResponse": {
"properties": {
"installed": {
"title": "Installed",
"type": "boolean"
}
},
"required": [
"installed"
],
"title": "InstallActionResponse",
"type": "object"
},
"InstallResponse": {
"properties": {
"entity_id": {
"title": "Entity Id",
"type": "string"
},
"installed": {
"title": "Installed",
"type": "boolean"
}
},
"required": [
"entity_id",
"installed"
],
"title": "InstallResponse",
"type": "object"
},
"ItemListResponse": {
"properties": {
"available_sorts": {
"default": [
"recent",
"most_used",
"most_adopted"
],
"items": {
"type": "string"
},
"title": "Available Sorts",
"type": "array"
},
"items": {
"items": {
"$ref": "#/components/schemas/MarketplaceItem"
},
"title": "Items",
"type": "array"
},
"page": {
"title": "Page",
"type": "integer"
},
"page_size": {
"title": "Page Size",
"type": "integer"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"items",
"total",
"page",
"page_size"
],
"title": "ItemListResponse",
"type": "object"
},
"LocalMdRequest": {
"properties": {
"content": {
"title": "Content",
"type": "string"
}
},
"required": [
"content"
],
"title": "LocalMdRequest",
"type": "object"
},
"MagicLinkRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
}
},
"required": [
"email"
],
"title": "MagicLinkRequest",
"type": "object"
},
"MagicLinkVerify": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"token": {
"title": "Token",
"type": "string"
}
},
"required": [
"email",
"token"
],
"title": "MagicLinkVerify",
"type": "object"
},
"MarketplaceItem": {
"properties": {
"added": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Added"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"detail_url": {
"title": "Detail Url",
"type": "string"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Display Name"
},
"distinct_users_30d": {
"default": 0,
"title": "Distinct Users 30D",
"type": "integer"
},
"distinct_users_7d": {
"default": 0,
"title": "Distinct Users 7D",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"installed": {
"default": false,
"title": "Installed",
"type": "boolean"
},
"invocations_30d": {
"default": 0,
"title": "Invocations 30D",
"type": "integer"
},
"invocations_7d": {
"default": 0,
"title": "Invocations 7D",
"type": "integer"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"is_viewer_owner": {
"default": false,
"title": "Is Viewer Owner",
"type": "boolean"
},
"marketplace_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Marketplace Name"
},
"marketplace_slug": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Marketplace Slug"
},
"name": {
"title": "Name",
"type": "string"
},
"owner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner"
},
"photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Photo Url"
},
"source": {
"enum": [
"curated",
"flea"
],
"title": "Source",
"type": "string"
},
"stack_count": {
"default": 0,
"title": "Stack Count",
"type": "integer"
},
"tagline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tagline"
},
"trend_pct": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Trend Pct"
},
"type": {
"enum": [
"skill",
"agent",
"plugin"
],
"title": "Type",
"type": "string"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
},
"visibility_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Visibility Status"
}
},
"required": [
"id",
"source",
"name",
"type",
"detail_url"
],
"title": "MarketplaceItem",
"type": "object"
},
"MarketplaceResponse": {
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Branch"
},
"curator_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Email"
},
"curator_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"has_token": {
"default": false,
"title": "Has Token",
"type": "boolean"
},
"id": {
"title": "Id",
"type": "string"
},
"last_commit_sha": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Commit Sha"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Synced At"
},
"name": {
"title": "Name",
"type": "string"
},
"plugin_count": {
"default": 0,
"title": "Plugin Count",
"type": "integer"
},
"registered_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Registered At"
},
"registered_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Registered By"
},
"url": {
"title": "Url",
"type": "string"
}
},
"required": [
"id",
"name",
"url"
],
"title": "MarketplaceResponse",
"type": "object"
},
"McpEntry": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"title": "Name",
"type": "string"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
"required": [
"name"
],
"title": "McpEntry",
"type": "object"
},
"MemberResponse": {
"properties": {
"active": {
"default": true,
"title": "Active",
"type": "boolean"
},
"added_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Added At"
},
"added_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Added By"
},
"email": {
"title": "Email",
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"source": {
"title": "Source",
"type": "string"
},
"user_id": {
"title": "User Id",
"type": "string"
}
},
"required": [
"user_id",
"email",
"source"
],
"title": "MemberResponse",
"type": "object"
},
"MetricCreate": {
"properties": {
"category": {
"title": "Category",
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"dimensions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dimensions"
},
"display_name": {
"title": "Display Name",
"type": "string"
},
"expression": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expression"
},
"filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Filters"
},
"grain": {
"default": "monthly",
"title": "Grain",
"type": "string"
},
"id": {
"title": "Id",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"notes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Notes"
},
"source": {
"default": "manual",
"title": "Source",
"type": "string"
},
"sql": {
"title": "Sql",
"type": "string"
},
"sql_variants": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Sql Variants"
},
"synonyms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Synonyms"
},
"table_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Table Name"
},
"tables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tables"
},
"time_column": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Time Column"
},
"type": {
"default": "sum",
"title": "Type",
"type": "string"
},
"unit": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Unit"
},
"validation": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Validation"
}
},
"required": [
"id",
"name",
"display_name",
"category",
"sql"
],
"title": "MetricCreate",
"type": "object"
},
"MyStackResponse": {
"properties": {
"curated": {
"items": {
"$ref": "#/components/schemas/CuratedPlugin"
},
"title": "Curated",
"type": "array"
},
"store": {
"items": {
"$ref": "#/components/schemas/StoreInstallEntry"
},
"title": "Store",
"type": "array"
}
},
"required": [
"curated",
"store"
],
"title": "MyStackResponse",
"type": "object"
},
"NewsBody": {
"properties": {
"content": {
"default": "",
"title": "Content",
"type": "string"
},
"intro": {
"default": "",
"title": "Intro",
"type": "string"
}
},
"title": "NewsBody",
"type": "object"
},
"OkResponse": {
"properties": {
"ok": {
"default": true,
"title": "Ok",
"type": "boolean"
}
},
"title": "OkResponse",
"type": "object"
},
"OnboardedRequest": {
"properties": {
"onboarded": {
"default": true,
"title": "Onboarded",
"type": "boolean"
},
"source": {
"default": "agnes_init",
"enum": [
"agnes_init",
"self_acknowledged",
"self_unmark"
],
"title": "Source",
"type": "string"
}
},
"title": "OnboardedRequest",
"type": "object"
},
"OwnerOption": {
"properties": {
"display_name": {
"title": "Display Name",
"type": "string"
},
"entity_count": {
"title": "Entity Count",
"type": "integer"
},
"user_id": {
"title": "User Id",
"type": "string"
}
},
"required": [
"user_id",
"display_name",
"entity_count"
],
"title": "OwnerOption",
"type": "object"
},
"PasswordLoginRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"password": {
"title": "Password",
"type": "string"
}
},
"required": [
"email",
"password"
],
"title": "PasswordLoginRequest",
"type": "object"
},
"PasswordSetupRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"password": {
"title": "Password",
"type": "string"
},
"token": {
"title": "Token",
"type": "string"
}
},
"required": [
"email",
"token",
"password"
],
"title": "PasswordSetupRequest",
"type": "object"
},
"PatchItemRequest": {
"description": "Partial update for a knowledge item via PATCH /api/memory/admin/{id}.\n\nReplaces the narrow ``EditRequest`` (title + content only). Any field\nleft as ``None`` is unchanged. Domain is validated against\n``VALID_DOMAINS`` when supplied.",
"properties": {
"audience": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Audience"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content"
},
"domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Title"
}
},
"title": "PatchItemRequest",
"type": "object"
},
"PersonalFlagRequest": {
"properties": {
"is_personal": {
"title": "Is Personal",
"type": "boolean"
}
},
"required": [
"is_personal"
],
"title": "PersonalFlagRequest",
"type": "object"
},
"PluginDetailResponse": {
"description": "Unified detail response for a plugin (curated *or* flea).\n\nFrontend-side switching is purely cosmetic \u2014 `source` controls the\nCurated/Flea pill, photo URL fallback path, and owner label.",
"properties": {
"agents": {
"default": [],
"items": {
"$ref": "#/components/schemas/InnerItemSummary"
},
"title": "Agents",
"type": "array"
},
"author_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Author Name"
},
"bundle_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bundle Size"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"commands": {
"default": [],
"items": {
"$ref": "#/components/schemas/CommandEntry"
},
"title": "Commands",
"type": "array"
},
"cover_photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cover Photo Url"
},
"curator_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Email"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"description_long_html": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description Long Html"
},
"display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Display Name"
},
"docs": {
"default": [],
"items": {
"$ref": "#/components/schemas/DocEntry"
},
"title": "Docs",
"type": "array"
},
"entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Entity Id"
},
"files": {
"default": [],
"items": {
"$ref": "#/components/schemas/FileEntry"
},
"title": "Files",
"type": "array"
},
"homepage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Homepage"
},
"hooks": {
"default": [],
"items": {
"$ref": "#/components/schemas/HookEntry"
},
"title": "Hooks",
"type": "array"
},
"install_count": {
"default": 0,
"title": "Install Count",
"type": "integer"
},
"installed": {
"default": false,
"title": "Installed",
"type": "boolean"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"manifest_name": {
"title": "Manifest Name",
"type": "string"
},
"marketplace_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Marketplace Id"
},
"marketplace_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Marketplace Name"
},
"mcps": {
"default": [],
"items": {
"$ref": "#/components/schemas/McpEntry"
},
"title": "Mcps",
"type": "array"
},
"owner_display": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Display"
},
"plugin_name": {
"title": "Plugin Name",
"type": "string"
},
"released_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Released At"
},
"sample_interaction": {
"anyOf": [
{
"$ref": "#/components/schemas/SampleInteraction"
},
{
"type": "null"
}
]
},
"skills": {
"default": [],
"items": {
"$ref": "#/components/schemas/InnerItemSummary"
},
"title": "Skills",
"type": "array"
},
"source": {
"enum": [
"curated",
"flea"
],
"title": "Source",
"type": "string"
},
"stack_count": {
"default": 0,
"title": "Stack Count",
"type": "integer"
},
"submission_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Submission Status"
},
"tagline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tagline"
},
"telemetry": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Telemetry"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"use_cases": {
"default": [],
"items": {
"$ref": "#/components/schemas/UseCase"
},
"title": "Use Cases",
"type": "array"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Video Url"
},
"visibility_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Visibility Status"
}
},
"required": [
"source",
"plugin_name",
"manifest_name"
],
"title": "PluginDetailResponse",
"type": "object"
},
"PluginResponse": {
"properties": {
"author_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Author Name"
},
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"homepage": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Homepage"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"name": {
"title": "Name",
"type": "string"
},
"source_spec": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Source Spec"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
},
"version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
}
},
"required": [
"name"
],
"title": "PluginResponse",
"type": "object"
},
"PreviewComponent": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"file": {
"title": "File",
"type": "string"
},
"issues": {
"default": [],
"items": {},
"title": "Issues",
"type": "array"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ok": {
"title": "Ok",
"type": "boolean"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"type",
"file",
"ok"
],
"title": "PreviewComponent",
"type": "object"
},
"PreviewResponse": {
"properties": {
"components": {
"default": [],
"items": {
"$ref": "#/components/schemas/PreviewComponent"
},
"title": "Components",
"type": "array"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"type"
],
"title": "PreviewResponse",
"type": "object"
},
"QueryRequest": {
"properties": {
"limit": {
"default": 1000,
"title": "Limit",
"type": "integer"
},
"sql": {
"title": "Sql",
"type": "string"
}
},
"required": [
"sql"
],
"title": "QueryRequest",
"type": "object"
},
"QueryResponse": {
"properties": {
"columns": {
"items": {},
"title": "Columns",
"type": "array"
},
"row_count": {
"title": "Row Count",
"type": "integer"
},
"rows": {
"items": {},
"title": "Rows",
"type": "array"
},
"truncated": {
"default": false,
"title": "Truncated",
"type": "boolean"
}
},
"required": [
"columns",
"rows",
"row_count"
],
"title": "QueryResponse",
"type": "object"
},
"RegisterRequest": {
"description": "Upsert payload \u2014 fields not provided are left untouched on update.\n\n``token = None`` means \"leave existing PAT alone\".\n``token = \"\"`` means \"clear PAT\".\n``token = \"ghp_...\"`` means \"set/rotate PAT\".",
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Branch"
},
"token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Token"
},
"url": {
"title": "Url",
"type": "string"
}
},
"required": [
"url"
],
"title": "RegisterRequest",
"type": "object"
},
"RegisterTableRequest": {
"properties": {
"bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bucket"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"folder": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Folder"
},
"incremental_column": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Incremental Column"
},
"incremental_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Incremental Window Days"
},
"initial_load_chunk_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Initial Load Chunk Days"
},
"max_history_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max History Days"
},
"name": {
"title": "Name",
"type": "string"
},
"partition_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Partition By"
},
"partition_granularity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Partition Granularity"
},
"primary_key": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Primary Key"
},
"profile_after_sync": {
"default": true,
"deprecated": true,
"description": "DEPRECATED: not consumed by the runtime (Agent 1 finding 2026-05-01). Profiler runs unconditionally on every synced table; this flag has no effect. Field stays for back-compat.",
"title": "Profile After Sync",
"type": "boolean"
},
"query_mode": {
"default": "local",
"title": "Query Mode",
"type": "string"
},
"source_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Query"
},
"source_table": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Table"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
},
"sync_schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sync Schedule"
},
"sync_strategy": {
"default": "full_refresh",
"description": "Per-table extraction strategy. v26+: drives the Keboola extractor's dispatcher in connectors/keboola/extractor.py. Allowed values: 'full_refresh' (default; full table dump on each sync), 'incremental' (Storage API changedSince + primary-key dedup merge), 'partitioned' (per-partition parquet files keyed by partition_by column, per-partition merge for daily updates, chunked initial load). Pre-v26 this field was inert; existing rows default to 'full_refresh' so behavior is unchanged unless an admin opts a table in to incremental/partitioned.",
"title": "Sync Strategy",
"type": "string"
},
"where_filters": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Where Filters"
}
},
"required": [
"name"
],
"title": "RegisterTableRequest",
"type": "object"
},
"ResolveContradictionRequest": {
"properties": {
"resolution": {
"title": "Resolution",
"type": "string"
}
},
"required": [
"resolution"
],
"title": "ResolveContradictionRequest",
"type": "object"
},
"ResolveDuplicateRequest": {
"description": "Resolve a duplicate-candidate relation row.\n\n``resolution`` is one of ``duplicate`` / ``different`` / ``dismissed``\n(decision 2 in issue #62 \u2014 no auto-merge action; merging is a separate\nlarger feature).",
"properties": {
"resolution": {
"title": "Resolution",
"type": "string"
}
},
"required": [
"resolution"
],
"title": "ResolveDuplicateRequest",
"type": "object"
},
"RunScriptRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
}
},
"title": "RunScriptRequest",
"type": "object"
},
"SampleInteraction": {
"description": "Example dialog shown in the \"Sample interaction\" section.\n\n``assistant`` is markdown \u2014 the API pre-renders to safe HTML in\n``assistant_html`` so the template can inject without a client-side\nmarkdown lib. ``assistant`` stays as the source for copy-paste / future\nre-rendering needs.",
"properties": {
"assistant": {
"title": "Assistant",
"type": "string"
},
"assistant_html": {
"title": "Assistant Html",
"type": "string"
},
"user": {
"title": "User",
"type": "string"
}
},
"required": [
"user",
"assistant",
"assistant_html"
],
"title": "SampleInteraction",
"type": "object"
},
"ServerConfigUpdateRequest": {
"description": "Patch payload for POST /api/admin/server-config.\n\nOnly the sections listed in `_EDITABLE_SECTIONS` are accepted; anything\nelse is rejected with 400. `confirm_danger` must be true if the patch\ntouches any danger-zone section (auth.*, server.*).",
"properties": {
"confirm_danger": {
"default": false,
"description": "Must be true to apply changes touching auth.* or server.*",
"title": "Confirm Danger",
"type": "boolean"
},
"sections": {
"additionalProperties": {
"additionalProperties": true,
"type": "object"
},
"description": "Per-section patch dict (e.g. {'instance': {'name': 'X'}})",
"title": "Sections",
"type": "object"
}
},
"title": "ServerConfigUpdateRequest",
"type": "object"
},
"SetPasswordRequest": {
"properties": {
"password": {
"title": "Password",
"type": "string"
}
},
"required": [
"password"
],
"title": "SetPasswordRequest",
"type": "object"
},
"StoreEntityListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/StoreEntityResponse"
},
"title": "Items",
"type": "array"
},
"limit": {
"title": "Limit",
"type": "integer"
},
"skip": {
"title": "Skip",
"type": "integer"
},
"total": {
"title": "Total",
"type": "integer"
}
},
"required": [
"items",
"total",
"skip",
"limit"
],
"title": "StoreEntityListResponse",
"type": "object"
},
"StoreEntityResponse": {
"properties": {
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"doc_paths": {
"default": [],
"items": {
"type": "string"
},
"title": "Doc Paths",
"type": "array"
},
"file_size": {
"default": 0,
"title": "File Size",
"type": "integer"
},
"id": {
"title": "Id",
"type": "string"
},
"install_count": {
"default": 0,
"title": "Install Count",
"type": "integer"
},
"invocation_name": {
"title": "Invocation Name",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"owner_display_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner Display Name"
},
"owner_user_id": {
"title": "Owner User Id",
"type": "string"
},
"owner_username": {
"title": "Owner Username",
"type": "string"
},
"photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Photo Url"
},
"type": {
"title": "Type",
"type": "string"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"version": {
"title": "Version",
"type": "string"
},
"video_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Video Url"
},
"visibility_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Visibility Status"
}
},
"required": [
"id",
"type",
"name",
"version",
"owner_user_id",
"owner_username",
"invocation_name"
],
"title": "StoreEntityResponse",
"type": "object"
},
"StoreInstallEntry": {
"properties": {
"category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"entity_id": {
"title": "Entity Id",
"type": "string"
},
"install_count": {
"title": "Install Count",
"type": "integer"
},
"installed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Installed At"
},
"invocation_name": {
"title": "Invocation Name",
"type": "string"
},
"name": {
"title": "Name",
"type": "string"
},
"owner_user_id": {
"title": "Owner User Id",
"type": "string"
},
"owner_username": {
"title": "Owner Username",
"type": "string"
},
"photo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Photo Url"
},
"type": {
"title": "Type",
"type": "string"
},
"version": {
"title": "Version",
"type": "string"
},
"visibility_status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Visibility Status"
}
},
"required": [
"entity_id",
"type",
"name",
"version",
"owner_user_id",
"owner_username",
"invocation_name",
"install_count"
],
"title": "StoreInstallEntry",
"type": "object"
},
"SyncSettingsUpdate": {
"properties": {
"datasets": {
"additionalProperties": true,
"title": "Datasets",
"type": "object"
}
},
"required": [
"datasets"
],
"title": "SyncSettingsUpdate",
"type": "object"
},
"SystemFlagResponse": {
"description": "Return shape of the mark/unmark_system endpoints.",
"properties": {
"affected_groups": {
"default": 0,
"title": "Affected Groups",
"type": "integer"
},
"affected_users": {
"default": 0,
"title": "Affected Users",
"type": "integer"
},
"is_system": {
"title": "Is System",
"type": "boolean"
},
"marketplace_id": {
"title": "Marketplace Id",
"type": "string"
},
"plugin_name": {
"title": "Plugin Name",
"type": "string"
}
},
"required": [
"marketplace_id",
"plugin_name",
"is_system"
],
"title": "SystemFlagResponse",
"type": "object"
},
"TableSubscriptionUpdate": {
"properties": {
"table_mode": {
"default": "all",
"title": "Table Mode",
"type": "string"
},
"tables": {
"additionalProperties": true,
"maxProperties": 500,
"title": "Tables",
"type": "object"
}
},
"title": "TableSubscriptionUpdate",
"type": "object"
},
"TemplatePreviewRequest": {
"properties": {
"content": {
"maxLength": 200000,
"minLength": 1,
"title": "Content",
"type": "string"
}
},
"required": [
"content"
],
"title": "TemplatePreviewRequest",
"type": "object"
},
"TemplatePutRequest": {
"properties": {
"content": {
"maxLength": 200000,
"minLength": 1,
"title": "Content",
"type": "string"
}
},
"required": [
"content"
],
"title": "TemplatePutRequest",
"type": "object"
},
"ToggleRequest": {
"properties": {
"enabled": {
"title": "Enabled",
"type": "boolean"
}
},
"required": [
"enabled"
],
"title": "ToggleRequest",
"type": "object"
},
"TokenListItem": {
"properties": {
"created_at": {
"title": "Created At",
"type": "string"
},
"expires_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Expires At"
},
"id": {
"title": "Id",
"type": "string"
},
"last_used_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Used At"
},
"name": {
"title": "Name",
"type": "string"
},
"prefix": {
"title": "Prefix",
"type": "string"
},
"revoked_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Revoked At"
}
},
"required": [
"id",
"name",
"prefix",
"created_at",
"expires_at",
"last_used_at",
"revoked_at"
],
"title": "TokenListItem",
"type": "object"
},
"TokenRequest": {
"properties": {
"email": {
"title": "Email",
"type": "string"
},
"password": {
"default": "",
"title": "Password",
"type": "string"
}
},
"required": [
"email"
],
"title": "TokenRequest",
"type": "object"
},
"TokenResponse": {
"properties": {
"access_token": {
"title": "Access Token",
"type": "string"
},
"email": {
"title": "Email",
"type": "string"
},
"role": {
"title": "Role",
"type": "string"
},
"token_type": {
"default": "bearer",
"title": "Token Type",
"type": "string"
},
"user_id": {
"title": "User Id",
"type": "string"
}
},
"required": [
"access_token",
"user_id",
"email",
"role"
],
"title": "TokenResponse",
"type": "object"
},
"UpdateGroupRequest": {
"properties": {
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"title": "UpdateGroupRequest",
"type": "object"
},
"UpdateMarketplaceRequest": {
"properties": {
"branch": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Branch"
},
"curator_email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Email"
},
"curator_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Curator Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Token"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url"
}
},
"title": "UpdateMarketplaceRequest",
"type": "object"
},
"UpdateTableRequest": {
"properties": {
"bucket": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bucket"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"incremental_column": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Incremental Column"
},
"incremental_window_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Incremental Window Days"
},
"initial_load_chunk_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Initial Load Chunk Days"
},
"max_history_days": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max History Days"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"partition_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Partition By"
},
"partition_granularity": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Partition Granularity"
},
"primary_key": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Primary Key"
},
"profile_after_sync": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"deprecated": true,
"description": "DEPRECATED: not consumed by the runtime. See RegisterTableRequest.profile_after_sync.",
"title": "Profile After Sync"
},
"query_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Query Mode"
},
"source_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Query"
},
"source_table": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Table"
},
"source_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
},
"sync_schedule": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sync Schedule"
},
"sync_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "v26+: drives the Keboola extractor dispatcher. PUT-shape requires a value if sent. See RegisterTableRequest.sync_strategy.",
"title": "Sync Strategy"
},
"where_filters": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Where Filters"
}
},
"title": "UpdateTableRequest",
"type": "object"
},
"UpdateUserRequest": {
"properties": {
"active": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Active"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"title": "UpdateUserRequest",
"type": "object"
},
"UseCase": {
"description": "One \"When to use it\" example from marketplace-metadata.json.\nCurator-authored: friendly title + 1-2-sentence description + the\nliteral prompt the user would paste into Claude Code.",
"properties": {
"description": {
"title": "Description",
"type": "string"
},
"prompt": {
"title": "Prompt",
"type": "string"
},
"title": {
"title": "Title",
"type": "string"
}
},
"required": [
"title",
"description",
"prompt"
],
"title": "UseCase",
"type": "object"
},
"UserMembershipResponse": {
"properties": {
"added_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Added At"
},
"added_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Added By"
},
"group_id": {
"title": "Group Id",
"type": "string"
},
"group_name": {
"title": "Group Name",
"type": "string"
},
"is_system": {
"default": false,
"title": "Is System",
"type": "boolean"
},
"origin": {
"default": "custom",
"title": "Origin",
"type": "string"
},
"source": {
"title": "Source",
"type": "string"
}
},
"required": [
"group_id",
"group_name",
"source"
],
"title": "UserMembershipResponse",
"type": "object"
},
"UserResponse": {
"properties": {
"active": {
"default": true,
"title": "Active",
"type": "boolean"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"deactivated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deactivated At"
},
"email": {
"title": "Email",
"type": "string"
},
"groups": {
"default": [],
"items": {
"$ref": "#/components/schemas/GroupBrief"
},
"title": "Groups",
"type": "array"
},
"id": {
"title": "Id",
"type": "string"
},
"invite_email_sent": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Invite Email Sent"
},
"invite_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Invite Url"
},
"is_admin": {
"default": false,
"title": "Is Admin",
"type": "boolean"
},
"is_sso_user": {
"default": false,
"title": "Is Sso User",
"type": "boolean"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"role": {
"title": "Role",
"type": "string"
}
},
"required": [
"id",
"email",
"name",
"role",
"created_at"
],
"title": "UserResponse",
"type": "object"
},
"ValidationError": {
"properties": {
"ctx": {
"title": "Context",
"type": "object"
},
"input": {
"title": "Input"
},
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"title": "Location",
"type": "array"
},
"msg": {
"title": "Message",
"type": "string"
},
"type": {
"title": "Error Type",
"type": "string"
}
},
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError",
"type": "object"
},
"VerifyRequest": {
"properties": {
"code": {
"title": "Code",
"type": "string"
}
},
"required": [
"code"
],
"title": "VerifyRequest",
"type": "object"
},
"VoteRequest": {
"properties": {
"vote": {
"title": "Vote",
"type": "integer"
}
},
"required": [
"vote"
],
"title": "VoteRequest",
"type": "object"
},
"_OverrideRequest": {
"properties": {
"reason": {
"maxLength": 2000,
"minLength": 4,
"title": "Reason",
"type": "string"
}
},
"required": [
"reason"
],
"title": "_OverrideRequest",
"type": "object"
},
"app__api__claude_md__TemplateGetResponse": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content"
},
"default": {
"title": "Default",
"type": "string"
},
"legacy_strings_detected": {
"default": [],
"items": {
"type": "string"
},
"title": "Legacy Strings Detected",
"type": "array"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"updated_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated By"
}
},
"required": [
"content",
"default"
],
"title": "TemplateGetResponse",
"type": "object"
},
"app__api__welcome__TemplateGetResponse": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content"
},
"default": {
"title": "Default",
"type": "string"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"updated_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated By"
}
},
"required": [
"content",
"default"
],
"title": "TemplateGetResponse",
"type": "object"
}
}
},
"info": {
"description": "Data distribution platform for AI analytical systems",
"title": "AI Data Analyst",
"version": "0.54.16"
},
"openapi": "3.1.0",
"paths": {
"/": {
"get": {
"operationId": "index__get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Index",
"tags": [
"web"
]
}
},
"/activity-center": {
"get": {
"description": "Legacy URL \u2014 redirect to /admin/activity.",
"operationId": "activity_center_redirect_activity_center_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Activity Center Redirect",
"tags": [
"web"
]
}
},
"/admin/access": {
"get": {
"description": "Resource access management \u2014 master-detail layout with the group list\non the left and per-resource-type checkbox tree on the right. Supports\n``?group=<id>`` deep-link from the group detail page.\n\nUnderlying entity is `resource_grants`; the UI label \"Resource access\"\nmatches what admins think about (who has access) rather than the table\nname (grants).",
"operationId": "admin_access_page_admin_access_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Access Page",
"tags": [
"web"
]
}
},
"/admin/activity": {
"get": {
"description": "Unified observability page \u2014 KPI cards, faceted filter bar, full\naudit_log table with sort/search/saved-views. All data loads\nclient-side from /api/admin/observability/* + /api/admin/activity.",
"operationId": "admin_activity_admin_activity_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Activity",
"tags": [
"web"
]
}
},
"/admin/agent-prompt": {
"get": {
"operationId": "admin_agent_prompt_page_admin_agent_prompt_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Agent Prompt Page",
"tags": [
"web"
]
}
},
"/admin/corporate-memory": {
"get": {
"description": "Curated Memory review queue \u2014 admin-only.\n\nThe governance surface paired with the user-facing ``/corporate-memory``\npage: pending items awaiting review, contradictions, duplicate\ncandidates, and the audit trail. Reached from the Admin nav dropdown.",
"operationId": "corporate_memory_admin_admin_corporate_memory_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Corporate Memory Admin",
"tags": [
"web"
]
}
},
"/admin/grants": {
"get": {
"description": "Backward-compat redirect for the page's previous URL.",
"operationId": "admin_grants_redirect_admin_grants_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Admin Grants Redirect",
"tags": [
"web"
]
}
},
"/admin/groups": {
"get": {
"description": "Group list view \u2014 full-width table of user_groups with origin chips,\nmember/grant counts, and edit/delete affordances for non-system rows.",
"operationId": "admin_groups_page_admin_groups_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Groups Page",
"tags": [
"web"
]
}
},
"/admin/groups/{group_id}": {
"get": {
"description": "Single-group detail page \u2014 header + members table. Resource grants\nlive on /admin/grants (deep-linked from here).",
"operationId": "admin_group_detail_page_admin_groups__group_id__get",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Group Detail Page",
"tags": [
"web"
]
}
},
"/admin/marketplaces": {
"get": {
"description": "Admin page for marketplace git repositories (register / sync / delete).",
"operationId": "admin_marketplaces_page_admin_marketplaces_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Marketplaces Page",
"tags": [
"web"
]
}
},
"/admin/news": {
"get": {
"description": "Admin authoring surface \u2014 current published banner, draft editor,\nversions table. JS hits the /api/admin/news/* endpoints for the\nwrite paths.",
"operationId": "admin_news_editor_admin_news_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin News Editor",
"tags": [
"web"
]
}
},
"/admin/scheduler-runs": {
"get": {
"description": "Scheduler runs is now a filter on the unified Activity page, not a\nstandalone view \u2014 see the unification done in the platform-telemetry\nepic. Keep the URL as a 308 so existing bookmarks land on the right\npre-filtered view.",
"operationId": "admin_scheduler_runs_redirect_admin_scheduler_runs_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Scheduler Runs Redirect",
"tags": [
"web"
]
}
},
"/admin/server-config": {
"get": {
"description": "Server configuration editor \u2014 instance.yaml fields grouped by section.\n\nShell-only page. The form is populated client-side from\nGET /api/admin/server-config (which redacts secrets) and submitted\nsection-by-section to POST /api/admin/server-config. Auth/server\nsections require an explicit confirmation dialog before save (see\n``_DANGER_SECTIONS`` in the API). Saves trigger the \"restart required\"\nbanner \u2014 hot-reload is out of scope for #91.",
"operationId": "admin_server_config_page_admin_server_config_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Server Config Page",
"tags": [
"web"
]
}
},
"/admin/sessions": {
"get": {
"description": "Global Sessions browser \u2014 every collected session JSONL across all\nusers. The list page is a shell; data loads client-side via\n/api/admin/sessions/{list,kpis,facets}.",
"operationId": "admin_sessions_page_admin_sessions_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Sessions Page",
"tags": [
"web"
]
}
},
"/admin/sessions/{username}/{session_file}": {
"get": {
"description": "Session transcript viewer. Username + session_file are revalidated by\nthe API route (regex + path-escape guard) when /transcript is fetched;\nhere we just render the shell.",
"operationId": "admin_session_detail_admin_sessions__username___session_file__get",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"title": "Username",
"type": "string"
}
},
{
"in": "path",
"name": "session_file",
"required": true,
"schema": {
"title": "Session File",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Session Detail",
"tags": [
"web"
]
}
},
"/admin/store/submissions": {
"get": {
"description": "Triage page for flea-market guardrail submissions.\n\nLists every submission row newest-first with the inline-check verdicts,\nLLM findings, and override action buttons. Server-side render keeps the\npage accessible without JS for the read-only inspect path; mutating\nactions (override, retry, delete) hit the JSON admin endpoints under\n``/api/admin/store/submissions``.\n\nFilters AND together; URL is bookmarkable. Pagination via ``skip`` /\n``limit`` (default 50, clamped to [1, 200] for the UI page-size\nselector).",
"operationId": "admin_store_submissions_page_admin_store_submissions_get",
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
}
},
{
"in": "query",
"name": "submitter",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Submitter"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"in": "query",
"name": "name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
{
"in": "query",
"name": "version",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sort"
}
},
{
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Order"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "skip",
"required": false,
"schema": {
"default": 0,
"title": "Skip",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Store Submissions Page",
"tags": [
"web"
]
}
},
"/admin/store/submissions/{submission_id}": {
"get": {
"description": "Per-submission detail with full verdict + override + retry actions.",
"operationId": "admin_store_submission_detail_page_admin_store_submissions__submission_id__get",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Store Submission Detail Page",
"tags": [
"web"
]
}
},
"/admin/tables": {
"get": {
"operationId": "admin_tables_admin_tables_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Tables",
"tags": [
"web"
]
}
},
"/admin/telemetry": {
"get": {
"description": "Interactive Telemetry page \u2014 filter / group-by / search on usage_events.\n\nAll data loads client-side from /api/admin/telemetry/* (facets, kpis,\nquery) so the page state lives in the URL and the server doesn't\npreload a fixed window's snapshot.",
"operationId": "admin_telemetry_page_admin_telemetry_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Telemetry Page",
"tags": [
"web"
]
}
},
"/admin/tokens": {
"get": {
"description": "Admin \u2014 list of ALL tokens for incident response + offboarding.\n\nAdmin-only. No create form here (admins mint their own PATs via /me/profile).\nURL param ?user=<email> pre-fills the owner filter (deep-link from\n/admin/users \"Tokens\" action).",
"operationId": "admin_tokens_page_admin_tokens_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Tokens Page",
"tags": [
"web"
]
}
},
"/admin/usage": {
"get": {
"description": "Legacy URL \u2014 308 to /admin/telemetry. The page was renamed in the\nplatform-telemetry epic to match what's actually shown (tool/skill\ninvocations from session JSONLs). Old bookmarks land on the right\nplace without breaking.",
"operationId": "admin_usage_redirect_admin_usage_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Usage Redirect",
"tags": [
"web"
]
}
},
"/admin/users": {
"get": {
"description": "Admin page for user management.",
"operationId": "admin_users_page_admin_users_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Users Page",
"tags": [
"web"
]
}
},
"/admin/users/{user_id}": {
"get": {
"description": "Per-user detail page \u2014 core role + module capabilities + effective-roles debug.\n\nRenders shell HTML; the JS bootstraps all role data via the admin REST API\n(/api/admin/internal-roles, /api/admin/users/{id}/role-grants,\n/api/admin/users/{id}/effective-roles). Server-side we only need the\ntarget user's email + name so the page header renders before the API\nround-trips finish; everything role-related is loaded client-side so an\nadmin reload picks up state changes from a sibling tab without a\nfull-page reload elsewhere.",
"operationId": "admin_user_detail_page_admin_users__user_id__get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin User Detail Page",
"tags": [
"web"
]
}
},
"/admin/workspace-prompt": {
"get": {
"operationId": "admin_workspace_prompt_page_admin_workspace_prompt_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Workspace Prompt Page",
"tags": [
"web"
]
}
},
"/api/admin/access-overview": {
"get": {
"description": "One-shot snapshot for the /admin/access page.\n\nReturns:\n - ``groups``: every user_group with member + grant counts\n - ``grants``: every (group_id, resource_type, resource_id) row\n - ``resources``: per-resource-type hierarchical layout, where each\n type has a list of *blocks* (parent entities, e.g. a marketplace)\n and each block has *items* (concrete grantable resources).\n\nUI stitches the three pieces into the two-column layout: groups on\nthe left, resources tree on the right with per-item checkboxes whose\nstate derives from ``grants``.",
"operationId": "access_overview_api_admin_access_overview_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Access Overview Api Admin Access Overview Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Access Overview",
"tags": [
"access"
]
}
},
"/api/admin/activity": {
"get": {
"operationId": "activity_timeline_api_admin_activity_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 1440,
"maximum": 43200,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
{
"in": "query",
"name": "action_prefix",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Action Prefix"
}
},
{
"in": "query",
"name": "resource",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resource"
}
},
{
"in": "query",
"name": "result_pattern",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Result Pattern"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "query",
"name": "cursor_ts",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Ts"
}
},
{
"in": "query",
"name": "cursor_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Id"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Activity Timeline",
"tags": [
"activity"
]
}
},
"/api/admin/activity/health": {
"get": {
"operationId": "activity_health_api_admin_activity_health_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Activity Health",
"tags": [
"activity"
]
}
},
"/api/admin/activity/sync": {
"get": {
"operationId": "activity_sync_api_admin_activity_sync_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 1440,
"maximum": 43200,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 100,
"maximum": 500,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Activity Sync",
"tags": [
"activity"
]
}
},
"/api/admin/bigquery/test-connection": {
"post": {
"description": "Run `SELECT 1 AS ok` against BigQuery via the configured BqAccess.\n\nReturns 200 with `{ok, billing_project, data_project, elapsed_ms}` on\nsuccess. Maps known failure modes:\n\n- `BqAccessError(not_configured)` \u2192 400 with the typed detail\n- `BqAccessError` (other kinds) \u2192 502 with the typed detail\n- `concurrent.futures.TimeoutError` \u2192 504 with `kind=\"timeout\"` and\n best-effort `cancel_job` invoked",
"operationId": "test_connection_api_admin_bigquery_test_connection_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Test Connection",
"tags": [
"admin"
]
}
},
"/api/admin/cache-warmup/run": {
"post": {
"operationId": "warmup_run_api_admin_cache_warmup_run_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Warmup Run"
}
},
"/api/admin/cache-warmup/status": {
"get": {
"operationId": "warmup_status_api_admin_cache_warmup_status_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Warmup Status"
}
},
"/api/admin/cache-warmup/stream": {
"get": {
"operationId": "warmup_stream_api_admin_cache_warmup_stream_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Warmup Stream"
}
},
"/api/admin/configure": {
"post": {
"description": "Configure data source and instance settings via API.\n\nWrites config to instance.yaml and persists secrets to .env_overlay.\nAI agents and the /setup wizard use this instead of manual file editing.",
"operationId": "configure_instance_api_admin_configure_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConfigureRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Configure Instance",
"tags": [
"admin"
]
}
},
"/api/admin/discover-and-register": {
"post": {
"description": "Discover tables from configured source and auto-register them.\n\nCombines discover-tables + register-table into one call. Already-\nregistered rows are NEVER overwritten \u2014 admin edits to bucket /\nsource_table win. The response surfaces a ``drift`` array listing\nany rows where discovery would have written different coordinates\nthan what's in the registry, so operators can audit divergence\nafter a Keboola-side bucket rename / table move.\n\nQuery params:\n - ``dry_run=true`` returns the plan without writing anything.\n Lists ``would_register``, ``drift``, and ``invalid`` so an\n operator can decide whether to proceed (or, in the drift case,\n which side they want to fix).\n\nUsed by /setup wizard and AI agents.",
"operationId": "discover_and_register_api_admin_discover_and_register_post",
"parameters": [
{
"in": "query",
"name": "dry_run",
"required": false,
"schema": {
"default": false,
"title": "Dry Run",
"type": "boolean"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Discover And Register",
"tags": [
"admin"
]
}
},
"/api/admin/discover-tables": {
"get": {
"description": "Discover available tables from the configured data source.\n\nFor ``data_source.type='keboola'`` returns the full Storage API table\nlist (single round-trip). For ``data_source.type='bigquery'``:\n\n- Without ``dataset``: list datasets in the configured project.\n- With ``dataset=name``: list tables (BASE TABLE + VIEW) in that dataset.\n\nTwo-step shape avoids paying the per-dataset list_tables cost up-front\non projects with hundreds of datasets \u2014 the UI populates the dataset\ndropdown first, then fetches tables only for the selected dataset.",
"operationId": "discover_tables_api_admin_discover_tables_get",
"parameters": [
{
"in": "query",
"name": "dataset",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Dataset"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Discover Tables",
"tags": [
"admin"
]
}
},
"/api/admin/grants": {
"get": {
"operationId": "list_grants_api_admin_grants_get",
"parameters": [
{
"in": "query",
"name": "resource_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Resource Type"
}
},
{
"in": "query",
"name": "group_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Group Id"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/GrantResponse"
},
"title": "Response List Grants Api Admin Grants Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Grants",
"tags": [
"access"
]
},
"post": {
"operationId": "create_grant_api_admin_grants_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGrantRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GrantResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Grant",
"tags": [
"access"
]
}
},
"/api/admin/grants/{grant_id}": {
"delete": {
"operationId": "delete_grant_api_admin_grants__grant_id__delete",
"parameters": [
{
"in": "path",
"name": "grant_id",
"required": true,
"schema": {
"title": "Grant Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Grant",
"tags": [
"access"
]
}
},
"/api/admin/groups": {
"get": {
"operationId": "list_groups_api_admin_groups_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/GroupResponse"
},
"title": "Response List Groups Api Admin Groups Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Groups",
"tags": [
"access"
]
},
"post": {
"operationId": "create_group_api_admin_groups_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateGroupRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Group",
"tags": [
"access"
]
}
},
"/api/admin/groups/{group_id}": {
"delete": {
"operationId": "delete_group_api_admin_groups__group_id__delete",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Group",
"tags": [
"access"
]
},
"get": {
"description": "Single-group payload for the /admin/groups/{id} detail page header.",
"operationId": "get_group_api_admin_groups__group_id__get",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Group",
"tags": [
"access"
]
},
"patch": {
"operationId": "update_group_api_admin_groups__group_id__patch",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateGroupRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GroupResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Group",
"tags": [
"access"
]
}
},
"/api/admin/groups/{group_id}/members": {
"get": {
"operationId": "list_members_api_admin_groups__group_id__members_get",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/MemberResponse"
},
"title": "Response List Members Api Admin Groups Group Id Members Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Members",
"tags": [
"access"
]
},
"post": {
"operationId": "add_member_api_admin_groups__group_id__members_post",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddMemberRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemberResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Add Member",
"tags": [
"access"
]
}
},
"/api/admin/groups/{group_id}/members/{user_id}": {
"delete": {
"operationId": "remove_member_api_admin_groups__group_id__members__user_id__delete",
"parameters": [
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Remove Member",
"tags": [
"access"
]
}
},
"/api/admin/initial-workspace": {
"delete": {
"description": "Remove the ``initial_workspace:`` config + PAT.\n\nOptional ``?purge=true`` also wipes ``${DATA_DIR}/initial-workspace/``\nfrom disk. Default leaves the working copy in place so an admin can\ninspect / re-register the same URL without re-cloning.",
"operationId": "admin_delete_api_admin_initial_workspace_delete",
"parameters": [
{
"in": "query",
"name": "purge",
"required": false,
"schema": {
"default": false,
"title": "Purge",
"type": "boolean"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Delete",
"tags": [
"initial_workspace"
]
},
"get": {
"description": "Return the current ``initial_workspace:`` config + sync state.",
"operationId": "admin_get_api_admin_initial_workspace_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminInitialWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Get",
"tags": [
"initial_workspace"
]
},
"post": {
"description": "Register / update the template repo.\n\nOnly ``url``, ``branch``, and ``token_env`` land in the YAML overlay.\nSync state (``last_synced_at`` / ``last_commit_sha`` / ``last_error``)\nis written by ``POST .../sync``, not here \u2014 saving a config change\nshould NOT silently invalidate the existing sync state.",
"operationId": "admin_post_api_admin_initial_workspace_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminInitialWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Post",
"tags": [
"initial_workspace"
]
}
},
"/api/admin/initial-workspace/sync": {
"post": {
"description": "Manual \"Sync now\" \u2014 clone or fast-forward the template repo, then\npersist ``last_synced_at`` + ``last_commit_sha`` (or ``last_error``)\nback to the YAML overlay.\n\nReturns ``{action, commit_sha, file_count, path}`` on success or\nsurfaces a ``400`` with the validation / git error so the admin sees\nit in the Sync-now modal. The error payload uses the typed-``kind``\nshape the CLI's error renderer already understands.",
"operationId": "admin_sync_api_admin_initial_workspace_sync_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Sync",
"tags": [
"initial_workspace"
]
}
},
"/api/admin/metadata/{table_id}": {
"get": {
"description": "Return column metadata for a table.",
"operationId": "get_table_metadata_api_admin_metadata__table_id__get",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Table Metadata",
"tags": [
"metadata"
]
},
"post": {
"description": "Save column metadata for a table. Admin only.",
"operationId": "save_table_metadata_api_admin_metadata__table_id__post",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ColumnMetadataSave"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Save Table Metadata",
"tags": [
"metadata"
]
}
},
"/api/admin/metadata/{table_id}/push": {
"post": {
"description": "Push column metadata to Keboola Storage API. Admin only.",
"operationId": "push_metadata_to_source_api_admin_metadata__table_id__push_post",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Push Metadata To Source",
"tags": [
"metadata"
]
}
},
"/api/admin/metrics": {
"post": {
"description": "Create or update a metric definition (admin only).",
"operationId": "create_or_update_metric_api_admin_metrics_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricCreate"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Or Update Metric",
"tags": [
"metrics"
]
}
},
"/api/admin/metrics/import": {
"post": {
"description": "Import metrics from uploaded YAML file.",
"operationId": "import_metrics_api_admin_metrics_import_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_import_metrics_api_admin_metrics_import_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Import Metrics",
"tags": [
"metrics"
]
}
},
"/api/admin/metrics/{metric_id}": {
"delete": {
"description": "Delete a metric definition by ID (admin only).",
"operationId": "delete_metric_api_admin_metrics__metric_id__delete",
"parameters": [
{
"in": "path",
"name": "metric_id",
"required": true,
"schema": {
"title": "Metric Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Metric",
"tags": [
"metrics"
]
}
},
"/api/admin/news/current": {
"get": {
"description": "Latest published version (or {published: false} if none).",
"operationId": "get_current_api_admin_news_current_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Current",
"tags": [
"news"
]
}
},
"/api/admin/news/draft": {
"get": {
"description": "Active draft. 404 if none \u2014 UI shows 'create new draft' button.",
"operationId": "get_draft_api_admin_news_draft_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Draft",
"tags": [
"news"
]
},
"put": {
"description": "Upsert the active draft. Sanitizes both fields BEFORE writing.\n\nOptimistic-lock: when `expected_version` is supplied (query string),\nthe request fails with 409 unless the active draft is at that\nversion. Pass `expected_version=0` when you intend to create the\nfirst draft and want the call to fail if another admin already\nstarted one.",
"operationId": "put_draft_api_admin_news_draft_put",
"parameters": [
{
"in": "query",
"name": "expected_version",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Expected Version"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewsBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Put Draft",
"tags": [
"news"
]
}
},
"/api/admin/news/preview": {
"post": {
"description": "Sanitize candidate intro + content and return \u2014 no DB writes.",
"operationId": "post_preview_api_admin_news_preview_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewsBody"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Post Preview",
"tags": [
"news"
]
}
},
"/api/admin/news/publish": {
"post": {
"description": "Publish the active draft.\n\nWhen `expected_version` is supplied (query string), the request\nfails with 409 unless the active draft is at that version. Use\nthis when reviewing a specific draft before flipping it live so\na concurrent admin's edit doesn't slip through under your name.",
"operationId": "post_publish_api_admin_news_publish_post",
"parameters": [
{
"in": "query",
"name": "expected_version",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Expected Version"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Post Publish",
"tags": [
"news"
]
}
},
"/api/admin/news/unpublish/{version}": {
"post": {
"operationId": "post_unpublish_api_admin_news_unpublish__version__post",
"parameters": [
{
"in": "path",
"name": "version",
"required": true,
"schema": {
"title": "Version",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Post Unpublish",
"tags": [
"news"
]
}
},
"/api/admin/news/versions": {
"get": {
"operationId": "list_versions_api_admin_news_versions_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Versions",
"tags": [
"news"
]
}
},
"/api/admin/news/versions/{version}": {
"get": {
"operationId": "get_version_api_admin_news_versions__version__get",
"parameters": [
{
"in": "path",
"name": "version",
"required": true,
"schema": {
"title": "Version",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Version",
"tags": [
"news"
]
}
},
"/api/admin/observability/facets": {
"get": {
"description": "Return the distinct facet values present in `audit_log` for the\nselected window, each with a count. The UI uses these to populate the\nfilter dropdowns \u2014 so an admin sees only users/actions that actually\nexist, not a free-text guess.\n\nCounts are capped at 50 per facet (largest first). 50 is comfortable in\na dropdown; tighter windows usually have <20 anyway.",
"operationId": "facets_api_admin_observability_facets_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 1440,
"maximum": 43200,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Facets",
"tags": [
"observability"
]
}
},
"/api/admin/observability/kpis": {
"get": {
"description": "Four KPIs for the top-bar cards: events, active users, error rate, p95.",
"operationId": "kpis_api_admin_observability_kpis_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 1440,
"maximum": 43200,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Kpis",
"tags": [
"observability"
]
}
},
"/api/admin/observability/views": {
"get": {
"operationId": "list_views_api_admin_observability_views_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Views",
"tags": [
"observability"
]
},
"post": {
"operationId": "save_view_api_admin_observability_views_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Payload",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Save View",
"tags": [
"observability"
]
}
},
"/api/admin/observability/views/{view_id}": {
"delete": {
"operationId": "delete_view_api_admin_observability_views__view_id__delete",
"parameters": [
{
"in": "path",
"name": "view_id",
"required": true,
"schema": {
"title": "View Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete View",
"tags": [
"observability"
]
}
},
"/api/admin/register-table": {
"post": {
"description": "Register a new table in the system.\n\nBehavior by source_type:\n- **bigquery**: validates BQ-specific shape (dataset / source_table /\n identifier safety / project_id format), forces query_mode='remote' and\n profile_after_sync=False, then synchronously rebuilds extract.duckdb +\n master views with a wall-clock budget. Returns 200 with the view name\n on success, 202 on budget overrun (rebuild continues in a\n BackgroundTask), or 500 if the synchronous rebuild ran but reported\n an error (e.g. auth failure, missing project, unsafe identifier).\n- other source types: insert-only, no post-register hook. Returns 201.\n\nDefined as a plain ``def`` (not ``async def``) so FastAPI runs it in a\nthreadpool \u2014 the synchronous-materialize path waits on\n``threading.Event.wait()``, which would otherwise block the asyncio\nevent loop and stall every other request for up to ``_BQ_SYNC_REGISTER_\nTIMEOUT_S``. ``Depends(...)``, ``BackgroundTasks``, and\n``JSONResponse`` all work the same in sync handlers; the rest of the\nadmin module mixes both styles already.\n\nThe route does NOT carry a default ``status_code`` \u2014 each branch returns\nits own JSONResponse with the right code. A blanket ``status_code=201``\non the decorator would mislead OpenAPI consumers about the BQ branch.\n\nAlways: 409 on view-name collision against the existing registry, audit\nlog entry on success.",
"operationId": "register_table_api_admin_register_table_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterTableRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "BigQuery row registered + materialized synchronously"
},
"201": {
"description": "Non-BigQuery row registered (no post-insert materialize)"
},
"202": {
"description": "BigQuery row registered; materialize continues in background"
},
"409": {
"description": "Table id or view name already in use"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
},
"500": {
"description": "BigQuery row registered but post-insert rebuild failed"
}
},
"summary": "Register Table",
"tags": [
"admin"
]
}
},
"/api/admin/register-table/precheck": {
"post": {
"description": "Validate a register-table payload + (BQ only) confirm the source table exists.\n\nNo DB write. Used by the UI to surface row count + size + column count\nin the modal before the operator clicks Register, and by the CLI's\n``--dry-run`` to print what *would* be registered without touching\nstate. Identical Pydantic validation to register-table; for BQ rows we\nadditionally make a ``bigquery.Client(project).get_table(...)`` call\nand surface the GCP error verbatim.\n\nDefined as a plain ``def`` (not ``async def``) so FastAPI runs it in a\nthreadpool \u2014 the BQ branch makes synchronous ``bigquery.Client(...)``\n/``client.get_table(...)`` calls, which would otherwise block the\nasyncio event loop and stall every other request for the duration of\nthe GCE round-trip. Mirrors the same conversion done for\n``register_table`` (see comment on that route). ``Depends(...)`` works\nidentically in sync handlers.",
"operationId": "register_table_precheck_api_admin_register_table_precheck_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RegisterTableRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Register Table Precheck",
"tags": [
"admin"
]
}
},
"/api/admin/registry": {
"get": {
"description": "Get full table registry.\n\nEach table row is enriched with `last_sync_error` from sync_state so\noperators can see WHY a row isn't materializing without trawling\nscheduler logs. None for rows that have never errored or have already\nrecovered (status='ok'); the per-row error message string otherwise.",
"operationId": "list_registry_api_admin_registry_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Registry",
"tags": [
"admin"
]
}
},
"/api/admin/registry/{table_id}": {
"delete": {
"description": "Unregister a table from the system.\n\nFor BQ rows, schedules a background rebuild so the dropped row's\nmaster view is removed from analytics.duckdb (rather than hanging\naround until the next scheduled sync).\n\nFor materialized rows, also removes the canonical parquet at\n`${DATA_DIR}/extracts/<source_type>/data/<id>.parquet` and clears\nthe matching `sync_state` row. Without these two cleanups, the\nmanifest endpoint kept advertising the dropped table to `agnes pull`\n(sync_state-driven) and the orchestrator's next rebuild could\nresurrect a master view from the leftover parquet (E2E sub-agent\nfinding 2026-05-01).",
"operationId": "unregister_table_api_admin_registry__table_id__delete",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Unregister Table",
"tags": [
"admin"
]
},
"put": {
"description": "Update a registered table's configuration.\n\nFor BQ rows, schedules a background rebuild so the master view picks\nup changes (e.g. a renamed dataset) without waiting for the next\nscheduled sync.",
"operationId": "update_table_api_admin_registry__table_id__put",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateTableRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Table",
"tags": [
"admin"
]
}
},
"/api/admin/resource-types": {
"get": {
"description": "List the resource types defined in app.resource_types.\n\nNo DB call \u2014 these come from the ``ResourceType`` StrEnum. The shape\nis ``[{key, display_name, description, id_format}]`` so the admin UI\ncan render the create-grant form's resource_type dropdown plus a\nplaceholder hint for the ``resource_id`` input.",
"operationId": "get_resource_types_api_admin_resource_types_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Response Get Resource Types Api Admin Resource Types Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Resource Types",
"tags": [
"access"
]
}
},
"/api/admin/run-blocked-purge": {
"post": {
"description": "Trigger the TTL purge of blocked bundle bytes.\n\nWraps :func:`src.store_guardrails.purge.purge_blocked_bundles`. The\nscheduler service hits this endpoint daily (under\n``SCHEDULER_API_TOKEN`` like the corporate-memory + verification\njobs); admins can also run it on demand from the UI.",
"operationId": "run_blocked_purge_api_admin_run_blocked_purge_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Blocked Purge",
"tags": [
"admin"
]
}
},
"/api/admin/run-bq-metadata-refresh": {
"post": {
"description": "Refresh metadata for every remote BQ row in the registry.\n\nCalled by the scheduler at ``SCHEDULER_BQ_METADATA_REFRESH_INTERVAL``\n(default 4 h). Single-flight guarded: if a refresh is already\nrunning (e.g. operator clicked \"Re-warm all\" while a scheduler tick\nis in flight, or two scheduler containers raced during an upgrade),\nthe second caller gets ``409 already_running`` with the in-flight\n``run_id`` + ``started_at`` so they can correlate against logs.\nThe scheduler treats 409 as a no-op success.\n\nBounded concurrency within a run (default 4, override via\n``AGNES_BQ_METADATA_REFRESH_CONCURRENCY``) so a deployment with\nmany remote tables doesn't fan out to dozens of parallel BQ jobs.",
"operationId": "run_bq_metadata_refresh_api_admin_run_bq_metadata_refresh_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Bq Metadata Refresh"
}
},
"/api/admin/run-corporate-memory": {
"post": {
"description": "Trigger the corporate-memory catalog refresh from the scheduler.\n\nReads all CLAUDE.local.md files, sends them through the LLM with the\nexisting catalog, and writes an updated catalog to knowledge.json.",
"operationId": "run_corporate_memory_api_admin_run_corporate_memory_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Corporate Memory",
"tags": [
"admin"
]
}
},
"/api/admin/run-reap-stuck-reviews": {
"post": {
"description": "Trigger the stuck-review reaper.\n\nWraps :func:`src.store_guardrails.reaper.reap_stuck_llm_reviews`.\nThe scheduler hits this every 15 minutes; admins can run it on\ndemand if a worker crash is suspected. Flips any\n``status='pending_llm'`` row older than the configured grace to\n``review_error`` so the queue stops growing indefinitely.",
"operationId": "run_reap_stuck_reviews_api_admin_run_reap_stuck_reviews_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Reap Stuck Reviews",
"tags": [
"admin"
]
}
},
"/api/admin/run-session-collector": {
"post": {
"description": "Trigger the session-collector job from the scheduler.\n\nWalks /home/*/user/sessions/*.jsonl and copies new files into\n/data/user_sessions/<user>/. Idempotent \u2014 already-collected files\nare skipped.",
"operationId": "run_session_collector_api_admin_run_session_collector_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Session Collector",
"tags": [
"admin"
]
}
},
"/api/admin/run-session-processor": {
"post": {
"description": "Trigger one session-pipeline processor against /data/user_sessions/*.\n\nReplaces the per-processor /run-* endpoints with a single parametrized\nentry. The scheduler invokes this once per registered processor on its\nown cadence; processors are independent (one slow / failing processor\ncan't block any other).\n\nReturns 400 if `processor` is unknown. The verification processor\nrequires an LLM extractor \u2014 if the instance has no ai: config and no\nANTHROPIC_API_KEY / LLM_API_KEY, it won't appear in the registry and\nthe call returns 400 the same as a misspelled name.",
"operationId": "run_session_processor_api_admin_run_session_processor_post",
"parameters": [
{
"description": "Processor name (e.g. 'verification', 'usage')",
"in": "query",
"name": "processor",
"required": true,
"schema": {
"description": "Processor name (e.g. 'verification', 'usage')",
"title": "Processor",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Session Processor",
"tags": [
"admin"
]
}
},
"/api/admin/server-config": {
"get": {
"description": "Return the current instance.yaml with secrets redacted.\n\nUsed by the /admin/server-config UI to prefill its form. The redacted\npayload mirrors the actual file shape, so the UI doesn't need to know\nthe schema \u2014 it iterates over the editable sections and renders the\nfields it finds. Empty sections still show in the response so the form\nknows to render their headers.",
"operationId": "get_server_config_api_admin_server_config_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Server Config",
"tags": [
"admin"
]
},
"post": {
"description": "Patch instance.yaml from the /admin/server-config editor.\n\nAccepts a partial patch keyed by section. Validates sections, refuses\ndanger-zone edits without explicit confirmation, deep-merges into the\ncurrent overlay, writes the file, and emits one audit entry per save\nwith a sanitized diff. Returns ``restart_required=true`` so the UI can\nshow the restart banner \u2014 hot-reload is a separate issue (see #91 Out\nof scope).",
"operationId": "update_server_config_api_admin_server_config_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerConfigUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Server Config",
"tags": [
"admin"
]
}
},
"/api/admin/sessions/facets": {
"get": {
"operationId": "facets_api_admin_sessions_facets_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Facets",
"tags": [
"admin-sessions"
]
}
},
"/api/admin/sessions/kpis": {
"get": {
"operationId": "kpis_api_admin_sessions_kpis_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "username",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Username"
}
},
{
"in": "query",
"name": "model",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
}
},
{
"in": "query",
"name": "only_errors",
"required": false,
"schema": {
"default": false,
"title": "Only Errors",
"type": "boolean"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Kpis",
"tags": [
"admin-sessions"
]
}
},
"/api/admin/sessions/list": {
"get": {
"operationId": "list_sessions_api_admin_sessions_list_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "username",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Username"
}
},
{
"in": "query",
"name": "model",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
}
},
{
"in": "query",
"name": "only_errors",
"required": false,
"schema": {
"default": false,
"title": "Only Errors",
"type": "boolean"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"default": "started_at:desc",
"title": "Sort",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"maximum": 50000,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Sessions",
"tags": [
"admin-sessions"
]
}
},
"/api/admin/sessions/{username}/{session_file}/download": {
"get": {
"description": "Stream a single JSONL straight from disk. Path-safety guarded the\nsame way as ``/transcript``. Audit-logged.",
"operationId": "download_api_admin_sessions__username___session_file__download_get",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"title": "Username",
"type": "string"
}
},
{
"in": "path",
"name": "session_file",
"required": true,
"schema": {
"title": "Session File",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Download",
"tags": [
"admin-sessions"
]
}
},
"/api/admin/sessions/{username}/{session_file}/transcript": {
"get": {
"operationId": "transcript_api_admin_sessions__username___session_file__transcript_get",
"parameters": [
{
"in": "path",
"name": "username",
"required": true,
"schema": {
"title": "Username",
"type": "string"
}
},
{
"in": "path",
"name": "session_file",
"required": true,
"schema": {
"title": "Session File",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Transcript",
"tags": [
"admin-sessions"
]
}
},
"/api/admin/store/submissions": {
"get": {
"description": "List flea-market guardrail submissions newest-first.\n\nAll filters AND together. ``status`` is comma-separated\n(e.g. ``blocked_inline,blocked_llm``). ``submitter`` matches\n``submitter_id`` exactly. ``type`` is one of ``skill`` / ``agent`` /\n``plugin``. ``name`` and ``version`` are case-insensitive substrings.\n``limit`` clamped to [1, 500].",
"operationId": "admin_list_store_submissions_api_admin_store_submissions_get",
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status"
}
},
{
"in": "query",
"name": "submitter",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Submitter"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"in": "query",
"name": "name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
{
"in": "query",
"name": "version",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Version"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Sort"
}
},
{
"in": "query",
"name": "order",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Order"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 100,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "skip",
"required": false,
"schema": {
"default": 0,
"title": "Skip",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin List Store Submissions",
"tags": [
"admin"
]
}
},
"/api/admin/store/submissions/{submission_id}": {
"delete": {
"description": "Hard-delete a submission record + its linked bundle (if any).\n\nUse this for spam / accidental uploads after override-publish is the\nwrong call. The audit_log row preserves what was deleted in case\ntriage needs the evidence trail later.",
"operationId": "admin_delete_store_submission_api_admin_store_submissions__submission_id__delete",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Delete Store Submission",
"tags": [
"admin"
]
},
"get": {
"operationId": "admin_get_store_submission_api_admin_store_submissions__submission_id__get",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Get Store Submission",
"tags": [
"admin"
]
}
},
"/api/admin/store/submissions/{submission_id}/bundle.zip": {
"get": {
"description": "Stream the on-disk bundle as a fresh ZIP for admin inspection.\n\nRequired by the forensic use case: admin needs to inspect what a\nsubmitter actually tried to upload (not just the verdict). Bundle\nmust still be on disk \u2014 TTL purge nulls ``entity_id`` and removes\nthe directory, in which case this returns 410.",
"operationId": "admin_download_store_submission_bundle_api_admin_store_submissions__submission_id__bundle_zip_get",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Download Store Submission Bundle",
"tags": [
"admin"
]
}
},
"/api/admin/store/submissions/{submission_id}/override": {
"post": {
"description": "Force-publish a previously-blocked submission.\n\nFlips the submission to ``status='overridden'`` and the linked\nstore_entities row to ``visibility_status='approved'``. Audit row\ncaptures who, why, and the verdict that was overridden so the next\ntime this submission shows up, the trail is intact.",
"operationId": "admin_override_store_submission_api_admin_store_submissions__submission_id__override_post",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/_OverrideRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Override Store Submission",
"tags": [
"admin"
]
}
},
"/api/admin/store/submissions/{submission_id}/rescan": {
"post": {
"description": "Re-run **all** guardrail checks (inline + LLM) against the current\nbundle.\n\nDifferent from ``/retry``: rescan starts from scratch (re-runs the\ndeterministic inline checks too) and is allowed regardless of\ncurrent status. Use when check rules have changed and a previously-\napproved entity might now fail (or vice versa).\n\nEffects:\n * inline checks run sync; verdict written to ``inline_checks``\n * on inline fail \u2192 ``status='blocked_inline'``, entity hidden\n * on inline pass \u2192 ``status='pending_llm'``, LLM call scheduled,\n entity visibility flipped to ``pending`` until verdict lands\n * audit_log entry recorded for both outcomes \u2014 admin sees the\n rescan in the detail-page activity timeline\n * audit row recorded\n\nRequires the bundle to still be on disk. Inline-blocked submissions\nwhose bundle was rolled back (no ``entity_id``) cannot be rescanned \u2014\nnothing to scan.",
"operationId": "admin_rescan_store_submission_api_admin_store_submissions__submission_id__rescan_post",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Rescan Store Submission",
"tags": [
"admin"
]
}
},
"/api/admin/store/submissions/{submission_id}/retry": {
"post": {
"description": "Re-queue the LLM review for a submission.\n\nEligible statuses:\n * ``review_error`` \u2014 LLM call failed, admin retrying after the\n underlying issue (rate limit, timeout, transient outage) clears.\n * ``blocked_llm`` \u2014 admin disagrees with the prior verdict; rerun\n from a clean slate (review rules may have shifted since).\n * ``pending_llm`` \u2014 submission was held when the LLM provider had\n no credentials in env (fail-CLOSED matrix: intent True + not\n ready). Admin sets the key and re-fires from here.\n\nOnly valid when the original submission's plugin tree is still on\ndisk \u2014 for inline-blocked rows the bundle was deleted at POST time.",
"operationId": "admin_retry_store_submission_api_admin_store_submissions__submission_id__retry_post",
"parameters": [
{
"in": "path",
"name": "submission_id",
"required": true,
"schema": {
"title": "Submission Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Retry Store Submission",
"tags": [
"admin"
]
}
},
"/api/admin/telemetry/ask": {
"post": {
"description": "Translate a natural-language question to SELECT-only SQL via Anthropic + execute.\n\nReturns the generated SQL even when validation rejects it, so the\nadmin sees what the LLM tried.",
"operationId": "ask_usage_api_admin_telemetry_ask_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Payload",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Ask Usage",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/export": {
"get": {
"description": "Stream usage_events filtered by since/until/user_id/source.\n\nCSV: standard library `csv.writer`, one row per event with all columns.\nJSON: streaming NDJSON (one JSON object per line) \u2014 easier to pipe + tail.\nParquet: DuckDB `COPY (SELECT ...) TO '<tmp>.parquet'` then stream the file.",
"operationId": "export_usage_api_admin_telemetry_export_get",
"parameters": [
{
"in": "query",
"name": "format",
"required": false,
"schema": {
"default": "csv",
"enum": [
"csv",
"json",
"parquet"
],
"title": "Format",
"type": "string"
}
},
{
"description": "ISO date or datetime; events with occurred_at >= since",
"in": "query",
"name": "since",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO date or datetime; events with occurred_at >= since",
"title": "Since"
}
},
{
"description": "ISO date or datetime; events with occurred_at < until",
"in": "query",
"name": "until",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO date or datetime; events with occurred_at < until",
"title": "Until"
}
},
{
"description": "Filter to a single user_id",
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter to a single user_id",
"title": "User Id"
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"curated",
"flea",
"builtin"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Export Usage",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/facets": {
"get": {
"description": "Distinct values present in usage_events for the selected window so the\nUI dropdowns are closed-set instead of free-text guesses.",
"operationId": "usage_facets_api_admin_telemetry_facets_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Usage Facets",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/kpis": {
"get": {
"description": "Four headline numbers, scoped to the same filters as /query.\n\nThe cards on /admin/usage echo these as clickable quick-filters, so the\nserver applies the same WHERE the table will see \u2014 otherwise the cards\nand the table tell different stories at the same time.",
"operationId": "usage_kpis_api_admin_telemetry_kpis_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "username",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Username"
}
},
{
"in": "query",
"name": "tool_name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Name"
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
}
},
{
"in": "query",
"name": "event_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Type"
}
},
{
"in": "query",
"name": "only_errors",
"required": false,
"schema": {
"default": false,
"title": "Only Errors",
"type": "boolean"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Usage Kpis",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/prune": {
"post": {
"description": "Delete usage_events older than USAGE_EVENTS_RETENTION_DAYS.\n\nDefault retention: env var unset or ``0`` \u2192 no pruning (forever).\nDaily rollup tables untouched \u2014 they're tiny and lossy-by-design.",
"operationId": "prune_usage_api_admin_telemetry_prune_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Prune Usage",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/query": {
"get": {
"description": "Filtered + optionally grouped read against usage_events.\n\n`group_by` \u2208 {None, 'day', 'username', 'tool_name', 'source', 'ref_id'}.\nWhen grouped, returns one bucket per row with `invocations`,\n`distinct_users`, `distinct_sessions`, `errors`. When ungrouped, returns\nthe raw event rows.\n\n`sort` syntax: `<column>:<asc|desc>`. For grouped queries the valid\ncolumns are `bucket`, `invocations`, `distinct_users`, `distinct_sessions`,\n`errors`. For ungrouped queries: `occurred_at`. Unknown sort keys fall\nback to a safe default rather than 400 \u2014 UIs evolve faster than this\nendpoint.",
"operationId": "usage_query_api_admin_telemetry_query_get",
"parameters": [
{
"in": "query",
"name": "since_minutes",
"required": false,
"schema": {
"default": 10080,
"maximum": 525600,
"minimum": 1,
"title": "Since Minutes",
"type": "integer"
}
},
{
"in": "query",
"name": "username",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Username"
}
},
{
"in": "query",
"name": "tool_name",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Tool Name"
}
},
{
"in": "query",
"name": "source",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source"
}
},
{
"in": "query",
"name": "event_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event Type"
}
},
{
"in": "query",
"name": "only_errors",
"required": false,
"schema": {
"default": false,
"title": "Only Errors",
"type": "boolean"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "query",
"name": "group_by",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Group By"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"default": "invocations:desc",
"title": "Sort",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 100,
"maximum": 500,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"maximum": 50000,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Usage Query",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/reprocess": {
"post": {
"description": "Force re-extraction of all sessions for the usage processor.\n\nDELETEs:\n - session_processor_state WHERE processor_name='usage' (so the next\n scheduler tick re-scans every JSONL) + processor_name='marketplace_rollup_30d'\n (forces 30d window rebuild on the next tick)\n - usage_events\n - usage_session_summary\n - usage_tool_daily (legacy)\n - usage_marketplace_item_daily\n - usage_marketplace_item_window\n\nVerification processor's state untouched (composite PK isolates each processor).\nAudit-logged with deleted-row counts.",
"operationId": "reprocess_usage_api_admin_telemetry_reprocess_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Reprocess Usage",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/telemetry/summary": {
"get": {
"description": "Compute six summaries:\n- top_tools: list[{tool_name, invocations, source}]\n- top_users: list[{username, tool_calls}]\n- error_rate: list[{tool_name, invocations, errors, rate}]\n- dau_series: list[{day, active_users}] \u2014 30 entries even when window=7d (sparkline likes 30)\n- dau_avg: float\n- slow_actions: list[{action, p50, p95, p99, max_ms, n}]",
"operationId": "usage_summary_api_admin_telemetry_summary_get",
"parameters": [
{
"in": "query",
"name": "window",
"required": false,
"schema": {
"default": "7d",
"enum": [
"7d",
"30d",
"all"
],
"title": "Window",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Usage Summary",
"tags": [
"admin-telemetry"
]
}
},
"/api/admin/users/{user_id}/activity": {
"get": {
"description": "List audit_log rows for a specific user.\n\nResolves user_id to the user record (404 if not found), filters audit_log\non the user_id field, returns paginated rows newest first.",
"operationId": "list_user_activity_api_admin_users__user_id__activity_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List User Activity",
"tags": [
"admin"
]
}
},
"/api/admin/users/{user_id}/effective-access": {
"get": {
"description": "List resources the user effectively has access to, with which group\ngrants each one. ``is_admin`` reflects the real Admin-group check but\nno longer short-circuits the response \u2014 admins get the same explicit\ngrant breakdown as everyone else, so the admin viewing a target user\ncan see precisely what's been granted via which group rather than a\nflat \"Full access\" pill that hides the wiring.\n\nNote: actual authorization at runtime still gives Admin-group members\ngod-mode (see ``app.auth.access.is_user_admin``); this endpoint is a\ndebugging/audit view of the explicit grant graph, not the enforcement\nsurface.",
"operationId": "user_effective_access_api_admin_users__user_id__effective_access_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EffectiveAccessResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "User Effective Access",
"tags": [
"access"
]
}
},
"/api/admin/users/{user_id}/memberships": {
"get": {
"description": "Groups a user belongs to, joined with group metadata for display.\n\nIncludes ``source`` so the UI can distinguish admin-managed memberships\n(deletable from this page) from Google-synced or system-seeded ones\n(read-only \u2014 managed by their own writer).",
"operationId": "list_user_memberships_api_admin_users__user_id__memberships_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/UserMembershipResponse"
},
"title": "Response List User Memberships Api Admin Users User Id Memberships Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List User Memberships",
"tags": [
"access"
]
},
"post": {
"description": "Add a user to a group from the user-centric page.\n\nMirror of POST /api/admin/groups/{id}/members but keyed on the user.\nAlways writes ``source='admin'`` so the row survives Google sync.",
"operationId": "add_user_to_group_api_admin_users__user_id__memberships_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddUserToGroupRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserMembershipResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Add User To Group",
"tags": [
"access"
]
}
},
"/api/admin/users/{user_id}/memberships/{group_id}": {
"delete": {
"description": "Remove a user from a group from the user-centric page.\n\nOnly deletes admin-source rows (Google-sync / system-seed managed\nelsewhere). Last-admin guard: refuse to remove anyone from Admin\nwhen they are the only active admin \u2014 recovery from zero admins\nrequires direct DB access.",
"operationId": "remove_user_from_group_api_admin_users__user_id__memberships__group_id__delete",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "path",
"name": "group_id",
"required": true,
"schema": {
"title": "Group Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Remove User From Group",
"tags": [
"access"
]
}
},
"/api/admin/users/{user_id}/sessions": {
"get": {
"description": "Return a paginated session list for *user_id*.\n\nEach row joins ``usage_session_summary`` (preferred, ``processed=true``)\nwith a filesystem scan of ``${SESSION_DATA_DIR}/<username>/*.jsonl`` so\nthe response surfaces sessions even when the UsageProcessor hasn't run yet\n(``processed=false`` for those rows).\n\n``processed=false`` rows carry only: ``session_file``, ``session_id``\n(extracted from the filename when possible), ``started_at`` (file mtime),\nand zeroed-out counters.",
"operationId": "list_user_sessions_api_admin_users__user_id__sessions_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List User Sessions",
"tags": [
"admin"
]
}
},
"/api/admin/users/{user_id}/sessions/download-all": {
"get": {
"description": "Stream a ZIP of every *.jsonl under the user's session directory.\n\nReturns 404 when the directory doesn't exist.\nReturns 200 + empty ZIP when the directory exists but has no JSONL files.",
"operationId": "download_all_sessions_api_admin_users__user_id__sessions_download_all_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Download All Sessions",
"tags": [
"admin"
]
}
},
"/api/admin/users/{user_id}/sessions/{session_file}/download": {
"get": {
"description": "Stream the raw JSONL for a single session.\n\nPath-traversal is guarded by three layers:\n1. ``safe_name = Path(session_file).name`` \u2014 strips any ``../`` etc.\n2. The name must match ``^[A-Za-z0-9._-]+\\.jsonl$``.\n3. ``path.resolve()`` must still be under the session directory.",
"operationId": "download_session_api_admin_users__user_id__sessions__session_file__download_get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "path",
"name": "session_file",
"required": true,
"schema": {
"title": "Session File",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Download Session",
"tags": [
"admin"
]
}
},
"/api/admin/welcome-template": {
"delete": {
"operationId": "admin_reset_template_api_admin_welcome_template_delete",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Reset Template",
"tags": [
"welcome"
]
},
"get": {
"operationId": "admin_get_template_api_admin_welcome_template_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/app__api__welcome__TemplateGetResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Get Template",
"tags": [
"welcome"
]
},
"put": {
"operationId": "admin_put_template_api_admin_welcome_template_put",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplatePutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Put Template",
"tags": [
"welcome"
]
}
},
"/api/admin/welcome-template/preview": {
"post": {
"description": "Render arbitrary template content against the live context for the\ncalling admin, without persisting. Used by the /admin/agent-prompt editor's\nPreview button so admins can see their edits before saving.",
"operationId": "admin_preview_template_api_admin_welcome_template_preview_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplatePreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BannerResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Preview Template",
"tags": [
"welcome"
]
}
},
"/api/admin/workspace-prompt-template": {
"delete": {
"operationId": "admin_reset_workspace_template_api_admin_workspace_prompt_template_delete",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Reset Workspace Template",
"tags": [
"claude_md"
]
},
"get": {
"operationId": "admin_get_workspace_template_api_admin_workspace_prompt_template_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/app__api__claude_md__TemplateGetResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Get Workspace Template",
"tags": [
"claude_md"
]
},
"put": {
"description": "Save an admin override for the analyst CLAUDE.md template.\n\nTwo-pass Jinja2 validation (autoescape=False, StrictUndefined):\n- Pass 1: render with an authenticated user stub \u2014 catches undefined\n placeholders and syntax errors.\n- Pass 2: render with a minimal anon-style user stub \u2014 catches templates\n that hard-depend on admin-only context fields.",
"operationId": "admin_put_workspace_template_api_admin_workspace_prompt_template_put",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplatePutRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Put Workspace Template",
"tags": [
"claude_md"
]
}
},
"/api/admin/workspace-prompt-template/preview": {
"post": {
"description": "Render arbitrary template content against the live RBAC context for the\ncalling admin, without persisting. Used by the /admin/workspace-prompt editor's\nPreview button so admins can see their edits before saving.",
"operationId": "admin_preview_workspace_template_api_admin_workspace_prompt_template_preview_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TemplatePreviewRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaudeMdResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Preview Workspace Template",
"tags": [
"claude_md"
]
}
},
"/api/catalog/metrics/{metric_path}": {
"get": {
"deprecated": true,
"description": "Deprecated: use GET /api/metrics/{metric_id} instead.",
"operationId": "get_metric_api_catalog_metrics__metric_path__get",
"parameters": [
{
"in": "path",
"name": "metric_path",
"required": true,
"schema": {
"title": "Metric Path",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Metric",
"tags": [
"catalog"
]
}
},
"/api/catalog/profile/{table_name}": {
"get": {
"description": "Get profiler data for a specific table.",
"operationId": "get_table_profile_api_catalog_profile__table_name__get",
"parameters": [
{
"in": "path",
"name": "table_name",
"required": true,
"schema": {
"title": "Table Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Table Profile",
"tags": [
"catalog"
]
}
},
"/api/catalog/profile/{table_name}/refresh": {
"post": {
"description": "Re-generate profile for a table on demand.",
"operationId": "refresh_profile_api_catalog_profile__table_name__refresh_post",
"parameters": [
{
"in": "path",
"name": "table_name",
"required": true,
"schema": {
"title": "Table Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Refresh Profile",
"tags": [
"catalog"
]
}
},
"/api/catalog/tables": {
"get": {
"description": "List all available tables from table_registry.",
"operationId": "list_catalog_tables_api_catalog_tables_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogTablesResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Catalog Tables",
"tags": [
"catalog"
]
}
},
"/api/data/{table_id}/check-access": {
"get": {
"description": "Lightweight RBAC probe used by Caddy's ``forward_auth`` directive\nto gate file_server-served parquet downloads without involving the\napp's request workers in the bulk byte transfer.\n\nReturns HTTP 204 No Content when the caller has read access to\n``table_id``; HTTP 403 (via ``can_access_table`` returning False)\notherwise. Caddy treats 2xx as authorized and forwards the request\nto its own ``file_server`` block; non-2xx is returned to the client\nverbatim.\n\nWhy a separate endpoint and not just ``HEAD /download``: ``HEAD`` on\nthe FileResponse-based ``download`` handler still opens the file and\nruns stat() to populate Content-Length / ETag. ``forward_auth`` calls\nthis endpoint on every request, so the per-call cost matters; a pure\nRBAC check is ~1 ms while a HEAD path involves filesystem walks\n(``rglob`` for the parquet across source subdirs).",
"operationId": "check_access_api_data__table_id__check_access_get",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Check Access",
"tags": [
"data"
]
}
},
"/api/data/{table_id}/download": {
"get": {
"description": "Stream a parquet file for download. Supports ETag for caching.\n\nOn Caddy-fronted deployments the matching Caddyfile rule intercepts\n``GET /api/data/{table_id}/download``, calls ``check-access`` via\n``forward_auth``, and serves the parquet directly via ``file_server``\n\u2014 bypassing this handler entirely. This handler stays as the\ncanonical fallback for non-Caddy deployments (dev `docker compose\nup`, alternative reverse proxies, direct :8000 access) where the\nbulk transfer goes through uvicorn.",
"operationId": "download_table_api_data__table_id__download_get",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Download Table",
"tags": [
"data"
]
}
},
"/api/debug/throw": {
"get": {
"description": "Deliberate-crash route for verifying observability wiring.\n\nGated by ``DEBUG=1`` \u2014 returns 404 in production. Always raises after\nthe auth dependency resolves, so ``request.state.user`` is populated\nby the time the unhandled-exception handler captures the event. Use\nto confirm that PostHog receives the exception with full user context\n(``distinct_id``, ``user_id``, ``user_email``) and not just\n``request_id``.\n\nOptional query params let you pick the exception type and message:\n /api/debug/throw?kind=ValueError&msg=hello",
"operationId": "debug_throw_api_debug_throw_get",
"parameters": [
{
"in": "query",
"name": "kind",
"required": false,
"schema": {
"default": "RuntimeError",
"title": "Kind",
"type": "string"
}
},
{
"in": "query",
"name": "msg",
"required": false,
"schema": {
"default": "intentional debug throw",
"title": "Msg",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Debug Throw",
"tags": [
"health"
]
}
},
"/api/health": {
"get": {
"description": "Minimal health check for load balancers / compose healthcheck. No auth required.",
"operationId": "health_check_api_health_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Health Check",
"tags": [
"health"
]
}
},
"/api/health/detailed": {
"get": {
"description": "Structured health check with deployment metadata. Requires authentication.",
"operationId": "health_check_detailed_api_health_detailed_get",
"parameters": [
{
"description": "Comma-separated list of optional checks to include. Recognised values: `schema` (DB schema version against the expected migration). The default response omits these because they're rarely actionable on a healthy instance and add noise to `agnes diagnose` output (issue #204). Pass `?include=schema` to get the legacy behavior.",
"in": "query",
"name": "include",
"required": false,
"schema": {
"default": "",
"description": "Comma-separated list of optional checks to include. Recognised values: `schema` (DB schema version against the expected migration). The default response omits these because they're rarely actionable on a healthy instance and add noise to `agnes diagnose` output (issue #204). Pass `?include=schema` to get the legacy behavior.",
"title": "Include",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Health Check Detailed",
"tags": [
"health"
]
}
},
"/api/initial-workspace": {
"get": {
"description": "Status probe consumed by ``agnes init``. Always 200.\n\nReturns ``configured: false`` when no template is registered (CLI then\nfalls through to the existing default flow). Returns ``configured:\ntrue, synced: false`` when registered but never synced (or last sync\nfailed); CLI shows a typed error pointing at /admin/server-config.\nReturns full metadata + manifest when configured + synced.",
"operationId": "analyst_status_api_initial_workspace_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AnalystInitialWorkspaceResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Analyst Status",
"tags": [
"initial_workspace"
]
}
},
"/api/initial-workspace.zip": {
"get": {
"description": "Return the zip of the cloned template tree (sans ``.git/``).\n\nWrites a server-side ``initial_workspace.fetch_started`` audit row so\nwe have an authoritative event the analyst's PAT-holder cannot spoof\n(the matching ``initial_workspace.applied`` event from\n``POST /applied`` is best-effort).\n\n404 when not configured (the CLI status probe should have caught\nthis; defense in depth). 503 when configured but never synced \u2014 the\nCLI then surfaces a typed error pointing at \"Sync now\".",
"operationId": "analyst_zip_api_initial_workspace_zip_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Analyst Zip",
"tags": [
"initial_workspace"
]
}
},
"/api/initial-workspace/applied": {
"post": {
"description": "Best-effort audit event from ``agnes init`` confirming the\nanalyst's workspace has been extracted + sentinel written.\n\nThe authoritative anchor is the server-side\n``initial_workspace.fetch_started`` event written by ``GET .../zip`` \u2014\na fetch_started without a matching applied = the analyst downloaded\nbut never confirmed extraction (useful signal for operators).",
"operationId": "analyst_applied_api_initial_workspace_applied_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppliedRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Analyst Applied",
"tags": [
"initial_workspace"
]
}
},
"/api/marketplace/categories": {
"get": {
"description": "Per-tab category list with non-zero counts.\n\nSource of categories: union of ``STORE_CATEGORIES`` and any non-empty\n``marketplace_plugins.category`` values in the caller's RBAC scope.\nCategories with zero matching items are omitted (the frontend hides\nthem this way).",
"operationId": "list_categories_api_marketplace_categories_get",
"parameters": [
{
"in": "query",
"name": "tab",
"required": false,
"schema": {
"default": "curated",
"enum": [
"curated",
"flea",
"my"
],
"title": "Tab",
"type": "string"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"skill",
"agent",
"plugin"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CategoriesResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Categories",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}": {
"get": {
"description": "Return the curated plugin detail + inner skill/agent/command/hook/mcp list.\n\nThe 403 guard fires before this body runs (via ``require_resource_access``).\nA second ``get_current_user`` dependency is included so we still have the\ncaller's user dict for the ``installed`` flag.",
"operationId": "curated_detail_api_marketplace_curated__marketplace_id___plugin_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PluginDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/agent/{agent_name}": {
"get": {
"operationId": "curated_agent_detail_api_marketplace_curated__marketplace_id___plugin_name__agent__agent_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "agent_name",
"required": true,
"schema": {
"title": "Agent Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InnerDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Agent Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/asset/{path}": {
"get": {
"description": "Serve an internal image asset from the cloned marketplace working tree.\n\nPaths are repo-root-relative \u2014 ``{path}`` may be e.g.\n``.agnes/cover.png`` or ``plugins/foo/icon.png``.\n\n**Auth model: login-only, no per-plugin RBAC.** Cover photos are\ncurator-designed marketing visuals \u2014 they exist specifically to be seen\nand carry no PII / source / secrets. The previous\n``require_resource_access`` check serialized every image request through\na DuckDB join under ``_system_db_lock``, making the /marketplace grid\n(12-20 cover photos per render) pay N round-trips of auth+RBAC cost in\nsequence. Login (``get_current_user``) still required \u2192 no\nunauthenticated public access. See CHANGELOG entry under \"Security\" for\nthe threat-model rationale.\n\n**Image-only by contract.** The endpoint is the source of cover photos\nreferenced from ``marketplace-metadata.json`` and from inner skill / agent\ncards. A curator who could land an arbitrary file in the cloned repo\n(HTML, JS, SVG with inline ``<script>``) would otherwise have a\nsame-origin XSS via this endpoint, since the response shares the\ncookie scope with ``/admin`` and ``/api/me/*``. Two layered checks:\n\n1. Extension must be in :data:`src.marketplace_asset_validation.IMAGE_EXTENSIONS`\n (``.png``/``.jpg``/``.jpeg``/``.webp``); anything else \u2192 415.\n2. ``Content-Type`` is pinned from the extension table (not stdlib\n mimetypes), so the response is never served as ``text/html`` even\n if mimetypes were misconfigured.\n\nMagic-bytes body validation that previously ran per request was dropped\nafter the perf audit found it re-read the file just to discard the\nbytes (``FileResponse`` reads it again to stream). The repo is fetched\nvia ``git pull`` from a trusted upstream the operator registered in\n``marketplace_registry`` \u2014 accepting curator content at sync time is\nthe layer where adversarial-payload detection belongs, not at every\nGET. Extension + Content-Type pinning + path-traversal guard remain.\n\nSVG is intentionally not in the allowlist \u2014 ``<script>`` inside SVG\nexecutes in the browser. ``X-Content-Type-Options: nosniff`` plus a\nstrict CSP harden the response further.\n\nInline rendering (no ``Content-Disposition``) \u2014 covers display in\n``<img>``, not as a download.",
"operationId": "curated_asset_api_marketplace_curated__marketplace_id___plugin_name__asset__path__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "path",
"required": true,
"schema": {
"title": "Path",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Asset",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/doc/{path}": {
"get": {
"description": "Serve an internal doc path from the cloned marketplace working tree.\n\nSame path-traversal guard as ``/asset/``. Adds an allowlist check \u2014 the\ndoc endpoint refuses to serve a file whose extension isn't in the\ndocumented PDF / Markdown / plain text set (HTTP 415). Defense-in-depth\neven though the marketplace-metadata parser already rejects out-of-allowlist\nextensions during the doc_link parse \u2014 a curator who edits the working\ntree directly (or whose JSON survived parsing because of a generic\nextension match elsewhere) shouldn't be able to land a .docx through\na re-served doc URL.\n\nForce-download via Content-Disposition: attachment \u2014 clicking a doc\nlink in the UI saves the file to disk rather than opening it in a tab.",
"operationId": "curated_doc_api_marketplace_curated__marketplace_id___plugin_name__doc__path__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "path",
"required": true,
"schema": {
"title": "Path",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Doc",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/install": {
"delete": {
"operationId": "curated_uninstall_api_marketplace_curated__marketplace_id___plugin_name__install_delete",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallActionResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Uninstall",
"tags": [
"marketplace"
]
},
"post": {
"description": "Subscribe the caller to a curated plugin (Model B opt-in).\n\nIdempotent \u2014 repeated calls are no-ops. The plugin must exist in\n``marketplace_plugins``; otherwise 404. The RBAC guard already ensured\nthe caller is allowed to install.",
"operationId": "curated_install_api_marketplace_curated__marketplace_id___plugin_name__install_post",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallActionResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Install",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/mirrored/{key}": {
"get": {
"description": "Serve a mirrored external asset from the marketplace cache.\n\n``key`` is the ``local`` relpath stored in the cache manifest minus the\nleading ``<plugin>/`` prefix \u2014 the mirror writes files at\n``${DATA_DIR}/marketplace-cache/<slug>/<plugin>/<rest>``, and this\nendpoint expects ``{plugin}/{rest}`` so the same path-resolution check\ncatches escapes whether the caller provided ``cover.png`` or\n``docs/abc-setup.pdf``.\n\nDoc-shaped paths (key starting with ``docs/``) get the same force-download\ntreatment as the internal /doc/ endpoint. Cover photos under the cache\nroot render inline so the <img> tag works.\n\n**Auth model: login-only for cover photos**, same rationale as\n``curated_asset`` above. The doc branch below is still gated by login\nonly at this point \u2014 RBAC was dropped here too because the mirrored\ncache is just the cover-photo serving complement, not user-facing\ndocument distribution. Tighter doc gating lives on the separate\n``curated_doc`` endpoint which retains ``require_resource_access``.",
"operationId": "curated_mirrored_api_marketplace_curated__marketplace_id___plugin_name__mirrored__key__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "key",
"required": true,
"schema": {
"title": "Key",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Mirrored",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/curated/{marketplace_id}/{plugin_name}/skill/{skill_name}": {
"get": {
"operationId": "curated_skill_detail_api_marketplace_curated__marketplace_id___plugin_name__skill__skill_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "skill_name",
"required": true,
"schema": {
"title": "Skill Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InnerDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Curated Skill Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/flea/{entity_id}/agent/{agent_name}": {
"get": {
"description": "Inner agent detail for an agent nested inside a flea plugin entity.\n\nMirror of ``curated_agent_detail``. Agents are flat single-file .md\nso ``bundle_size`` is the file size and ``files`` is a single entry.",
"operationId": "flea_agent_detail_api_marketplace_flea__entity_id__agent__agent_name__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "agent_name",
"required": true,
"schema": {
"title": "Agent Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InnerDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Flea Agent Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/flea/{entity_id}/detail": {
"get": {
"description": "Same shape as curated detail, sourced from a Store entity.\n\nFlea entities live at ``${DATA_DIR}/store/<entity_id>/plugin/`` \u2014\ncanonical Claude Code plugin tree, so the same parsers apply.",
"operationId": "flea_detail_api_marketplace_flea__entity_id__detail_get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PluginDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Flea Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/flea/{entity_id}/skill/{skill_name}": {
"get": {
"description": "Inner skill detail for a skill nested inside a flea plugin entity.\n\nMirror of ``curated_skill_detail`` for the flea bundle root layout\n(``${DATA_DIR}/store/<entity_id>/plugin/``). Visibility gate matches\nthe standalone flea_detail handler \u2014 owner / admin see quarantined\nentities, everyone else gets 404.",
"operationId": "flea_skill_detail_api_marketplace_flea__entity_id__skill__skill_name__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "skill_name",
"required": true,
"schema": {
"title": "Skill Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InnerDetailResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Flea Skill Detail",
"tags": [
"marketplace"
]
}
},
"/api/marketplace/items": {
"get": {
"description": "Paginated, RBAC-scoped item list for the ``/marketplace`` browse page.\n\nPer-tab dispatch:\n\n* ``curated`` \u2192 ``MarketplacePluginsRepository.list_with_filters`` scoped to\n the caller's ``user_group_members``. Results are tagged with the\n caller's subscription state.\n* ``flea`` \u2192 ``StoreEntitiesRepository.list`` (community Store).\n* ``my`` \u2192 direct read from ``user_curated_subscriptions`` (filtered\n against the caller's RBAC-allowed plugins) \u222a ``user_store_installs``\n (all flea types \u2014 skill / agent / plugin \u2014 surface as individual\n cards). We deliberately don't reuse ``resolve_user_marketplace``\n here: that resolver bundles flea skills/agents into a single\n synthetic ``store-bundle`` entry useful for the served Claude Code\n marketplace ZIP/git endpoints but wrong for /marketplace browsing,\n where each item should appear as its own card. Mirrors the\n ``/api/my-stack`` reading pattern.\n\n``sort`` controls ordering after stats are joined:\n * ``recent`` \u2014 existing DB order (default, backward-compatible).\n * ``most_used`` \u2014 DESC by invocations_30d, ties by install_count then name.\n * ``trending`` \u2014 DESC by trend_pct; items with no trend data are excluded.",
"operationId": "list_items_api_marketplace_items_get",
"parameters": [
{
"in": "query",
"name": "tab",
"required": false,
"schema": {
"default": "curated",
"enum": [
"curated",
"flea",
"my"
],
"title": "Tab",
"type": "string"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"skill",
"agent",
"plugin"
],
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"default": "recent",
"enum": [
"recent",
"most_used",
"most_adopted",
"trending"
],
"title": "Sort",
"type": "string"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"minimum": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 24,
"maximum": 100,
"minimum": 1,
"title": "Page Size",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ItemListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Items",
"tags": [
"marketplace"
]
}
},
"/api/marketplaces": {
"get": {
"operationId": "list_marketplaces_api_marketplaces_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/MarketplaceResponse"
},
"title": "Response List Marketplaces Api Marketplaces Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Marketplaces",
"tags": [
"marketplaces"
]
},
"post": {
"operationId": "create_marketplace_api_marketplaces_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMarketplaceRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MarketplaceResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Marketplace",
"tags": [
"marketplaces"
]
}
},
"/api/marketplaces/sync-all": {
"post": {
"description": "Sync every registered marketplace.\n\nWired up so the scheduler service can drive the nightly refresh over\nHTTP. The previous implementation called ``src.marketplace.sync_marketplaces``\nin-process from the scheduler container, which conflicted with the app's\nlong-lived ``system.duckdb`` handle (DuckDB allows only one writer per\nfile across processes). Routing through the app inherits the existing\nconnection without contention.\n\nDeclared ``def`` (not ``async def``) so FastAPI runs it in a thread\npool \u2014 :func:`sync_marketplaces` does blocking I/O (subprocess git\nclones with ``GIT_TIMEOUT_SEC=300`` per repo, DuckDB writes, a\nprocess-wide threading.Lock) and would freeze the event loop for the\nduration of a bulk sync if it ran on the asyncio thread. Health\nchecks, login redirects, and every other concurrent request keep\nserving while the bulk sync churns through the registry.\n\nOne audit row per call summarises the outcome \u2014 per-marketplace details\nlive in ``marketplace_registry`` and the per-call result payload below.",
"operationId": "trigger_sync_all_api_marketplaces_sync_all_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Trigger Sync All",
"tags": [
"marketplaces"
]
}
},
"/api/marketplaces/{marketplace_id}": {
"delete": {
"operationId": "delete_marketplace_api_marketplaces__marketplace_id__delete",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "query",
"name": "purge",
"required": false,
"schema": {
"default": false,
"title": "Purge",
"type": "boolean"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Marketplace",
"tags": [
"marketplaces"
]
},
"patch": {
"operationId": "update_marketplace_api_marketplaces__marketplace_id__patch",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMarketplaceRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MarketplaceResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Marketplace",
"tags": [
"marketplaces"
]
}
},
"/api/marketplaces/{marketplace_id}/plugins": {
"get": {
"description": "Return the cached plugin list for a marketplace.\n\nRows come from `marketplace_plugins`, which is refreshed from\n`.claude-plugin/marketplace.json` on every successful sync. An\nunsynced marketplace will return an empty list.",
"operationId": "list_plugins_api_marketplaces__marketplace_id__plugins_get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/PluginResponse"
},
"title": "Response List Plugins Api Marketplaces Marketplace Id Plugins Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Plugins",
"tags": [
"marketplaces"
]
}
},
"/api/marketplaces/{marketplace_id}/plugins/{plugin_name}/system": {
"delete": {
"description": "Flip ``is_system`` to FALSE. Materialized grants/subscriptions\nsurvive \u2014 admin curates cleanup via the standard /admin/access UI\n(which immediately unlocks the checkboxes for this plugin) and\nusers can unsubscribe normally on /marketplace?tab=my.",
"operationId": "unmark_plugin_system_api_marketplaces__marketplace_id__plugins__plugin_name__system_delete",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SystemFlagResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Unmark Plugin System",
"tags": [
"marketplaces"
]
},
"post": {
"description": "Mark a plugin as system (mandatory for every user).\n\nIdempotent \u2014 re-running a mark on an already-system plugin still\nruns the fanout (cheap; ON CONFLICT DO NOTHING) so any user/group\nthat slipped past the creation hooks gets caught up.",
"operationId": "mark_plugin_system_api_marketplaces__marketplace_id__plugins__plugin_name__system_post",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SystemFlagResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Mark Plugin System",
"tags": [
"marketplaces"
]
}
},
"/api/marketplaces/{marketplace_id}/sync": {
"post": {
"operationId": "trigger_sync_api_marketplaces__marketplace_id__sync_post",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Trigger Sync",
"tags": [
"marketplaces"
]
}
},
"/api/me/effective-access": {
"get": {
"description": "Same payload as /api/admin/users/{id}/effective-access but scoped to\nthe calling user. Drives the /me/profile page's read-only access summary \u2014\nso non-admin callers can self-audit without elevation. Admins get the\nsame explicit grant breakdown as everyone else (no short-circuit) so\nthe profile page audits the actual grant graph; runtime authorization\nstill gives Admin god-mode regardless of this list.",
"operationId": "my_effective_access_api_me_effective_access_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EffectiveAccessResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "My Effective Access",
"tags": [
"me"
]
}
},
"/api/me/home-stats": {
"get": {
"description": "Return the five counters rendered in the /home status frame for\nthe calling user, over a 24-hour or 7-day window.\n\nSingle round-trip: one DuckDB query joins ``users``,\n``usage_session_summary``, and ``usage_events`` so the homepage\nrenders without N+1. Missing rows (new user, no telemetry yet)\nsurface as zeros / null rather than 404 \u2014 the frame still renders\ncleanly for first-day analysts.",
"operationId": "get_home_stats_api_me_home_stats_get",
"parameters": [
{
"in": "query",
"name": "window",
"required": false,
"schema": {
"default": "24h",
"title": "Window",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Home Stats",
"tags": [
"me"
]
}
},
"/api/me/onboarded": {
"post": {
"operationId": "post_onboarded_api_me_onboarded_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OnboardedRequest",
"default": {
"onboarded": true,
"source": "agnes_init"
}
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Post Onboarded",
"tags": [
"me"
]
}
},
"/api/me/stats/queries": {
"get": {
"description": "Audit-log rows where ``action LIKE 'query.%'`` for the caller.\n\nCovers query.local (DuckDB on parquet), query.hybrid (BQ + local\njoin), query.remote (BQ direct), and query.internal (admin\ninternal queries that get attributed to the actor). Cursor\npagination on (timestamp, id) so streams under concurrent\nwrites don't double-render rows.",
"operationId": "list_self_queries_api_me_stats_queries_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor_ts",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Ts"
}
},
{
"in": "query",
"name": "cursor_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Id"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Self Queries Api Me Stats Queries Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Self Queries",
"tags": [
"me"
]
}
},
"/api/me/stats/sessions": {
"get": {
"description": "Paginated session list for the calling user.\n\nJoins ``usage_session_summary`` (processed=true) with a filesystem\nscan of un-processed JSONL so a session appears immediately even\nbefore the UsageProcessor runs. Additionally enriches each row\nwith verification-pipeline status (from ``session_processor_state``)\nand a ``download_url`` when the uploaded JSONL exists in\n``${DATA_DIR}/user_sessions/<user_id>/``.",
"operationId": "list_self_sessions_api_me_stats_sessions_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Self Sessions Api Me Stats Sessions Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Self Sessions",
"tags": [
"me"
]
}
},
"/api/me/stats/sync": {
"get": {
"description": "Audit-log rows where action is ``sync.*`` or ``manifest.*``\nfor the caller, plus ``users.last_pull_at`` for the header card.\n\nTwo action prefixes are merged with a UNION-ish IN filter via\n``AuditRepository.query(action_in=[...])`` \u2014 but the repo helper\ndoesn't take both prefix and IN, so we call twice and merge.\nCheaper alternative is two SELECTs in the repo; for now we fetch\ntwo pages and interleave because cursor merging across two\nindependent streams is fiddly without a unified ORDER. To keep\nthe code obvious, we use ``query_actions(...)`` and accept that\nthe cursor is single-stream (start over to page back; first page\nis what matters for the dashboard).",
"operationId": "list_self_sync_activity_api_me_stats_sync_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 50,
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "cursor_ts",
"required": false,
"schema": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Ts"
}
},
{
"in": "query",
"name": "cursor_id",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Cursor Id"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response List Self Sync Activity Api Me Stats Sync Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Self Sync Activity",
"tags": [
"me"
]
}
},
"/api/me/stats/tokens": {
"get": {
"description": "Token breakdown for the Tokens tab.\n\nReturns a daily series (last *days* days), by-model breakdown\n(lifetime), top-10 biggest sessions (by total tokens, lifetime),\nand the lifetime grand total. Single round-trip via three\nsub-queries \u2014 each scans the same per-user partition of\n``usage_session_summary`` which the\n``idx_usage_session_user`` index supports.",
"operationId": "get_tokens_api_me_stats_tokens_get",
"parameters": [
{
"in": "query",
"name": "days",
"required": false,
"schema": {
"default": 30,
"maximum": 365,
"minimum": 1,
"title": "Days",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Get Tokens Api Me Stats Tokens Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Tokens",
"tags": [
"me"
]
}
},
"/api/memory": {
"get": {
"description": "List knowledge items with filtering, pagination, search.\n\n``upvoted_by_me=true`` narrows to items the caller upvoted (powers the\n\"My Upvotes\" filter on /corporate-memory \u2014 replaces the old dead\n\"My Rules\" category sentinel).",
"operationId": "list_knowledge_api_memory_get",
"parameters": [
{
"in": "query",
"name": "status_filter",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status Filter"
}
},
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "query",
"name": "domain",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Domain"
}
},
{
"in": "query",
"name": "source_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
}
},
{
"in": "query",
"name": "search",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Search"
}
},
{
"in": "query",
"name": "exclude_personal",
"required": false,
"schema": {
"default": true,
"title": "Exclude Personal",
"type": "boolean"
}
},
{
"in": "query",
"name": "upvoted_by_me",
"required": false,
"schema": {
"default": false,
"title": "Upvoted By Me",
"type": "boolean"
}
},
{
"in": "query",
"name": "hide_dismissed",
"required": false,
"schema": {
"default": false,
"title": "Hide Dismissed",
"type": "boolean"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 50,
"title": "Per Page",
"type": "integer"
}
},
{
"in": "query",
"name": "sort",
"required": false,
"schema": {
"default": "updated_at",
"title": "Sort",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Knowledge",
"tags": [
"memory"
]
},
"post": {
"operationId": "create_knowledge_api_memory_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKnowledgeRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Knowledge",
"tags": [
"memory"
]
}
},
"/api/memory/admin/approve": {
"post": {
"operationId": "admin_approve_api_memory_admin_approve_post",
"parameters": [
{
"in": "query",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Approve",
"tags": [
"memory"
]
}
},
"/api/memory/admin/audit": {
"get": {
"description": "Get governance audit log.\n\nFilters ``corporate_memory.<action>`` rows AND legacy ``km_<action>``\nrows. The dual prefix is here because rows already in the audit log keep\nthe legacy ``km_*`` action name (no migration of historical audit rows \u2014\nthey are write-once); new rows use the ``corporate_memory.*`` namespace.\nSee issue #62 decision E.",
"operationId": "admin_audit_api_memory_admin_audit_get",
"parameters": [
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 50,
"title": "Per Page",
"type": "integer"
}
},
{
"in": "query",
"name": "action",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Action"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Audit",
"tags": [
"memory"
]
}
},
"/api/memory/admin/batch": {
"post": {
"description": "Batch governance action on multiple items.",
"operationId": "admin_batch_api_memory_admin_batch_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchActionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Batch",
"tags": [
"memory"
]
}
},
"/api/memory/admin/bulk-update": {
"post": {
"description": "Apply ``updates`` to every id in ``item_ids``. Per-id audit rows.\n\nReturns a per-id status map plus rolled-up convenience lists (200 even on\npartial failure \u2014 the body distinguishes successes from misses).",
"operationId": "admin_bulk_update_api_memory_admin_bulk_update_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpdateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Bulk Update",
"tags": [
"memory"
]
}
},
"/api/memory/admin/contradictions": {
"get": {
"description": "List knowledge contradictions for admin review.\n\nBy default (`exclude_personal=True`), personal items are replaced with\n{id, hidden: true} so the contradiction record is still visible for\ngovernance but personal content is not exposed. Pass exclude_personal=false\nto opt in to full content (KM_ADMIN only \u2014 see ADR Decision 1).",
"operationId": "admin_contradictions_api_memory_admin_contradictions_get",
"parameters": [
{
"in": "query",
"name": "resolved",
"required": false,
"schema": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Resolved"
}
},
{
"in": "query",
"name": "exclude_personal",
"required": false,
"schema": {
"default": true,
"title": "Exclude Personal",
"type": "boolean"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Contradictions",
"tags": [
"memory"
]
},
"post": {
"description": "Admin endpoint for manually recording a contradiction between two knowledge items.",
"operationId": "admin_create_contradiction_api_memory_admin_contradictions_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateContradictionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Create Contradiction",
"tags": [
"memory"
]
}
},
"/api/memory/admin/contradictions/{contradiction_id}/resolve": {
"post": {
"description": "Resolve a knowledge contradiction.",
"operationId": "admin_resolve_contradiction_api_memory_admin_contradictions__contradiction_id__resolve_post",
"parameters": [
{
"in": "path",
"name": "contradiction_id",
"required": true,
"schema": {
"title": "Contradiction Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveContradictionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Resolve Contradiction",
"tags": [
"memory"
]
}
},
"/api/memory/admin/duplicate-candidates": {
"get": {
"description": "List duplicate-candidate relations for admin review.\n\nPass ``resolved=true`` or ``resolved=false`` to filter; omit both to fetch\nevery state (the original UI default). The web UI keeps surfacing the\nactionable backlog by passing ``resolved=false`` explicitly.\n\nWith ``exclude_personal=true`` (default) personal items in the pair are\nreplaced with ``{id, hidden: true}`` \u2014 the relation row is still visible\nso admins can resolve it, but content stays inside the personal-item\nprivacy boundary (ADR Decision 1 precedent).",
"operationId": "admin_duplicate_candidates_api_memory_admin_duplicate_candidates_get",
"parameters": [
{
"in": "query",
"name": "resolved",
"required": false,
"schema": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Resolved"
}
},
{
"in": "query",
"name": "exclude_personal",
"required": false,
"schema": {
"default": true,
"title": "Exclude Personal",
"type": "boolean"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 100,
"title": "Limit",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Duplicate Candidates",
"tags": [
"memory"
]
}
},
"/api/memory/admin/duplicate-candidates/resolve": {
"post": {
"description": "Resolve a duplicate-candidate relation.\n\nAdmin chooses: ``duplicate`` (acknowledge), ``different`` (false\npositive), or ``dismissed`` (don't surface again, but no judgment).\nIdempotent re-resolve is rejected with 400 \u2014 the audit trail wants one\ndecision per pair.",
"operationId": "admin_resolve_duplicate_candidate_api_memory_admin_duplicate_candidates_resolve_post",
"parameters": [
{
"in": "query",
"name": "item_a_id",
"required": true,
"schema": {
"title": "Item A Id",
"type": "string"
}
},
{
"in": "query",
"name": "item_b_id",
"required": true,
"schema": {
"title": "Item B Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveDuplicateRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Resolve Duplicate Candidate",
"tags": [
"memory"
]
}
},
"/api/memory/admin/edit": {
"post": {
"operationId": "admin_edit_api_memory_admin_edit_post",
"parameters": [
{
"in": "query",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EditRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Edit",
"tags": [
"memory"
]
}
},
"/api/memory/admin/mandate": {
"post": {
"operationId": "admin_mandate_api_memory_admin_mandate_post",
"parameters": [
{
"in": "query",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminActionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Mandate",
"tags": [
"memory"
]
}
},
"/api/memory/admin/pending": {
"get": {
"description": "Get pending items queue for admin review.",
"operationId": "admin_pending_api_memory_admin_pending_get",
"parameters": [
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 50,
"title": "Per Page",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Pending",
"tags": [
"memory"
]
}
},
"/api/memory/admin/reject": {
"post": {
"operationId": "admin_reject_api_memory_admin_reject_post",
"parameters": [
{
"in": "query",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminActionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Reject",
"tags": [
"memory"
]
}
},
"/api/memory/admin/revoke": {
"post": {
"operationId": "admin_revoke_api_memory_admin_revoke_post",
"parameters": [
{
"in": "query",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminActionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Revoke",
"tags": [
"memory"
]
}
},
"/api/memory/admin/{item_id}": {
"patch": {
"description": "Partial update \u2014 accepts category/domain/tags/audience/title/content.\n\nReplaces the narrow ``POST /api/memory/admin/edit`` (kept one release as\na thin alias). Audit row tagged ``corporate_memory.update_item`` records\nwhich fields changed (not the full diff \u2014 keep audit rows compact).",
"operationId": "admin_patch_item_api_memory_admin__item_id__patch",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchItemRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Patch Item",
"tags": [
"memory"
]
}
},
"/api/memory/bundle": {
"get": {
"description": "Token-budgeted bundle of knowledge items for AI agent injection.\n\nMandatory items are always included regardless of the token budget.\nApproved items are confidence\u00d7recency-ranked and included until the budget\nis exhausted. Audience-filtered by the caller's group memberships (admins\nsee everything).",
"operationId": "get_bundle_api_memory_bundle_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Bundle",
"tags": [
"memory"
]
}
},
"/api/memory/my-contributions": {
"get": {
"description": "Get knowledge items contributed by the current user.",
"operationId": "get_my_contributions_api_memory_my_contributions_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get My Contributions",
"tags": [
"memory"
]
}
},
"/api/memory/my-votes": {
"get": {
"description": "Get current user's votes on all items.",
"operationId": "get_my_votes_api_memory_my_votes_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get My Votes",
"tags": [
"memory"
]
}
},
"/api/memory/stats": {
"get": {
"description": "Get corporate memory statistics.\n\nAggregations exclude personal items for non-privileged callers \u2014 otherwise\n`total` and the `by_*` counts would change in observable ways when a\ncolleague flags or unflags a personal item, leaking existence info per\nADR Decision 1.\n\nUses SQL aggregation rather than ``repo.list_items()`` to keep the\nendpoint cheap on large knowledge bases (the loader path materializes\nevery row + parses JSON tags/contributors per row, which blocks the\nevent loop on N>1k items). Audience filter mirrors what list_items\napplies: ``audience IS NULL OR audience = 'all'`` plus, for non-admins,\nmembership in any of the caller's group-prefixed audiences.",
"operationId": "get_stats_api_memory_stats_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Stats",
"tags": [
"memory"
]
}
},
"/api/memory/tree": {
"get": {
"description": "Server-side grouping for the Browse / Group-by tree (issue #62).\n\nReturns ``{groups: [{key, label, count, items: [...]}]}`` already\nRBAC-filtered + chip-filtered. The same ``_effective_groups`` and\n``_can_view_item`` helpers used by ``GET /api/memory`` apply, so a\nnon-admin caller never sees personal items belonging to others, and\naudience-restricted items only surface for members of the audience\ngroup.\n\nOn the ``tag`` axis a single item appears once per tag it holds \u2014 that\nis the intended \"overlapping bucket\" affordance. Every other axis puts\neach item in its single canonical bucket.",
"operationId": "get_tree_api_memory_tree_get",
"parameters": [
{
"in": "query",
"name": "axis",
"required": false,
"schema": {
"default": "domain",
"title": "Axis",
"type": "string"
}
},
{
"in": "query",
"name": "status_filter",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Status Filter"
}
},
{
"in": "query",
"name": "source_type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Type"
}
},
{
"in": "query",
"name": "audience",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Audience"
}
},
{
"in": "query",
"name": "q",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"in": "query",
"name": "has_duplicate",
"required": false,
"schema": {
"default": false,
"title": "Has Duplicate",
"type": "boolean"
}
},
{
"in": "query",
"name": "exclude_personal",
"required": false,
"schema": {
"default": true,
"title": "Exclude Personal",
"type": "boolean"
}
},
{
"in": "query",
"name": "page",
"required": false,
"schema": {
"default": 1,
"title": "Page",
"type": "integer"
}
},
{
"in": "query",
"name": "per_page",
"required": false,
"schema": {
"default": 50,
"title": "Per Page",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Tree",
"tags": [
"memory"
]
}
},
"/api/memory/{item_id}/dismiss": {
"delete": {
"description": "Idempotent un-dismiss \u2014 a second DELETE still returns 200.\n\nReturns 404 if the item itself doesn't exist (consistent with the rest\nof the per-item endpoints); the dismissal row's existence is not\nconsulted because absence is the success state.",
"operationId": "undismiss_item_api_memory__item_id__dismiss_delete",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Undismiss Item",
"tags": [
"memory"
]
},
"post": {
"description": "Per-user opt-out \u2014 remove an item from the caller's AI bundle.\n\nIdempotent: re-dismissing an already-dismissed item is a no-op success.\nMandatory items can never be dismissed \u2014 the governance hard rule \u2014\nso a POST against one returns 400 with a clear detail message.",
"operationId": "dismiss_item_api_memory__item_id__dismiss_post",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Dismiss Item",
"tags": [
"memory"
]
}
},
"/api/memory/{item_id}/personal": {
"post": {
"description": "Toggle personal/excluded flag on a knowledge item (only by the contributor).",
"operationId": "toggle_personal_flag_api_memory__item_id__personal_post",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PersonalFlagRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Toggle Personal Flag",
"tags": [
"memory"
]
}
},
"/api/memory/{item_id}/provenance": {
"get": {
"description": "Get source provenance for a knowledge item.",
"operationId": "get_provenance_api_memory__item_id__provenance_get",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Provenance",
"tags": [
"memory"
]
}
},
"/api/memory/{item_id}/vote": {
"post": {
"operationId": "vote_knowledge_api_memory__item_id__vote_post",
"parameters": [
{
"in": "path",
"name": "item_id",
"required": true,
"schema": {
"title": "Item Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VoteRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Vote Knowledge",
"tags": [
"memory"
]
}
},
"/api/metrics": {
"get": {
"description": "List all metric definitions, optionally filtered by category.",
"operationId": "list_metrics_api_metrics_get",
"parameters": [
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Metrics",
"tags": [
"metrics"
]
}
},
"/api/metrics/{metric_id}": {
"get": {
"description": "Get a single metric definition by ID.",
"operationId": "get_metric_api_metrics__metric_id__get",
"parameters": [
{
"in": "path",
"name": "metric_id",
"required": true,
"schema": {
"title": "Metric Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Metric",
"tags": [
"metrics"
]
}
},
"/api/my-stack": {
"get": {
"description": "Combined view of curated plugins the caller can subscribe to\nand Store entities they have installed.",
"operationId": "get_my_stack_api_my_stack_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MyStackResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get My Stack",
"tags": [
"my-stack"
]
}
},
"/api/my-stack/curated/{marketplace_id}/{plugin_name}": {
"put": {
"description": "Toggle subscribe/unsubscribe for a single curated plugin.\n\nUI thinks in terms of *enabled* (default off in Model B). v28+ the\nrepository stores *subscribed* rows (presence = enabled in served set);\n``enabled=true`` writes a row, ``enabled=false`` removes it.",
"operationId": "toggle_curated_api_my_stack_curated__marketplace_id___plugin_name__put",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToggleRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OkResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Toggle Curated",
"tags": [
"my-stack"
]
}
},
"/api/query": {
"post": {
"description": "Execute SQL against the server analytics DuckDB.\n\nPlain ``def`` (not ``async def``) so FastAPI auto-offloads the call\nto the anyio thread pool. The body invokes ``analytics.execute(sql)``\nsynchronously, which blocks for the full BQ jobs.query wait when a\nreferenced view resolves through the BQ extension. Under ``async def``\nthat block holds the single uvicorn event loop, freezing every other\nrequest (UI, /api/health, auth) until the query returns. Plain ``def``\nruns each invocation on its own thread, so heavy queries no longer\nstarve unrelated endpoints. See PR #188's CHANGELOG entry for the\nTier 1 event-loop unblocking rollout.",
"operationId": "execute_query_api_query_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/QueryResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Execute Query",
"tags": [
"query"
]
}
},
"/api/query/hybrid": {
"post": {
"operationId": "hybrid_query_api_query_hybrid_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HybridQueryRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Hybrid Query",
"tags": [
"query"
]
}
},
"/api/scripts": {
"get": {
"description": "List deployed scripts. Admin-only.",
"operationId": "list_scripts_api_scripts_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Scripts",
"tags": [
"scripts"
]
}
},
"/api/scripts/deploy": {
"post": {
"description": "Deploy a Python script to be run on the server (optionally on schedule). Admin-only.\n\nValidates the source against the safety blocklist BEFORE persisting \u2014\ncloses the Devin claim-fail-retry loop where a script with blocked\npatterns would land in script_registry, fail every scheduler tick, and\nre-claim itself perpetually.",
"operationId": "deploy_script_api_scripts_deploy_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeployScriptRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Deploy Script",
"tags": [
"scripts"
]
}
},
"/api/scripts/run": {
"post": {
"description": "Run an ad-hoc Python script (not deployed). Admin-only.",
"operationId": "run_adhoc_script_api_scripts_run_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunScriptRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Adhoc Script",
"tags": [
"scripts"
]
}
},
"/api/scripts/run-due": {
"post": {
"description": "Run every deployed script whose ``schedule`` says it is due.\n\nIterates ``script_registry``, skips rows without a schedule (those run\nonly via explicit POST /{id}/run), evaluates ``is_table_due(schedule,\nlast_run)``, and atomically claims each due row via\n``ScriptRepository.claim_for_run``. Execution is queued as a\n``BackgroundTask`` so the response returns immediately \u2014 the sidecar\nmust not block waiting on a long-running script.\n\nConcurrency: ``claim_for_run`` flips ``last_status`` to ``'running'``\ninside the same UPDATE; a script already in that state is skipped on\nsubsequent ticks until the BackgroundTask writes a terminal status via\n``record_run_result``. There is no max-runtime detection in this PR \u2014\nif a BackgroundTask crashes without writing a terminal status, the\nscript stays stuck in ``'running'`` until an operator clears it\nmanually (``UPDATE script_registry SET last_status = NULL WHERE id =\n?``). Documenting this as an accepted v0 limitation; revisit if it\nbites in practice.",
"operationId": "run_due_scripts_api_scripts_run_due_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Due Scripts",
"tags": [
"scripts"
]
}
},
"/api/scripts/{script_id}": {
"delete": {
"operationId": "undeploy_script_api_scripts__script_id__delete",
"parameters": [
{
"in": "path",
"name": "script_id",
"required": true,
"schema": {
"title": "Script Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Undeploy Script",
"tags": [
"scripts"
]
}
},
"/api/scripts/{script_id}/run": {
"post": {
"description": "Run a deployed script by ID. Admin-only.",
"operationId": "run_deployed_script_api_scripts__script_id__run_post",
"parameters": [
{
"in": "path",
"name": "script_id",
"required": true,
"schema": {
"title": "Script Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Run Deployed Script",
"tags": [
"scripts"
]
}
},
"/api/settings": {
"get": {
"description": "Get current user's sync settings.\n\nThe legacy ``permissions`` field that mirrored ``dataset_permissions``\nwas removed in v19 \u2014 table access is now via ``resource_grants``,\nqueryable through ``GET /api/me/effective-access``.",
"operationId": "get_settings_api_settings_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Settings",
"tags": [
"settings"
]
}
},
"/api/settings/dataset": {
"put": {
"description": "Enable or disable a dataset for sync.\n\nGate: the user must have a matching ``resource_grants`` row (or be\nAdmin). The user_sync_settings layer is per-user preference, not\nauthorization \u2014 gating the toggle here stops users from enabling\nsync on tables they cannot read.",
"operationId": "update_dataset_setting_api_settings_dataset_put",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DatasetSettingRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Dataset Setting",
"tags": [
"settings"
]
}
},
"/api/store/bundle.zip": {
"get": {
"description": "Stream a ZIP of all (filtered) Store entities.\n\nAuth: any authenticated user \u2014 the Store is community-open, the same\nset is already visible via ``GET /api/store/entities``. The bundle is\ndeterministic so two consecutive pulls without state changes produce\nbyte-identical ZIPs (modulo the manifest's ``generated_at`` timestamp).\nFilters mirror the listing endpoint so a backup workflow can scope by\ntype/owner if needed.",
"operationId": "export_bundle_api_store_bundle_zip_get",
"parameters": [
{
"description": "skill | agent | plugin",
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "skill | agent | plugin",
"title": "Type"
}
},
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "query",
"name": "search",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Search"
}
},
{
"description": "Filter by owner user_id",
"in": "query",
"name": "owner",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by owner user_id",
"title": "Owner"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Export Bundle",
"tags": [
"store"
]
}
},
"/api/store/categories": {
"get": {
"description": "Caller's group names \u2014 populates the upload form's category select.",
"operationId": "my_categories_api_store_categories_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"type": "string"
},
"title": "Response My Categories Api Store Categories Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "My Categories",
"tags": [
"store"
]
}
},
"/api/store/entities": {
"get": {
"operationId": "list_entities_api_store_entities_get",
"parameters": [
{
"in": "query",
"name": "skip",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Skip",
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 24,
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "type",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"in": "query",
"name": "category",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
{
"in": "query",
"name": "search",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Search"
}
},
{
"in": "query",
"name": "owner",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Owner"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreEntityListResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Entities",
"tags": [
"store"
]
},
"post": {
"operationId": "create_entity_api_store_entities_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_create_entity_api_store_entities_post"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreEntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Entity",
"tags": [
"store"
]
}
},
"/api/store/entities/preview": {
"post": {
"description": "Wizard step 1 \u2014 validate the uploaded ZIP and parse frontmatter for\npre-fill on step 2. Does **not** persist anything: tmp dir is wiped before\nthe response returns. The browser must hold the same File and re-submit\nit on step 2 (POST /entities) for the actual create.",
"operationId": "preview_entity_api_store_entities_preview_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_preview_entity_api_store_entities_preview_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreviewResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Preview Entity",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}": {
"delete": {
"description": "Soft-archive (default) or hard-delete (admin-only).\n\n* **Soft (default)** \u2014 flips `visibility_status='archived'`. Bundle\n stays on disk; existing user_store_installs continue serving the\n bundle through marketplace.zip / .git so already-installed users\n don't lose the plugin. Browse listings hide it; install endpoint\n refuses new installs. Owner + admin can soft-archive an\n approved entity.\n* **Hard (`?hard=true`)** \u2014 admin-only. Drops the row, removes the\n bundle from disk, deletes user_store_installs (existing users\n lose the plugin). Use for legal / privacy removals where the\n bytes have to go.\n\nQuarantined (pending / blocked / hidden) entities: only admins can\narchive or hard-delete; owner is refused so they can't erase the\nevidence of a flagged upload before triage.",
"operationId": "delete_entity_api_store_entities__entity_id__delete",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "query",
"name": "hard",
"required": false,
"schema": {
"default": false,
"title": "Hard",
"type": "boolean"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OkResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete Entity",
"tags": [
"store"
]
},
"get": {
"operationId": "get_entity_api_store_entities__entity_id__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreEntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Entity",
"tags": [
"store"
]
},
"put": {
"description": "Edit a flea-market entity. Owner or admin.\n\nv37 edit feature semantics:\n\n* **Type is locked** \u2014 passing ``type`` that differs from the\n stored row returns 400 ``type_locked``. Replacing one form\n factor with another is a fresh upload, not an edit.\n* **Display-name change** is allowed. Without a bundle change it\n flips the live slug immediately (mirrors rename-on-archive).\n Combined with a bundle change the rename is deferred \u2014 only the\n staged version dir is renamed; live keeps the prior slug until\n promotion, so existing installers never see a slug\u2260content pair\n mid-review.\n* **Bundle change** creates a new version: bake into\n ``versions/v<N+1>/plugin/``, run guardrails, on approval copy\n to the live ``plugin/`` dir + bump ``version_no`` + append\n ``version_history``. The prior version dir stays so rollback\n can copy it forward.\n* **Block-while-pending**: gates on the latest submission's status\n directly (``status IN ('pending_inline','pending_llm')``),\n independent of ``visibility_status``. Under deferred promotion\n v2+ edits leave the entity ``approved`` through the LLM review\n window, so a visibility-only check would never fire. Returns 409\n ``prior_version_pending``; owner waits for the verdict; the\n detail page auto-refreshes.\n* **Metadata-only edit** (no ``file`` posted) skips the bundle\n pipeline and the version bump.",
"operationId": "update_entity_api_store_entities__entity_id__put",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_update_entity_api_store_entities__entity_id__put"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreEntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Entity",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}/docs/{filename}": {
"get": {
"description": "Stream an attached doc \u2014 directory-traversal-guarded.",
"operationId": "get_entity_doc_api_store_entities__entity_id__docs__filename__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "filename",
"required": true,
"schema": {
"title": "Filename",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Entity Doc",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}/files": {
"get": {
"operationId": "list_entity_files_api_store_entities__entity_id__files_get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Entity Files",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}/install": {
"delete": {
"operationId": "uninstall_entity_api_store_entities__entity_id__install_delete",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Uninstall Entity",
"tags": [
"store"
]
},
"post": {
"operationId": "install_entity_api_store_entities__entity_id__install_post",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstallResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Install Entity",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}/photo": {
"get": {
"description": "Serve a flea-market entity's cover photo.\n\n**Auth model: login-only, no per-entity visibility check.** Cover\nphotos are uploader-designed showcase images \u2014 they exist to be seen\nand carry no PII / source / secrets. The previous\n``_enforce_visibility`` check serialized every request through a DB\njoin (same ``_system_db_lock`` rationale as\n``app/api/marketplace.py:curated_asset``). Login still required.\n\nCache: bytes change exactly when ``store_entities.version_no`` bumps,\nand listing endpoints append ``?v=<version_no>`` to the photo URL,\nso a 30-day ``immutable`` cache is safe \u2014 a re-upload generates a\nnew URL fingerprint that the browser refetches.",
"operationId": "get_entity_photo_api_store_entities__entity_id__photo_get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Entity Photo",
"tags": [
"store"
]
}
},
"/api/store/entities/{entity_id}/versions/{version_no}/restore": {
"post": {
"description": "Roll back to a prior version. Owner or admin.\n\nCreates a NEW version (`v<max+1>`) by copying the bundle bytes\nfrom `versions/v<N>/plugin/`, then runs the standard guardrails\npipeline so today's rules apply (rules tighten over time \u2014\npre-approved bundles re-validate at restore time).\n\nThe original `version_no` row in ``version_history`` keeps its\nown verdict; the new copy gets a fresh one. Forward-only history\n\u2014 no deletes from version_history.\n\nRefuses while a prior version is under review (same\n``prior_version_pending`` 409 as PUT).\n\nWrapped in the per-entity write lock so a concurrent PUT and\nrestore on the same entity can't both pass the pending-gate +\nrace on ``versions/v<N+1>/plugin/``.",
"operationId": "restore_version_api_store_entities__entity_id__versions__version_no__restore_post",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "version_no",
"required": true,
"schema": {
"title": "Version No",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StoreEntityResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Restore Version",
"tags": [
"store"
]
}
},
"/api/store/import-bundle": {
"post": {
"description": "Restore a Store bundle ZIP \u2014 admin only.\n\nModes:\n * ``merge`` (default) \u2014 upsert by ``entity_id``; existing entities\n are replaced when the bundle's ``version`` differs, otherwise\n skipped. Safe default for nightly cron round-trips.\n * ``replace`` \u2014 every entity in the bundle overwrites the existing\n row + on-disk tree. Bundle-not-in-target rows are NOT deleted.\n * ``skip`` \u2014 only entities NOT already present are imported.\n\nOwner resolution by ``owner_email``; missing emails get a stub\ndisabled user so the row references an existing ``users.id`` (no\nforeign key, but app code joins).",
"operationId": "import_bundle_api_store_import_bundle_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_import_bundle_api_store_import_bundle_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ImportBundleResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Import Bundle",
"tags": [
"store"
]
}
},
"/api/store/owners": {
"get": {
"description": "Owners who have at least one entity in the Store \u2014 populates the\nlisting-page owner filter. Sorted by display name (name fallbacks to\nemail then to username) so the dropdown is alphabetical and stable.\n\nVisibility filter (v32+/v35): non-admin sees owners-of-approved\nonly (a submitter with N quarantined uploads must not surface in\nthe public dropdown until at least one is approved). Admin sees\nevery owner regardless of state.",
"operationId": "list_owners_api_store_owners_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OwnerOption"
},
"title": "Response List Owners Api Store Owners Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Owners",
"tags": [
"store"
]
}
},
"/api/sync/manifest": {
"get": {
"description": "Return hash-based manifest of all synced data, filtered per user.\n\nSide-effect: stamps ``users.last_pull_at`` so the /home status frame\ncan show when the analyst last pulled. This GET is the canonical\n\"I am about to sync\" signal \u2014 agnes pull hits it first, then\ndownloads parquets whose hash changed. UI bumps (manifest browsed in\na browser session) also count; cheap and accurate enough for a\nhomepage card.",
"operationId": "sync_manifest_api_sync_manifest_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Sync Manifest",
"tags": [
"sync"
]
}
},
"/api/sync/settings": {
"get": {
"description": "Get user's dataset sync settings.",
"operationId": "get_sync_settings_api_sync_settings_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Sync Settings",
"tags": [
"sync"
]
},
"post": {
"description": "Update user's dataset sync settings.\n\nA dataset can only be enabled when the user has access (via\n``resource_grants(group, \"table\", dataset)`` or Admin membership). The\nuser_sync_settings layer is per-user preference, not authorization \u2014\nthe gate stops users from enabling sync on tables they cannot read.",
"operationId": "update_sync_settings_api_sync_settings_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SyncSettingsUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Sync Settings",
"tags": [
"sync"
]
}
},
"/api/sync/status": {
"get": {
"description": "Whether a sync is currently in flight on this app process.\n\nPublic (no auth) \u2014 used by the host-side ``agnes-auto-upgrade.sh``\ncron to decide whether to skip a `docker compose up -d` that would\nkill a running extractor / materialized pass mid-flight. Cheap to\nserve (single Lock.locked() check) and contains no sensitive data.\n\nReturns:\n ``{\"locked\": bool}`` \u2014 True if `_sync_lock` is currently held by\n a `_run_sync` invocation, OR a sync was triggered within the\n last ``_TRIGGER_HOLD_SEC`` seconds (so the FastAPI background\n task hasn't yet acquired the lock). Without the trigger-hold\n window, an auto-upgrade probe firing in the gap between the\n trigger handler's 200 response and the background task's\n ``_sync_lock.acquire()`` would see ``locked=False`` and proceed\n with ``up -d`` \u2014 killing the just-spawning extractor.",
"operationId": "sync_status_api_sync_status_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Sync Status",
"tags": [
"sync"
]
}
},
"/api/sync/table-subscriptions": {
"get": {
"description": "Get user's per-table subscription settings.",
"operationId": "get_table_subscriptions_api_sync_table_subscriptions_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Table Subscriptions",
"tags": [
"sync"
]
},
"post": {
"description": "Update per-table subscription preferences.\n\nMirrors the RBAC gate in POST /settings: a table can only be subscribed\nto when the user holds a resource_grants row for it (or is Admin). This\nprevents an authenticated user from subscribing to tables they cannot read.",
"operationId": "update_table_subscriptions_api_sync_table_subscriptions_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TableSubscriptionUpdate"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update Table Subscriptions",
"tags": [
"sync"
]
}
},
"/api/sync/trigger": {
"post": {
"description": "Trigger data sync from configured source. Admin only. Runs in background.\n\nBody accepts three shapes (all optional \u2014 empty body / `null` syncs\nevery registered table):\n\n - ``[\"kbc_job\", \"orders\"]`` \u2014 bare JSON array of table ids\n - ``{\"tables\": [\"kbc_job\", \"orders\"]}`` \u2014 object with a ``tables``\n key (matches the wire shape of the response, more discoverable\n for clients building requests by hand)\n - ``null`` / no body \u2014 sync everything\n\nBoth array forms have shipped at different times; accepting both\nkeeps older clients (PR-build CLIs, helper scripts) working while\nsurfacing the shape that mirrors the response payload. Anything\nelse returns HTTP 422 with a structured detail.\n\nReturns 409 if a previously-triggered sync is still running. Two\nconcurrent extractor subprocesses fight for the same `extract.duckdb`\nfile lock \u2014 that contention starves uvicorn, makes `/api/health` time\nout, flips the container to `unhealthy`, and (behind a `reverse_proxy`\nupstream like the bundled Caddy overlay) bricks external traffic\nuntil contention drains. Fast-fail here keeps that from happening.",
"operationId": "trigger_sync_api_sync_trigger_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Body"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Trigger Sync",
"tags": [
"sync"
]
}
},
"/api/telegram/status": {
"get": {
"description": "Get current Telegram link status.",
"operationId": "telegram_status_api_telegram_status_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Telegram Status",
"tags": [
"telegram"
]
}
},
"/api/telegram/unlink": {
"post": {
"description": "Unlink Telegram account.",
"operationId": "telegram_unlink_api_telegram_unlink_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Telegram Unlink",
"tags": [
"telegram"
]
}
},
"/api/telegram/verify": {
"post": {
"description": "Verify a code to link Telegram account.",
"operationId": "telegram_verify_api_telegram_verify_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VerifyRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Telegram Verify",
"tags": [
"telegram"
]
}
},
"/api/upload/artifacts": {
"post": {
"description": "Upload an artifact (HTML report, PNG chart, etc.).",
"operationId": "upload_artifact_api_upload_artifacts_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_upload_artifact_api_upload_artifacts_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Upload Artifact",
"tags": [
"upload"
]
}
},
"/api/upload/local-md": {
"post": {
"description": "Upload CLAUDE.local.md content for corporate memory processing.",
"operationId": "upload_local_md_api_upload_local_md_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LocalMdRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Upload Local Md",
"tags": [
"upload"
]
}
},
"/api/upload/sessions": {
"post": {
"description": "Upload a Claude session transcript (JSONL).",
"operationId": "upload_session_api_upload_sessions_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_upload_session_api_upload_sessions_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Upload Session",
"tags": [
"upload"
]
}
},
"/api/users": {
"get": {
"operationId": "list_users_api_users_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 1000,
"maximum": 10000,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/UserResponse"
},
"title": "Response List Users Api Users Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Users",
"tags": [
"users"
]
},
"post": {
"operationId": "create_user_api_users_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateUserRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create User",
"tags": [
"users"
]
}
},
"/api/users/{user_id}": {
"delete": {
"operationId": "delete_user_api_users__user_id__delete",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Delete User",
"tags": [
"users"
]
},
"get": {
"description": "Single-user payload used by the /admin/users/{id} detail page header\nand the account-status block. Same shape as the list endpoint, so the\npage can reuse the same response shape.",
"operationId": "get_user_api_users__user_id__get",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get User",
"tags": [
"users"
]
},
"patch": {
"operationId": "update_user_api_users__user_id__patch",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateUserRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Update User",
"tags": [
"users"
]
}
},
"/api/users/{user_id}/activate": {
"post": {
"operationId": "activate_user_api_users__user_id__activate_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Activate User",
"tags": [
"users"
]
}
},
"/api/users/{user_id}/deactivate": {
"post": {
"operationId": "deactivate_user_api_users__user_id__deactivate_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Deactivate User",
"tags": [
"users"
]
}
},
"/api/users/{user_id}/reset-password": {
"post": {
"description": "Generate a reset token and (best-effort) email it to the user.",
"operationId": "reset_password_api_users__user_id__reset_password_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Reset Password",
"tags": [
"users"
]
}
},
"/api/users/{user_id}/set-password": {
"post": {
"operationId": "set_password_api_users__user_id__set_password_post",
"parameters": [
{
"in": "path",
"name": "user_id",
"required": true,
"schema": {
"title": "User Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SetPasswordRequest"
}
}
},
"required": true
},
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Set Password",
"tags": [
"users"
]
}
},
"/api/v2/catalog": {
"get": {
"operationId": "catalog_api_v2_catalog_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Catalog",
"tags": [
"v2"
]
}
},
"/api/v2/metadata-cache/refresh": {
"post": {
"description": "Operator on-demand refresh of one row.\n\nUseful right after editing the registry row (so the catalog reflects\nnew ``bucket`` / ``source_table`` immediately) or after an upstream\nBQ schema change that the operator wants reflected before the next\nscheduled tick.",
"operationId": "refresh_one_table_api_v2_metadata_cache_refresh_post",
"parameters": [
{
"description": "Registry table_id to refresh",
"in": "query",
"name": "table",
"required": true,
"schema": {
"description": "Registry table_id to refresh",
"title": "Table",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Refresh One Table"
}
},
"/api/v2/metadata-cache/status": {
"get": {
"description": "Per-table cache status. Non-admin \u2014 analyst tools rely on this to\ndecide whether to trust the catalog's ``rows`` / ``size_bytes`` or\ntreat the table as opaque until the next refresh.",
"operationId": "metadata_cache_status_api_v2_metadata_cache_status_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Metadata Cache Status"
}
},
"/api/v2/sample/{table_id}": {
"get": {
"operationId": "sample_api_v2_sample__table_id__get",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "query",
"name": "n",
"required": false,
"schema": {
"default": 5,
"maximum": 100,
"minimum": 1,
"title": "N",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Sample",
"tags": [
"v2"
]
}
},
"/api/v2/scan": {
"post": {
"operationId": "scan_endpoint_api_v2_scan_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Raw",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Scan Endpoint",
"tags": [
"v2"
]
}
},
"/api/v2/scan/estimate": {
"post": {
"operationId": "scan_estimate_endpoint_api_v2_scan_estimate_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Raw",
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Scan Estimate Endpoint",
"tags": [
"v2"
]
}
},
"/api/v2/schema/{table_id}": {
"get": {
"operationId": "schema_api_v2_schema__table_id__get",
"parameters": [
{
"in": "path",
"name": "table_id",
"required": true,
"schema": {
"title": "Table Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Schema",
"tags": [
"v2"
]
}
},
"/api/version": {
"get": {
"description": "Lightweight version info \u2014 cacheable, no DB touch. Used by UI footer badge.",
"operationId": "version_info_api_version_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Version Info",
"tags": [
"health"
]
}
},
"/api/welcome": {
"get": {
"description": "Return the rendered CLAUDE.md for the authenticated analyst.\n\nThe CLI calls this endpoint during ``agnes init`` to write\n``<workspace>/CLAUDE.md``. The content is RBAC-filtered per the\ncalling user.\n\n``server_url`` query param lets the CLI pass the origin it knows so\nthe rendered content references the correct server URL rather than the\nrequest host (which may differ behind a proxy).",
"operationId": "get_welcome_api_welcome_get",
"parameters": [
{
"description": "Server URL used in rendered CLAUDE.md",
"in": "query",
"name": "server_url",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Server URL used in rendered CLAUDE.md",
"title": "Server Url"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClaudeMdResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Welcome",
"tags": [
"claude_md"
]
}
},
"/auth/admin/tokens": {
"get": {
"operationId": "admin_list_tokens_auth_admin_tokens_get",
"parameters": [
{
"in": "query",
"name": "limit",
"required": false,
"schema": {
"default": 1000,
"maximum": 10000,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
{
"in": "query",
"name": "offset",
"required": false,
"schema": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/AdminTokenItem"
},
"title": "Response Admin List Tokens Auth Admin Tokens Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin List Tokens",
"tags": [
"tokens-admin"
]
}
},
"/auth/admin/tokens/{token_id}": {
"delete": {
"operationId": "admin_revoke_token_auth_admin_tokens__token_id__delete",
"parameters": [
{
"in": "path",
"name": "token_id",
"required": true,
"schema": {
"title": "Token Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Admin Revoke Token",
"tags": [
"tokens-admin"
]
}
},
"/auth/bootstrap": {
"post": {
"description": "Bootstrap the first admin account.\n\nAllowed when no user has a password_hash yet. This covers:\n(a) No users exist at all.\n(b) Only seed users (created by SEED_ADMIN_EMAIL at startup) exist, which\n have no password and cannot log in \u2014 bootstrap lets the operator\n activate them with a password.\n\nIf a user with the given email already exists (e.g. as a seed), this\nendpoint sets its password_hash (or clears it, if no password was supplied \u2014\nuseful for OAuth-only flows) and promotes it to admin.\n\nDeactivates as soon as any user has a password_hash.",
"operationId": "bootstrap_auth_bootstrap_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BootstrapRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Bootstrap",
"tags": [
"auth"
]
}
},
"/auth/email/send-link": {
"post": {
"description": "Send a magic link to the user's email.\n\nWhen SMTP/SendGrid is not configured, or LOCAL_DEV_MODE=1, the link is\nlogged to stderr and returned in the response body so a developer can\nclick it without an email transport.",
"operationId": "send_magic_link_auth_email_send_link_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MagicLinkRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Send Magic Link",
"tags": [
"auth"
]
}
},
"/auth/email/verify": {
"get": {
"description": "Click-through variant \u2014 verifies token, sets cookie, redirects to the\noperator-configured home route.\n\nThis is the URL we embed in outgoing emails (and the dev-fallback link), so\nclicking it in a mail client logs the user in without a separate API call.\n\nRate limited 10/min per IP for the same reason as the POST variant \u2014\ndon't let the click-through path bypass the brute-force throttle.",
"operationId": "verify_magic_link_get_auth_email_verify_get",
"parameters": [
{
"in": "query",
"name": "email",
"required": true,
"schema": {
"title": "Email",
"type": "string"
}
},
{
"in": "query",
"name": "token",
"required": true,
"schema": {
"title": "Token",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Verify Magic Link Get",
"tags": [
"auth"
]
},
"post": {
"description": "Verify a magic link token and issue JWT (JSON API for programmatic clients).\n\nRate limited 10/min per IP to slow brute-forcing the 32-byte\n``reset_token`` (the same column doubles as the magic-link token).",
"operationId": "verify_magic_link_auth_email_verify_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MagicLinkVerify"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Verify Magic Link",
"tags": [
"auth"
]
}
},
"/auth/google/callback": {
"get": {
"description": "Handle Google OAuth callback.",
"operationId": "google_callback_auth_google_callback_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Google Callback",
"tags": [
"auth"
]
}
},
"/auth/google/login": {
"get": {
"description": "Redirect to Google OAuth.\n\nHonors `?next=<path>` by stashing the sanitized value in the session so the\ncallback can redirect there instead of the default /dashboard. The session\nis the right stash \u2014 OAuth flow is stateful and the `state` param is\nmanaged by Authlib.",
"operationId": "google_login_auth_google_login_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Google Login",
"tags": [
"auth"
]
}
},
"/auth/password/login": {
"post": {
"description": "Login with email + password.",
"operationId": "password_login_auth_password_login_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordLoginRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Password Login",
"tags": [
"auth"
]
}
},
"/auth/password/login/web": {
"post": {
"description": "Web form login \u2014 sets cookie and redirects to `next` (or /dashboard).",
"operationId": "password_login_web_auth_password_login_web_post",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_password_login_web_auth_password_login_web_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Password Login Web",
"tags": [
"auth"
]
}
},
"/auth/password/reset": {
"get": {
"description": "Render the 'set new password' form when arriving via reset link.",
"operationId": "reset_page_auth_password_reset_get",
"parameters": [
{
"in": "query",
"name": "email",
"required": false,
"schema": {
"default": "",
"title": "Email",
"type": "string"
}
},
{
"in": "query",
"name": "token",
"required": false,
"schema": {
"default": "",
"title": "Token",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Reset Page",
"tags": [
"auth"
]
},
"post": {
"description": "Request a password-reset link. Anti-enumeration: same response regardless.\n\nRate limited at the same 5/min as ``/auth/email/send-link`` \u2014 the\nattack surface is identical (single IP rotates random recipient\naddresses, anti-enumeration response shape masks which addresses\nlanded, attacker burns SMTP / SendGrid quota + spams real users).",
"operationId": "reset_request_auth_password_reset_post",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_reset_request_auth_password_reset_post"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Reset Request",
"tags": [
"auth"
]
}
},
"/auth/password/reset/confirm": {
"post": {
"description": "Submit a new password using a reset token.\n\nRate limited 10/min per IP to slow brute-force guessing of the 32-byte\nURL-safe ``reset_token`` \u2014 the token is high-entropy but logs / proxy\nreferer leaks have surfaced partial tokens before, and there's no\nreason to allow unbounded attempts.",
"operationId": "reset_confirm_auth_password_reset_confirm_post",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_reset_confirm_auth_password_reset_confirm_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Reset Confirm",
"tags": [
"auth"
]
}
},
"/auth/password/setup": {
"get": {
"description": "Render the initial 'set password + name' form when arriving via invite link.\n\nNote: we render the form based on URL params only, without a DB lookup, so\nthe response is identical for valid and invalid email/token combinations\n(anti-enumeration). Token validity is checked at POST /setup/confirm.",
"operationId": "setup_page_auth_password_setup_get",
"parameters": [
{
"in": "query",
"name": "email",
"required": false,
"schema": {
"default": "",
"title": "Email",
"type": "string"
}
},
{
"in": "query",
"name": "token",
"required": false,
"schema": {
"default": "",
"title": "Token",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Setup Page",
"tags": [
"auth"
]
},
"post": {
"description": "Set initial password using setup token (JSON API).\n\nRate limited 10/min per IP \u2014 same throttle as the form sibling\n``/setup/confirm``. Without this, the new web-form throttle is\nbypassable: an attacker brute-forcing the ``setup_token`` just\nswitches to this JSON path and resumes at unbounded RPS.",
"operationId": "password_setup_auth_password_setup_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PasswordSetupRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Password Setup",
"tags": [
"auth"
]
}
},
"/auth/password/setup/confirm": {
"post": {
"description": "Web form: complete initial password setup via setup token.\n\nRate limited 10/min per IP \u2014 same rationale as ``/reset/confirm``:\nhigh-entropy ``setup_token`` should still not be brute-forceable at\nunbounded RPS in case a partial token leaks via logs / referer.",
"operationId": "setup_confirm_auth_password_setup_confirm_post",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_setup_confirm_auth_password_setup_confirm_post"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Setup Confirm",
"tags": [
"auth"
]
}
},
"/auth/password/setup/request": {
"post": {
"description": "Self-service 'Request Access' \u2014 emails a setup link if user is pre-approved and unset.\n\nSame 5/min rate limit as ``/auth/password/reset`` and ``/send-link``\n\u2014 same email-bombing surface (anti-enumeration response, sends mail\non each request).",
"operationId": "setup_request_auth_password_setup_request_post",
"requestBody": {
"content": {
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/Body_setup_request_auth_password_setup_request_post"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Setup Request",
"tags": [
"auth"
]
}
},
"/auth/token": {
"post": {
"description": "Issue a JWT token. Requires password authentication.",
"operationId": "create_token_auth_token_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Token",
"tags": [
"auth"
]
}
},
"/auth/tokens": {
"get": {
"operationId": "list_tokens_auth_tokens_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/TokenListItem"
},
"title": "Response List Tokens Auth Tokens Get",
"type": "array"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "List Tokens",
"tags": [
"tokens"
]
},
"post": {
"operationId": "create_token_auth_tokens_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTokenRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateTokenResponse"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Create Token",
"tags": [
"tokens"
]
}
},
"/auth/tokens/{token_id}": {
"delete": {
"operationId": "revoke_token_auth_tokens__token_id__delete",
"parameters": [
{
"in": "path",
"name": "token_id",
"required": true,
"schema": {
"title": "Token Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Revoke Token",
"tags": [
"tokens"
]
},
"get": {
"operationId": "get_token_auth_tokens__token_id__get",
"parameters": [
{
"in": "path",
"name": "token_id",
"required": true,
"schema": {
"title": "Token Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TokenListItem"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Get Token",
"tags": [
"tokens"
]
}
},
"/catalog": {
"get": {
"operationId": "catalog_catalog_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Catalog",
"tags": [
"web"
]
}
},
"/cli/download": {
"get": {
"operationId": "cli_download_cli_download_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Cli Download",
"tags": [
"cli"
]
}
},
"/cli/install.sh": {
"get": {
"description": "Shell installer \u2014 bakes this server's URL into the generated config.",
"operationId": "cli_install_script_cli_install_sh_get",
"responses": {
"200": {
"content": {
"text/plain": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Cli Install Script",
"tags": [
"cli"
]
}
},
"/cli/latest": {
"get": {
"description": "Metadata for the currently-shipped CLI wheel.\n\nConsumed by `agnes` CLI's auto-update check so it can warn when a newer\nversion is on the server. Public + cacheable \u2014 no secrets here.\nReturns `version=None` when the server has no wheel yet (dev image that\ndidn't run `uv build`).",
"operationId": "cli_latest_cli_latest_get",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Cli Latest",
"tags": [
"cli"
]
}
},
"/cli/wheel/{wheel_name}": {
"get": {
"description": "Serve the currently-present wheel at a PEP 427-compliant URL.\n\nOnly the exact filename of the current wheel is honoured; any other\n`wheel_name` returns 404. No filesystem lookup is done from user input \u2014\nthe path param is only compared against `_find_wheel().name`.",
"operationId": "cli_wheel_versioned_cli_wheel__wheel_name__get",
"parameters": [
{
"in": "path",
"name": "wheel_name",
"required": true,
"schema": {
"title": "Wheel Name",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Cli Wheel Versioned",
"tags": [
"cli"
]
}
},
"/corporate-memory": {
"get": {
"description": "Curated Memory web view \u2014 any authenticated user.\n\nThis is the analyst-facing read surface for shared organizational\nknowledge: it lists ``approved`` / ``mandatory`` items plus the\ncaller's own contributions, and sits in the primary nav next to\nData Packages. The admin review queue (pending items, contradictions,\nduplicates) lives separately at ``/admin/corporate-memory`` behind\n``require_admin``.\n\nGating matches the underlying ``/api/memory/*`` endpoints, which\nalready run on ``get_current_user`` \u2014 CLI / agent flows that POST a\nknowledge item or read ``/api/memory`` work for any authenticated\nuser, so the web view does too. Admin-only affordances on this page\n(the pending-review banner) stay gated server-side: ``is_admin_view``\nzeroes ``pending_review_count`` for non-admins.",
"operationId": "corporate_memory_corporate_memory_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Corporate Memory",
"tags": [
"web"
]
}
},
"/dashboard": {
"get": {
"operationId": "dashboard_dashboard_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Dashboard",
"tags": [
"web"
]
}
},
"/first-time-setup": {
"get": {
"description": "First-time setup wizard. Redirects to login if users already exist.",
"operationId": "setup_wizard_first_time_setup_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Setup Wizard",
"tags": [
"web"
]
}
},
"/home": {
"get": {
"description": "State-aware /home \u2014 full inline install for not-onboarded users,\nclean nav hub once onboarded. The boolean drives template selection;\nno auto-transition (manual reload picks up the flip after\n``agnes init`` POSTs ``/api/me/onboarded``).\n\nSee origin: docs/brainstorms/home-page-requirements.md.",
"operationId": "home_page_home_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Home Page",
"tags": [
"web"
]
}
},
"/install": {
"get": {
"description": "Backwards-compat redirect: /install \u2192 /setup (302).\n\nUsing 302 (temporary) rather than 301 (permanent) so browsers/proxies\ndon't cache indefinitely \u2014 if the path ever changes again, cached 301s\nrequire manual cache clearing to recover.",
"operationId": "install_redirect_install_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Install Redirect",
"tags": [
"web"
]
}
},
"/login": {
"get": {
"operationId": "login_page_login_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Login Page",
"tags": [
"web"
]
}
},
"/login/email": {
"get": {
"description": "Email magic link login form.",
"operationId": "login_email_page_login_email_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Login Email Page",
"tags": [
"web"
]
}
},
"/login/password": {
"get": {
"description": "Password login form (email + password).",
"operationId": "login_password_page_login_password_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Login Password Page",
"tags": [
"web"
]
}
},
"/marketplace": {
"get": {
"operationId": "marketplace_listing_marketplace_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Listing",
"tags": [
"web"
]
}
},
"/marketplace.zip": {
"get": {
"operationId": "marketplace_zip_marketplace_zip_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Zip",
"tags": [
"marketplace"
]
}
},
"/marketplace/curated/{marketplace_id}/{plugin_name}": {
"get": {
"description": "Server-renders only the shell \u2014 the page hydrates via\n``GET /api/marketplace/curated/{slug}/{plugin}`` which carries the\nreal RBAC guard. Direct URL access for users without the grant lands on\na shell that 403s on the first XHR; UX-level the page renders an empty\nstate and a back link.",
"operationId": "marketplace_curated_detail_marketplace_curated__marketplace_id___plugin_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Curated Detail",
"tags": [
"web"
]
}
},
"/marketplace/curated/{marketplace_id}/{plugin_name}/agent/{agent_name}": {
"get": {
"operationId": "marketplace_curated_agent_detail_marketplace_curated__marketplace_id___plugin_name__agent__agent_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "agent_name",
"required": true,
"schema": {
"title": "Agent Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Curated Agent Detail",
"tags": [
"web"
]
}
},
"/marketplace/curated/{marketplace_id}/{plugin_name}/skill/{skill_name}": {
"get": {
"operationId": "marketplace_curated_skill_detail_marketplace_curated__marketplace_id___plugin_name__skill__skill_name__get",
"parameters": [
{
"in": "path",
"name": "marketplace_id",
"required": true,
"schema": {
"title": "Marketplace Id",
"type": "string"
}
},
{
"in": "path",
"name": "plugin_name",
"required": true,
"schema": {
"title": "Plugin Name",
"type": "string"
}
},
{
"in": "path",
"name": "skill_name",
"required": true,
"schema": {
"title": "Skill Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Curated Skill Detail",
"tags": [
"web"
]
}
},
"/marketplace/flea/{entity_id}": {
"get": {
"description": "Pick the right detail template based on the entity type:\nplugins reuse the unified plugin layout; skills / agents render the\nitem-detail layout (matches curated nested skill / agent).\n\nVisibility (v32+): non-owner non-admin gets 404 on any non-approved\nentity. Owner + admin see the page with a quarantine banner + the\nowner-actions strip (Edit / Delete with locked variants).",
"operationId": "marketplace_flea_detail_marketplace_flea__entity_id__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Flea Detail",
"tags": [
"web"
]
}
},
"/marketplace/flea/{entity_id}/agent/{agent_name}": {
"get": {
"description": "Inner agent detail page for an agent nested inside a flea plugin.\n\nMirrors ``marketplace_flea_skill_detail``; kind=\"agent\".",
"operationId": "marketplace_flea_agent_detail_marketplace_flea__entity_id__agent__agent_name__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "agent_name",
"required": true,
"schema": {
"title": "Agent Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Flea Agent Detail",
"tags": [
"web"
]
}
},
"/marketplace/flea/{entity_id}/edit": {
"get": {
"description": "Edit page for a flea-market entity (v37 edit feature).\n\nOwner or admin only. Pre-fills metadata + lets the submitter\noptionally upload a new bundle (creates v<N+1>). Skipping the\nbundle field updates only metadata. Edit is blocked while a\nprior version is under review \u2014 the form surfaces a banner and\ndisables Save in that case (the API gate also enforces 409\nserver-side).",
"operationId": "store_edit_marketplace_flea__entity_id__edit_get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Store Edit",
"tags": [
"web"
]
}
},
"/marketplace/flea/{entity_id}/skill/{skill_name}": {
"get": {
"description": "Inner skill detail page for a skill nested inside a flea plugin.\n\nMirrors ``marketplace_curated_skill_detail`` but uses the standalone\nflea visibility gate (``_enforce_visibility``) \u2014 owner / admin see\nquarantined entities, everyone else gets 404 (entity existence not\nleaked).",
"operationId": "marketplace_flea_skill_detail_marketplace_flea__entity_id__skill__skill_name__get",
"parameters": [
{
"in": "path",
"name": "entity_id",
"required": true,
"schema": {
"title": "Entity Id",
"type": "string"
}
},
{
"in": "path",
"name": "skill_name",
"required": true,
"schema": {
"title": "Skill Name",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Flea Skill Detail",
"tags": [
"web"
]
}
},
"/marketplace/format-guide": {
"get": {
"description": "Render docs/curated-marketplace-format.md as a logged-in HTML page.\n\nThe Markdown source is the canonical reference for upstream curators \u2014\nliving it next to docs/ in the repo means it's also discoverable on the\npublic GitHub mirror, so an external maintainer can read it without\nneeding an Agnes account. The web rendering exists for the in-product\nflow (link from /admin/marketplaces) and uses Python's ``markdown``\nlibrary with the standard extensions for fenced code + tables.\n\nAuth: ``Depends(get_current_user)`` only \u2014 no admin requirement. The\naudience is \"anyone authoring or reviewing a curated marketplace,\"\nwhich is broader than admins and could include non-admin curators.",
"operationId": "marketplace_format_guide_marketplace_format_guide_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Format Guide",
"tags": [
"web"
]
}
},
"/marketplace/guide/curated": {
"get": {
"operationId": "marketplace_guide_curated_marketplace_guide_curated_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Guide Curated",
"tags": [
"web"
]
}
},
"/marketplace/guide/flea": {
"get": {
"operationId": "marketplace_guide_flea_marketplace_guide_flea_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Guide Flea",
"tags": [
"web"
]
}
},
"/marketplace/info": {
"get": {
"operationId": "marketplace_info_marketplace_info_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Marketplace Info",
"tags": [
"marketplace"
]
}
},
"/me/activity": {
"get": {
"description": "Unified personal-activity page \u2014 consolidated replacement for\nthe old ``/me/stats`` + ``/profile/sessions`` split. Four tabs\n(Sessions / Token usage / Data access / Sync activity) backed by\n``/api/me/stats/*`` endpoints. The Sessions tab merges usage\nmetrics with verification-pipeline status and download links.",
"operationId": "me_activity_page_me_activity_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Me Activity Page",
"tags": [
"web"
]
}
},
"/me/profile": {
"get": {
"description": "User profile \u2014 self-service view of identity and group memberships.\n\nRenders the user's account info plus a list of group memberships joined\nagainst ``user_groups`` (with the source label so users can tell which\nwere added by an admin, by Google sync, or seeded at deploy).",
"operationId": "profile_page_me_profile_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Profile Page",
"tags": [
"web"
]
}
},
"/me/profile/refetch-groups": {
"post": {
"description": "Re-issue ``fetch_user_groups`` for the current user and return a\ndry-run diff against the cached ``user_group_members`` snapshot,\nwriting nothing. Gated behind AGNES_DEBUG_AUTH \u2014 a dry-run admin\ndebug action, not user-facing content.",
"operationId": "me_profile_refetch_groups_me_profile_refetch_groups_post",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Me Profile Refetch Groups",
"tags": [
"web"
]
}
},
"/me/stats": {
"get": {
"description": "Legacy redirect \u2014 ``/me/stats`` \u2192 ``/me/activity``.",
"operationId": "me_stats_redirect_me_stats_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Me Stats Redirect",
"tags": [
"web"
]
}
},
"/news": {
"get": {
"description": "Permalink page for the latest published news. Renders empty-state\ncopy when no version is published. Authed-only (same as /home).",
"operationId": "news_page_news_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "News Page",
"tags": [
"web"
]
}
},
"/profile/sessions": {
"get": {
"description": "Legacy redirect \u2014 ``/profile/sessions`` \u2192 ``/me/activity?tab=sessions``.",
"operationId": "profile_sessions_redirect_profile_sessions_get",
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
}
},
"summary": "Profile Sessions Redirect",
"tags": [
"web"
]
}
},
"/profile/sessions/{filename}": {
"get": {
"description": "Download a single jsonl session file owned by the caller.\n\nPath safety: filename is single-component (no separators, no `..`,\nmust end in `.jsonl`); the served path is built under\n`${DATA_DIR}/user_sessions/<current_user.id>/` and must resolve into\nthat directory. Any deviation yields 404 \u2014 never 403, so we don't\nleak the existence of files belonging to other users.",
"operationId": "profile_session_download_profile_sessions__filename__get",
"parameters": [
{
"in": "path",
"name": "filename",
"required": true,
"schema": {
"title": "Filename",
"type": "string"
}
},
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Profile Session Download",
"tags": [
"web"
]
}
},
"/setup": {
"get": {
"description": "Setup instructions for the local agent (CLI + Claude Code).\n\nSingle unified flow for everyone \u2014 admin-vs-analyst is no longer a\nlayout branch. The marketplace + plugins block appears iff the\ncaller has plugin grants in `resource_grants` (resolved inside\n`compute_default_agent_prompt`).\n\nWhen an admin override is saved, the override replaces the\nauto-generated setup_instructions output everywhere (both the\n/setup page display and the dashboard clipboard CTA). When no\noverride is set, the live default from\nsetup_instructions.resolve_lines() is used.",
"operationId": "setup_page_setup_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Setup Page",
"tags": [
"web"
]
}
},
"/setup-advanced": {
"get": {
"description": "Advanced setup reference \u2014 VS Code layout, recommended plugins,\nmulti-model second opinions, custom skills, cost guidance.\n\nPulls the deeper Chief-of-Stuff guide content out of /home so /home\nstays scannable for first-hour onboarding. Linked from /home's\n\"Want to look around first?\" explore card and from any deep-link\nanchors emitted by other pages (e.g. /home's auto-mode block points\nat #yolo).",
"operationId": "setup_advanced_page_setup_advanced_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Setup Advanced Page",
"tags": [
"web"
]
}
},
"/store/examples": {
"get": {
"description": "Examples of well-formed flea-market submissions.\n\nLinked from the content-guardrail rejection banner so a submitter\nwhose bundle failed review can see what 'good' looks like\nside-by-side with the rule that bit them.",
"operationId": "store_examples_store_examples_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Store Examples",
"tags": [
"web"
]
}
},
"/store/new": {
"get": {
"operationId": "store_new_store_new_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"text/html": {
"schema": {
"type": "string"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Store New",
"tags": [
"web"
]
}
},
"/webhooks/jira": {
"post": {
"description": "Receive and process Jira webhook notifications.",
"operationId": "receive_jira_webhook_webhooks_jira_post",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Successful Response"
}
},
"summary": "Receive Jira Webhook",
"tags": [
"jira-webhooks"
]
}
},
"/webhooks/jira/health": {
"get": {
"description": "Health check for Jira webhook endpoint. Admin-only: exposes secret presence.",
"operationId": "jira_webhook_health_webhooks_jira_health_get",
"parameters": [
{
"in": "header",
"name": "authorization",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"additionalProperties": true,
"title": "Response Jira Webhook Health Webhooks Jira Health Get",
"type": "object"
}
}
},
"description": "Successful Response"
},
"422": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
"description": "Validation Error"
}
},
"summary": "Jira Webhook Health",
"tags": [
"jira-webhooks"
]
}
}
}
}
Reference in a new issue View git blame Copy permalink