API Entry Points
API Entry Points by Use Case
Last updated: January 2026
This doc lists the main API entry points by use case so you can reach the right surface without scanning the full API reference. Base URL: local http://localhost:3001, production your backend URL (e.g. https://api.uniph.ai).
1. Orchestration & intent → outcome
Goal: Submit user intent, get outcomes, stream progress, act on results.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| One-shot ambient start | POST | /api/orchestrate/start | Body: { userMessage }. Headers: X-User-Email. Creates first outcome with minimal setup. |
| Submit intent (runtime) | POST | /api/runtime/intent | Body: { rawInput, email }. Returns outcome id + type. |
| List outcomes | GET | /api/runtime/outcomes | Query: limit, offset, status. Auth: X-User-Email. |
| Get outcome | GET | /api/runtime/outcomes/:id | Auth: X-User-Email. |
| Stream progress | GET | /api/runtime/outcomes/:id/progress | SSE. Query: email. |
| Outcome action | POST | /api/runtime/outcomes/:id/action | Body: { actionType, payload? }. |
| List/edit intents | GET / PATCH / DELETE | /api/runtime/intents, /api/runtime/intents/:id | Intent history. |
Frontend: Dashboard submit, outcome cards, /outcome/[id].
2. Goals & tasks (LifeOS)
Goal: Manage goals, categories, and tasks.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Categories | GET / POST | /api/goals/categories | List/create categories. |
| Goals (legacy) | GET / POST / PATCH / DELETE | /api/goals, /api/goals/:id | Auth: X-User-Email or session. |
| Goals (runtime) | GET / POST / PATCH / DELETE | /api/runtime/goals, /api/runtime/goals/:id | Same data; reorder, archive, tree. |
| Reorder / archive | POST | /api/runtime/goals/reorder, /api/runtime/goals/:id/archive | |
| Tasks | GET / POST / PATCH / DELETE | /api/tasks, /api/tasks/:id | Query: goalId, workspaceId, status. |
Frontend: /dashboard (runtime goals), /goals/[id] (legacy fetch + tasks).
3. Governance & approvals
Goal: Contracts, policies, approval requests, execution trace.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Contract version | GET | /api/contracts/version | Schema version. |
| Validate contracts | POST | /api/contracts/validate/outcome-spec, .../plan-graph, .../action-schema | |
| Compose contract | POST | /api/contracts/compose | Body: outcome + plan + actions. |
| Pending approvals | GET | /api/governance/approvals?status=pending | Auth: X-User-Email. |
| Decide approval | POST | /api/governance/approvals/:id/decision | Body: { decision: "approved" \| "rejected", decidedBy }. |
| Execution trace | GET | /api/execution/trace | Query: workspaceId. Deep audit. |
Frontend: Mission-control Approval Inbox, Release Guardrails, trace links.
4. Memory
Goal: Store and recall memory entries; compact, retain, purge.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| List memory | GET | /api/memory | Query: limit, offset, kind, q. Auth: X-User-Email. |
| Create memory | POST | /api/memory | Body: { key, content, kind, importance?, tags? }. |
| Get/update/delete entry | GET / PATCH / DELETE | /api/memory/:id | PATCH body: content, key, kind, tags, importance. |
| Recall | POST | /api/memory/recall | Body: { query, limit?, kinds? }. |
| Stats | GET | /api/memory/stats | Counts by kind. |
| Compact | POST | /api/memory/compact | Optional body params. |
| Retention | POST | /api/memory/retention | Optional body params. |
| Purge | POST | /api/memory/purge | Body: { confirmToken }. Destructive. |
Frontend: /settings/memory.
5. Agents & identity
Goal: Register agents, manage identities (OAuth), health, audits.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Register agent | POST | /api/agents/register | Returns apiKey once. |
| List agents | GET | /api/agents | |
| Create identity | POST | /api/agents/:id/identity | Body: provider, emailAlias?, scopes?. |
| List identities | GET | /api/agents/:id/identity | |
| Start connect (OAuth) | POST | /api/agents/:id/identity/:identityId/auth/connect | Returns connectUrl. User completes in browser. |
| Callback | GET | /api/agents/auth/callback/:provider | OAuth redirect; exchange code for tokens. |
| Refresh tokens | POST | /api/agents/:id/identity/:identityId/auth/refresh | Uses stored refresh_token. |
| Revoke identity | POST | /api/agents/:id/identity/:identityId/revoke | |
| Identity health | GET | /api/agents/:id/identity/health | Staleness, reconnect hint. |
| Audits | GET | /api/agents/:id/identity/audits | Query: identityId, limit. |
Frontend: /settings/agents. See Identity lifecycle for callback URLs and recovery.
6. Evaluation & improvement
Goal: Friction KPIs, release gates, improvement signals, mission-control data.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Health | GET | /api/health | db_configured, etc. |
| SLO | GET | /api/evaluation/slo | Run P95, job success rate. |
| Friction | GET | /api/evaluation/friction | Time-to-first-outcome, user actions, autonomous resolution. |
| Onboarding harness | GET | /api/evaluation/harness/onboarding-scenarios | Scenario pass rates. |
| Submit feedback signal | POST | /api/evaluation/signals | Body: category, severity, signalType, etc. |
| Signals summary | GET | /api/evaluation/signals/summary | Query: days. |
| Release gates | GET / POST | /api/evaluation/release-gates, /api/evaluation/release-gates/check | Snapshot + run check. |
| Improvement dashboard | GET | /api/evaluation/improve | Query: days. Regressions, experiments, credential friction. |
| Improvement runtime | GET | /api/evaluation/improvement-runtime | Pulse cadence, last run. |
Frontend: /mission-control.
7. Channels (inbound)
Goal: Receive events from Slack, Discord, email.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Slack events | POST | /api/slack/events | Slack event payload; verify with signing secret. |
| Discord interactions | POST | /api/discord/interactions | Slash commands, etc. |
| Email inbound | POST | /api/email/inbound | Inbound-to-task. |
8. Users & auth (app)
Goal: Sync user from OAuth, resolve current user.
| Purpose | Method | Path | Notes |
|--------|--------|------|--------|
| Sync user | POST | /api/users/sync | Body: email, name?, avatarUrl?, provider, providerAccountId. Called after sign-in. |
| Current user | GET | /api/users/me | Query: email (from session). |
9. Internal execution context (workspaces)
Goal: Low-level execution context, contributions, runs. Used by agents and trace; not primary user UI.
| Purpose | Method | Path |
|--------|--------|------|
| List/create workspaces | GET / POST | /api/workspaces, /api/workspaces/:id |
| Summary, questions, context | GET / PUT | /api/workspaces/:id/summary, .../questions, .../context |
| Contributions | GET | /api/workspaces/:id/contributions |
| Runs | GET / POST | /api/workspaces/:id/runs, /api/runs/:id |
See API.md for full workspace and contribution semantics.