# 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](API.md). 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](IDENTITY_LIFECYCLE.md) 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](API.md) for full workspace and contribution semantics.