UNIPH.AI
HomeAll docsOpen App

API Reference

Uniph.ai API Reference (Current)

Last updated: February 2026
Base URL (local): http://localhost:3001
Base URL (production): https://api.uniph.ai

This reference reflects currently mounted routes in backend/src/app.ts.

Conventions

  • Content type: JSON unless noted
  • User auth context is resolved by middleware (session / mapped user identity)
  • Agent auth: Authorization: Bearer <apiKey> or X-API-Key: <apiKey>
  • Common error shape: { "error": "..." } (sometimes includes code and details)

Health and Root

| Method | Path | Purpose | |---|---|---| | GET | / | API root payload | | GET | /api | API overview | | GET | /api/health | Health and DB-configured status |

Users

| Method | Path | Purpose | |---|---|---| | POST | /api/users/sync | Upsert user profile from provider data | | GET | /api/users/me | Resolve current user | | PATCH | /api/users/me/preferences | Update user preferences | | GET | /api/users/me/export | Export user data (goals, tasks, memory) as JSON (auth required) | | POST | /api/users/me/delete | Delete account and all data (auth required; body { confirm: "DELETE_ACCOUNT" }) |

Export and delete require auth. See PII policy for data scope.

Goals and Categories

| Method | Path | Purpose | |---|---|---| | GET | /api/goals/categories | List goal categories | | POST | /api/goals/categories | Create category | | GET | /api/goals | List goals for current user | | POST | /api/goals | Create goal and trigger planner/research | | GET | /api/goals/:id | Goal detail (tasks + internal execution contexts) | | PATCH | /api/goals/:id | Update goal | | DELETE | /api/goals/:id | Delete goal |

Tasks

| Method | Path | Purpose | |---|---|---| | GET | /api/tasks | List tasks (filters: goalId, workspaceId, status) | | POST | /api/tasks | Create task | | PATCH | /api/tasks/:id | Update task | | DELETE | /api/tasks/:id | Delete task |

Integrations

| Method | Path | Purpose | |---|---|---| | GET | /api/integrations | List current user integrations | | POST | /api/integrations | Connect or update integration | | DELETE | /api/integrations/:type | Remove integration type |

config is encrypted at rest.

Inference

| Method | Path | Purpose | |---|---|---| | POST | /api/infer/goals | Propose goals from context | | POST | /api/infer/chat | Assistant chat response |

/api/infer/chat reads recent memory for context when available.

Schedule and GitHub

| Method | Path | Purpose | |---|---|---| | GET | /api/schedule/context | Calendar context (Google/Microsoft) | | POST | /api/schedule/run | Trigger scheduler agent | | GET | /api/github/repos | List active GitHub repos | | POST | /api/github/sync | Sync repo issues/PRs into tasks |

Internal Execution Context (Workspace APIs)

| Method | Path | Purpose | |---|---|---| | POST | /api/workspaces | Create internal execution context | | GET | /api/workspaces | List internal execution contexts | | GET | /api/workspaces/:id | Get execution context + contributions | | GET | /api/workspaces/:id/spec | Adapter spec for agents | | GET | /api/workspaces/:id/contributions | Filter/sort/search contributions | | GET | /api/workspaces/:id/events | Poll event stream | | GET | /api/workspaces/:id/metrics | Internal collaboration metrics | | GET | /api/workspaces/:id/summary | Get pinned summary | | PUT | /api/workspaces/:id/summary | Update pinned summary | | GET | /api/workspaces/:id/questions | Get open questions | | PUT | /api/workspaces/:id/questions | Update open questions | | GET | /api/workspaces/:id/context | Get uploaded context | | PUT | /api/workspaces/:id/context | Update uploaded context | | GET | /api/workspaces/:id/outcome | Get outcome fields | | PUT | /api/workspaces/:id/outcome | Update outcome fields | | GET | /api/workspaces/:id/runs | List execution runs | | POST | /api/workspaces/:id/runs | Create execution run | | GET | /api/workspaces/:id/agents | List context agent permissions | | POST | /api/workspaces/:id/agents | Upsert context agent permissions | | GET | /api/workspaces/:id/export | Export context + contributions |

Important query params:

  • /contributions: intent, tags, sort=chronological|relevance, q, responds_to, supports
  • /events: since, tags, limit (1..200)
  • /runs: status, limit

Contributions

| Method | Path | Purpose | |---|---|---| | POST | /api/contributions | Create contribution | | GET | /api/contributions/:id | Get contribution |

Minimum body:

{
  "workspace_id": "ws_123",
  "payload": { "message": "hello" }
}

Optional fields: agent_id, content, intent, tags, provenance, responds_to.

Event behavior:

  • Always emits contribution.created
  • Emits contribution.deferred when intent === "defer" or payload includes defers_to

Agents

| Method | Path | Purpose | |---|---|---| | POST | /api/agents/register | Register agent and return apiKey once | | GET | /api/agents | List agents | | GET | /api/agents/me | Resolve agent from API key | | GET | /api/agents/:id | Get agent profile | | PATCH | /api/agents/:id | Update metadata and optionally rotate key |

Agent identity routes

| Method | Path | Purpose | |---|---|---| | POST | /api/agents/:id/identity | Create identity (provider, emailAlias, scopes) | | GET | /api/agents/:id/identity | List identities for agent | | PATCH | /api/agents/:id/identity/:identityId | Update status/scopes/display name | | POST | /api/agents/:id/identity/:identityId/auth/connect | Start connect flow (returns connectUrl) | | GET | /api/agents/auth/callback/:provider | Complete callback flow | | POST | /api/agents/:id/identity/:identityId/revoke | Revoke identity | | GET | /api/agents/:id/identity/audits | List identity audits (identityId, limit) |

Runs

| Method | Path | Purpose | |---|---|---| | GET | /api/runs/:id | Get run by id | | PATCH | /api/runs/:id | Update run status/timestamps |

Transition to in_progress emits run.started.

Contracts

| Method | Path | Purpose | |---|---|---| | GET | /api/contracts/version | Current contract schema version | | POST | /api/contracts/validate/outcome-spec | Validate outcome contract | | POST | /api/contracts/validate/plan-graph | Validate plan graph contract | | POST | /api/contracts/validate/action-schema | Validate action schema | | POST | /api/contracts/compose | Compose starter outcome + plan graph |

Governance

| Method | Path | Purpose | |---|---|---| | GET | /api/governance/policies | List active policies (user + global) | | POST | /api/governance/policies | Create policy | | POST | /api/governance/evaluate | Evaluate action against policy | | GET | /api/governance/approvals | List approvals (status filter) | | POST | /api/governance/approvals/:id/decision | Approve/reject request |

Execution

| Method | Path | Purpose | |---|---|---| | POST | /api/execution/jobs | Enqueue action job | | GET | /api/execution/jobs | List jobs (workspaceId optional; internal context id) | | POST | /api/execution/jobs/:id/retry | Requeue failed/queued job | | GET | /api/execution/trace | Get jobs/verifications/ledger for context (workspaceId required) |

Evaluation

| Method | Path | Purpose | |---|---|---| | GET | /api/evaluation/slo | Run and job SLO metrics | | POST | /api/evaluation/checkpoints | Create evaluation checkpoint | | GET | /api/evaluation/checkpoints/latest | Latest checkpoints | | POST | /api/evaluation/harness/model-router | Model-router sample harness | | GET | /api/evaluation/memory-maintenance | Memory maintenance status | | GET | /api/evaluation/friction | Friction-first KPI report | | GET | /api/evaluation/harness/onboarding-scenarios | Onboarding scenario rates |

Memory

All memory routes require user auth context.

| Method | Path | Purpose | |---|---|---| | GET | /api/memory | List memories (workspaceId internal context id, agentId, kind, q, limit) | | POST | /api/memory | Create memory entry | | PATCH | /api/memory/:id | Update entry (body: content, key, kind, tags, importance) | | POST | /api/memory/recall | Ranked recall by query/context | | GET | /api/memory/stats | Total + by-kind counts | | POST | /api/memory/compact | Compact old/overlapping entries | | DELETE | /api/memory/:id | Delete one entry (confirmation policy may apply) | | POST | /api/memory/purge | Bulk delete by filters | | POST | /api/memory/retention | Apply retention policy (dryRun supported) |

Destructive routes may require confirm token depending on env policy.

Orchestration

| Method | Path | Purpose | |---|---|---| | POST | /api/orchestrate/start | Friction-first ambient start flow |

Returns orchestration result plus friction telemetry.

V2 Dashboard and Automation APIs

These routes power the modern dashboard runtime, autonomous goal routing, and workflow/webhook integration.

Intent and Intent History

| Method | Path | Purpose | |---|---|---| | POST | /api/runtime/intent | Submit intent and trigger outcome flow | | GET | /api/runtime/intents | List intents with linked outcome summary | | PATCH | /api/runtime/intents/:id | Update intent fields (rawInput, feedback, successful) | | DELETE | /api/runtime/intents/:id | Delete intent (?deleteOutcome=true to remove linked outcome too) |

Outcomes

| Method | Path | Purpose | |---|---|---| | GET | /api/runtime/outcomes | List outcomes | | GET | /api/runtime/outcomes/:id | Outcome detail | | GET | /api/runtime/outcomes/:id/progress | SSE progress stream (includes stuck-warning events) | | POST | /api/runtime/outcomes/:id/action | Trigger outcome action (download, share, approve, retry) |

Goals, Suggestions, and Input Requests

| Method | Path | Purpose | |---|---|---| | GET | /api/runtime/goals | List goals | | POST | /api/runtime/goals | Create goal and kickoff execution-path selection | | PATCH | /api/runtime/goals/:id | Update goal | | DELETE | /api/runtime/goals/:id | Delete goal | | POST | /api/runtime/goals/reorder | Reorder goals | | POST | /api/runtime/goals/:id/archive | Archive/unarchive goal | | GET | /api/runtime/suggestions | Fetch grouped suggestions | | POST | /api/runtime/suggestions/:id/dismiss | Dismiss suggestion | | POST | /api/runtime/suggestions/:id/interact | Track suggestion interaction | | GET | /api/runtime/user-input-requests | List pending clarification requests | | POST | /api/runtime/user-input-requests/:id/respond | Submit/dismiss user clarification |

Workflows and Webhooks

| Method | Path | Purpose | |---|---|---| | GET | /api/runtime/workflows | List workflow templates/executions | | GET | /api/runtime/workflows/types | Workflow types and capability metadata | | GET | /api/runtime/workflows/:id | Workflow template detail | | POST | /api/runtime/workflows/:id/execute | Execute specific workflow template | | POST | /api/runtime/workflows/execute | Execute by payload/type | | GET | /api/runtime/workflows/executions/list | List recent executions | | POST | /api/runtime/webhooks/n8n/trigger | Trigger execution from n8n side | | POST | /api/runtime/webhooks/n8n/progress | n8n progress callback | | POST | /api/runtime/webhooks/n8n/complete | n8n completion callback | | POST | /api/runtime/webhooks/n8n/error | n8n failure callback | | GET | /api/runtime/webhooks/n8n/config | n8n webhook config details | | GET | /api/runtime/webhooks/n8n/executions/:id | n8n execution lookup |

Channel adapters

Slack

| Method | Path | Purpose | |---|---|---| | POST | /api/slack/events | Slack events webhook |

Discord

| Method | Path | Purpose | |---|---|---| | POST | /api/discord/interactions | Discord interactions endpoint |

Email

| Method | Path | Purpose | |---|---|---| | POST | /api/email/inbound | Inbound email to task | | POST | /api/email/digest | Trigger digest send |