Skip to main content

​
Base URLs

  • Backend: http://localhost:8000
  • API base: http://localhost:8000/api
  • OpenAPI: http://localhost:8000/docs

​
Protocols

  1. REST/JSON for most endpoints
  2. WebSocket for /api/ingest/ws/{job_id}
  3. SSE for POST /api/chat/stream

​
Contract Conventions

  • Request schemas are strict for most write endpoints.
  • Provenance fields are explicit in chat responses.
  • X-Response-Time is returned for latency observability.
  • Rate limiting can return 429 with Retry-After.

​
Primary Endpoint Families

  • /api/ingest*: ingestion, progress, screenshots, and page title
  • /api/library*: source inventory and lifecycle
  • /api/career*: taxonomy, scoring, recommendations
  • /api/projects*: project ideation and tracking
  • /api/social*: social OAuth connect/disconnect and direct publishing
  • /api/network-ops*: LinkedIn network snapshot persistence and KPI deltas
  • /api/chat*: chat and streaming
  • /api/conversations*: conversation history and updates
  • /api/feedback*: quality and review signals
  • /api/evals*: evaluation runs and comparisons
GET /api/library/sources includes a metrics block with filtered-vs-total counts for sources, chunks, tools, and concepts in the current query scope. YouTube SourceItem responses also include a description field sourced from ingest metadata and exposed on both list and detail endpoints. GET /api/career/composites returns composite readiness_pct (coverage-based activation/sorting) and confidence_pct (evidence-depth signal), with score_pct retained as a readiness alias for compatibility.

​
Services Surface Endpoint Map

The /monitor UI surface depends on these endpoint groups:
Services areaEndpoints
Health/health, /health?deep=true
Provider/runtime status/api/stats/providers, /api/stats/slo
Cost/usage telemetry/api/stats/costs
Eval runs and comparisons/api/evals/runs, /api/evals/runs/{run_id}, /api/evals/compare
Databases topologylocal store paths (data/*.db, data/chroma/) + architecture/data-store docs (no dedicated API endpoint)
Exploration queuelocal curated monitor content for not-yet-tried external tools (no dedicated API endpoint)
Tracing status (integration-level)runtime tracing integrations + stats endpoints
LinkedIn network KPI card/api/network-ops/linkedin/summary

​
Provenance Contract (Chat)

Client-facing provenance fields:
  • sources
  • answer_origin (values: library_rag, web_rag, general, policy, skill)
  • provenance_note
  • optional suggested_sources
  • optional model_name
  • optional provider
Render suggested_sources as discovery suggestions, not as grounded citations.

​
Provenance Contract (Other Surfaces)

  • Signal policy endpoint GET /api/ingest/policy returns structured accept/reject criteria, threshold, model, career goal context, and aggregate stats. Source of truth: backend/services/ingest/policy.py.
  • Ingest activity relevance entries can include optional relevance.model_name.
  • Ingest traceability endpoint GET /api/ingest/{job_id}/trace includes pipeline events (step, version, duration, model when present).
  • Ingest traceability endpoint GET /api/ingest/{job_id}/trace includes extracted skills (summary, concepts, tools, matched canonical skills).
  • Ingest traceability endpoint GET /api/ingest/{job_id}/trace includes superpowers impact preview (meta-skill/composite deltas).
  • Ingest traceability endpoint GET /api/ingest/{job_id}/trace includes patterns impact preview (before/after pattern deltas).
  • Projects list/detail entries can include optional model_name for generated/extracted records.
  • Career transparency endpoint GET /api/career/skill-provenance returns per-skill declared source, learnings hit counts, and extraction model summary for UI hover details.