Skip to content

api.md

Latest commit

 

History

History
341 lines (279 loc) · 20.9 KB

api.md

File metadata and controls

341 lines (279 loc) · 20.9 KB
Raw

API Reference

GENERATED FILE - do not edit by hand. Regenerate with python3 scripts/gen_docs.py.

201 endpoints across 18 route modules. All paths are relative to the API base (e.g. http://127.0.0.1:8765). Auth: single-user - first run uses POST /auth/auto only until the owner sets a password; later sessions use POST /auth/login. Requests carry the HttpOnly proxima_session cookie or Authorization: Bearer <token>.

Modules

routes/admin.py

Method Path Handler Description
GET /api/audit list_audit
GET /api/debug/logs debug_logs
POST /api/debug/reap-orphaned-jobs reap_orphaned_jobs

routes/archive.py

Method Path Handler Description
GET /api/archive list_archive Paginated deliverable records, newest first, with filter facet counts.
GET /api/archive/badges archive_badges Badge data for the Files tree (the Deliverables lens, #139): the
POST /api/archive/records/{record_id}/status set_archive_status The record-panel door of the ONE approval status (late/batch/
GET /api/archive/{slug}/{record_slug} get_archive_record One full record by its permanent address: metadata, lineage,

routes/auth.py

Method Path Handler Description
GET /api/me me
GET /api/setup/status setup_status
POST /auth/auto auth_auto First-run passwordless session bootstrap. Disabled once the owner password
POST /auth/change-password change_password Change the password (from Settings): verify the current one, set the new,
POST /auth/login login_with_password Verify the owner's password and start a session (expires after the
POST /auth/logout logout
POST /auth/resume resume Boot resume: authenticated by the HttpOnly cookie, echo the session token
POST /auth/set-password set_password First-run: set the owner's password. Only allowed while none is set (later
GET /health health

routes/chat.py

Method Path Handler Description
POST /api/chat/send chat_send
GET /api/dashboard dashboard Aggregated real-data summary for the Home dashboard.
GET /api/runs/active active_runs Sessions with an in-flight run, so the sidebar can show a thinking
DELETE /api/runs/{run_id} delete_run
GET /api/runs/{run_id} get_run
POST /api/runs/{run_id}/cancel cancel_run
POST /api/runs/{run_id}/permission respond_permission Deliver the user's interactive card choice back to the waiting agent.
GET /api/search search
GET /api/sessions list_sessions
POST /api/sessions create_session
DELETE /api/sessions/{session_id} delete_session
GET /api/sessions/{session_id} get_session
PATCH /api/sessions/{session_id} update_session
GET /api/sessions/{session_id}/events list_events
GET /api/sessions/{session_id}/events/stream stream_events
GET /api/sessions/{session_id}/messages list_messages
POST /api/sessions/{session_id}/messages create_message
POST /api/sessions/{session_id}/promote-workflow promote_workflow
POST /api/sessions/{session_id}/runs create_run
POST /api/sessions/{session_id}/wiki-note/commit wiki_note_commit
POST /api/sessions/{session_id}/wiki-note/draft wiki_note_draft
WS /api/ws/sessions/{session_id} ws_events
WS /api/ws/terminal ws_terminal In-browser PTY shell (like SSH from the cockpit). Auth via ?token= or the

routes/containers.py

Method Path Handler Description
GET /api/containers list_containers List the owner's Fleet registry with directly aggregated Live state.
GET /api/containers/{slug} get_container Read one owner-scoped Container and its current Fleet indicators.
GET /api/containers/{slug}/areas list_container_areas List targetable Areas after canonical Container-boundary validation.

routes/design.py

Method Path Handler Description
POST /api/projects/{slug}/design/brand-guide generate_brand_guide Kick off an agent run that synthesises a project's brand guideline into
POST /api/projects/{slug}/design/image design_image Generate (text→image) or edit (image+prompt→image) via the configured
GET /api/projects/{slug}/design/image-models design_image_models For the codex provider there's no static model list (login-based); for
GET /api/projects/{slug}/design/moodboard list_moodboard List this project's curated visual references.
POST /api/projects/{slug}/design/moodboard add_moodboard_item Add a URL preview or an already-uploaded screenshot to the Moodboard.
DELETE /api/projects/{slug}/design/moodboard/{item_id} remove_moodboard_item Delete a Moodboard card and its private cached/uploaded image.
PATCH /api/projects/{slug}/design/moodboard/{item_id} update_moodboard_item Edit a Moodboard note/tags or select it for design-run context.
POST /api/projects/{slug}/designs/from-image design_from_image Seed a new Design Studio scene containing an existing project image as a

routes/files.py

Method Path Handler Description
API_ROUTE /api/appview/{slug}/{path:path} app_view
GET /api/preview/{slug}/{file_path:path} project_preview
POST /api/projects/{slug}/app/start app_start
GET /api/projects/{slug}/app/status app_status
POST /api/projects/{slug}/app/stop app_stop
GET /api/projects/{slug}/apps detect_apps Scan the project for runnable apps so the user picks one instead of
GET /api/projects/{slug}/artifacts list_artifacts Typed artifacts recently produced in a project (design/app/page/doc/file) so
GET /api/projects/{slug}/file project_read_file
PUT /api/projects/{slug}/file project_write_file
DELETE /api/projects/{slug}/fs project_delete
POST /api/projects/{slug}/fs/mkdir project_mkdir
POST /api/projects/{slug}/fs/rename project_rename
POST /api/projects/{slug}/preview-mode project_preview_mode
GET /api/projects/{slug}/raw project_raw
GET /api/projects/{slug}/reference-files project_reference_files Safe, path-only project file index for @-reference autocomplete.
GET /api/projects/{slug}/tree project_tree
POST /api/projects/{slug}/upload project_upload
DELETE /api/sessions/{session_id}/artifacts delete_session_artifact
GET /api/sessions/{session_id}/artifacts session_artifacts Artifacts produced BY this session's runs (accumulated) — scopes the iterate
GET /api/settings/collaboration get_collaboration_settings
PUT /api/settings/collaboration set_collaboration_settings
GET /api/settings/higgsfield get_higgsfield_settings
PUT /api/settings/higgsfield put_higgsfield_settings
POST /api/settings/higgsfield/test test_higgsfield_settings
GET /api/settings/image-gen get_image_gen_settings The saved image-gen config + provider metadata + codex readiness.
PUT /api/settings/image-gen put_image_gen_settings Save the image-gen provider/model/key/baseUrl. An empty apiKey keeps the
POST /api/settings/image-gen/test test_image_gen Test a provider. Codex → OAuth login status; openai-compatible → endpoint probe.
GET /api/settings/permissions get_permission_settings Auto-approve toggle: when on, agent permission prompts are approved
PUT /api/settings/permissions set_permission_settings
GET /api/settings/runs get_run_settings Turn quota (T5): the per-turn run timeout as a first-class in-app
PUT /api/settings/runs set_run_settings
GET /api/settings/satpam get_satpam_settings Satpam supervision thresholds (slice 12, T10): N consecutive
PUT /api/settings/satpam set_satpam_settings
GET /api/settings/video-gen get_video_gen_settings The saved video-gen config + provider metadata (never the key itself).
PUT /api/settings/video-gen put_video_gen_settings Save the video-gen provider/model/key/baseUrl. An empty apiKey keeps the
POST /api/settings/video-gen/test test_video_gen Probe the configured video endpoint. Uses the submitted key/baseUrl
GET /api/target-preview/{slug}/{area_kind}/{area_id}/{file_path:path} project_target_preview

routes/graph.py

Method Path Handler Description
GET /api/graph/jobs list_graph_jobs
POST /api/graph/jobs create_graph_job
GET /api/graph/jobs/{job_id} get_graph_job
POST /api/graph/jobs/{job_id}/approve approve_graph_job
POST /api/graph/jobs/{job_id}/approve-plan approve_graph_plan The hash-bound plan approval (model 2): the owner approves EXACTLY
POST /api/graph/jobs/{job_id}/chat ensure_graph_job_chat The plan's chat thread, created and pinned if it is missing.
PATCH /api/graph/jobs/{job_id}/graph update_graph_definition
POST /api/graph/jobs/{job_id}/nodes/{node_id}/answer answer_node_decision Answer a decision-held node's question (slice 12, T10 #4). The node
POST /api/graph/jobs/{job_id}/nodes/{node_id}/approve approve_node
PATCH /api/graph/jobs/{job_id}/nodes/{node_id}/output edit_node_output
POST /api/graph/jobs/{job_id}/nodes/{node_id}/rerun rerun_node
POST /api/graph/jobs/{job_id}/save-template save_graph_template
POST /api/graph/jobs/{job_id}/start start_graph_job
GET /api/graph/templates list_graph_templates

routes/graphs.py

Method Path Handler Description
GET /api/containers/{slug}/graphs list_graph_states Read exact scoped graph freshness without exposing filesystem paths.
POST /api/containers/{slug}/graphs/rebuild rebuild_graph Run one bounded explicit build through the server-owned adapter.

routes/icm.py

Method Path Handler Description
GET /api/projects/{slug}/stages project_stages The project's ICM stages (NN-sorted) plus the active stage slug.
POST /api/projects/{slug}/stages project_stage_scaffold Scaffold stages/NN_/ (CONTEXT.md template + output/) and
PUT /api/projects/{slug}/stages/active project_stage_active The owner's stage boundary gate: set (or clear, with null) the

routes/master.py

Method Path Handler Description
GET /api/attention get_attention Ephemeral header notifications: unread only, newest first.
POST /api/attention/{item_id:path}/act act_attention
POST /api/attention/{item_id:path}/dismiss dismiss_attention Acknowledge a header item (#157).
GET /api/chat/messages/{message_id}/restore-turn preview_turn_restore
POST /api/chat/messages/{message_id}/restore-turn restore_chat_turn
GET /api/inbox get_inbox The Inbox destination: every notification, read and unread.
POST /api/inbox/client-error record_client_error Keep an error the owner saw in the browser after the toast is gone.
POST /api/inbox/read-all read_all_inbox Clear the unread badge without discarding a single notification.
POST /api/inbox/{item_id:path}/read set_inbox_read Mark one notification read or unread. The row itself never moves.
POST /api/jobs/{job_id}/checkpoint/restore restore_job_checkpoint
PUT /api/jobs/{job_id}/checkpoint/{checkpoint_id}/pin pin_job_checkpoint
GET /api/jobs/{job_id}/checkpoint/{checkpoint_id}/restore preview_checkpoint_restore
GET /api/jobs/{job_id}/checkpoints get_job_checkpoints
GET /api/master/decisions/{decision_id} get_master_decision
POST /api/master/decisions/{decision_id}/defer defer_master_decision
POST /api/master/decisions/{decision_id}/resolve resolve_master_decision
GET /api/master/desk get_master_desk
PUT /api/master/focus put_master_focus
POST /api/master/messages create_master_message
GET /api/settings/master get_master_settings
PUT /api/settings/master put_master_settings

routes/profiles.py

Method Path Handler Description
GET /api/commands/catalog commands_catalog Built-in Proxima commands plus enabled skills for the active profile
POST /api/commands/execute commands_execute
GET /api/profiles list_profiles
POST /api/profiles create_profile
DELETE /api/profiles/{profile_id} delete_profile
PATCH /api/profiles/{profile_id} update_profile
GET /api/runners/detect runners_detect
GET /api/runners/{runner_id}/capabilities runner_capabilities Skills + MCP servers detected on the host for this runner (portable —
POST /api/runners/{runner_id}/capabilities/rescan runner_capabilities_rescan Manual rescan: clear the skill/MCP detection cache and re-walk roots.
GET /api/settings/skill-roots get_skill_roots Global custom skill directories included in every runner's multi-root scan.
PUT /api/settings/skill-roots put_skill_roots Replace custom skill roots. Invalid paths are kept in the list but
GET /api/tools/recommended tools_recommended The capability bundle's recommended-tools list with a PATH-probe result

routes/projects.py

Method Path Handler Description
GET /api/fs/dirs fs_dirs Browse directories under the configured link roots, to pick an existing
GET /api/projects list_projects
POST /api/projects create_project
POST /api/projects/link link_project Register a folder as a project without writing anything into it
DELETE /api/projects/{slug} delete_project
GET /api/projects/{slug} get_project Return one owner-visible Project compatibility payload.
PATCH /api/projects/{slug} update_project
POST /api/projects/{slug}/activity-guardians/discard discard_stale_activity_guardians Owner-invoked recovery for the guardian-record deadlock (audit G1).
GET /api/projects/{slug}/areas list_project_areas The project's container areas: code areas (git-repo subfolders,
POST /api/projects/{slug}/areas add_project_area Manually register (or correct) a code area - T1's hybrid override.
POST /api/projects/{slug}/areas/detect detect_project_areas Re-run code-area auto-detection on demand. Only auto rows follow the
DELETE /api/projects/{slug}/areas/{area_id} remove_project_area Remove a code area. The row becomes an 'excluded' tombstone (not a
PATCH /api/projects/{slug}/areas/{area_id} update_project_area Per-area settings - today that is the T9 push-after-merge toggle
GET /api/projects/{slug}/layout get_project_layout The per-project layout map (prune C4): where this project keeps its
GET /api/projects/{slug}/location get_project_location Where this project's folder should be and whether it is there
PUT /api/projects/{slug}/memory-writes set_memory_writes The per-project memory-writes toggle (prune C5, decision #121):
GET /api/projects/{slug}/ops-migration get_ops_migration Inspect one Project's physical Ops migration without changing its files.
POST /api/projects/{slug}/ops-migration/retry retry_ops_migration Retry only a currently safe layout using the durable migration marker.
POST /api/projects/{slug}/ops-migration/validate validate_ops_migration Refresh the read-only collision and retry-safety projection.
POST /api/projects/{slug}/rebind rebind_project Re-pin a project to its folder's real location (prune C6, #141).

routes/reviews.py

Method Path Handler Description
POST /api/message-reviews/{review_id}/ask-original ask_original_to_revise
POST /api/message-reviews/{review_id}/replace-answer replace_answer_with_review
POST /api/message-reviews/{review_id}/restore-original restore_original_answer
POST /api/message-reviews/{review_id}/use-revised use_revised_review
GET /api/messages/{message_id}/reviews list_message_reviews
POST /api/messages/{message_id}/reviews create_message_review

routes/update.py

Method Path Handler Description
POST /api/update/apply update_apply
POST /api/update/check update_check
GET /api/update/status update_status

routes/wiki.py

Method Path Handler Description
GET /api/projects/{slug}/wiki/all project_wiki_all All notes in the project's wiki - resolved through the per-project
GET /api/wiki/all wiki_all
GET /api/wiki/file wiki_read_file
PUT /api/wiki/file wiki_write_file
DELETE /api/wiki/fs wiki_delete
POST /api/wiki/fs/mkdir wiki_mkdir
POST /api/wiki/fs/rename wiki_rename
GET /api/wiki/tree wiki_tree

routes/work.py

Method Path Handler Description
GET /api/jobs list_jobs
POST /api/jobs create_job
DELETE /api/jobs/{job_id} delete_job
GET /api/jobs/{job_id} get_job One job with its execution state (plus worktree state for repo jobs).
POST /api/jobs/{job_id}/approve approve_job
GET /api/jobs/{job_id}/diff get_job_diff The repo job's before/after change (worktree branch vs its base):
POST /api/jobs/{job_id}/link-run link_job_run Attach a project-scoped media run to a queued ad-hoc task.
POST /api/jobs/{job_id}/push push_job Retry (or run) the T9 push-after-merge for a merged repo job -
POST /api/jobs/{job_id}/reject reject_job The review surface's other door (slice 4, T1): rejecting a job at
POST /api/jobs/{job_id}/satpam/{intervention_id}/approve approve_satpam_restart Approve a satpam restart-clean of a REPO job (slice 12, T10 rung b):
POST /api/jobs/{job_id}/satpam/{intervention_id}/dismiss dismiss_satpam_restart Decline a pending satpam restart: the job keeps running as-is (the
POST /api/jobs/{job_id}/start start_job
GET /api/schedules list_schedules
POST /api/schedules create_schedule
DELETE /api/schedules/{schedule_id} delete_schedule
PATCH /api/schedules/{schedule_id} update_schedule
POST /api/schedules/{schedule_id}/run run_schedule Fire a schedule now, without waiting for its cron.
GET /api/workflows list_workflows
POST /api/workflows create_workflow
DELETE /api/workflows/{workflow_id} delete_workflow
GET /api/workflows/{workflow_id} get_workflow
PATCH /api/workflows/{workflow_id} update_workflow

main.py (app-level)

Method Path Handler Description
GET /api/config public_config
GET /api/health health
POST /api/preview-auth preview_auth

Generated 2026-08-19 17:24 UTC.