Portal facade

API index•/api/portal

Browser-facing proxy routes used by the dashboard, onboarding flow, and UI state.

Use this if you are extending the portal itself or want to understand the browser-facing API surface.

Endpoints

Service surface

GET

/api/portal/dashboard

Aggregates dashboard metrics and onboarding state.

Portal session

Dashboard

Pull the dashboard summary used by the portal home screen.

curl -H "X-Tenant-ID: <tenant-id>" \
  "http://localhost:3000/api/portal/dashboard"

GET

/api/portal/onboarding

Returns the onboarding checklist state.

Portal session

Onboarding status

Check the onboarding completion state.

curl -H "X-Tenant-ID: <tenant-id>" \
  "http://localhost:3000/api/portal/onboarding"

POST

/api/portal/onboarding/complete

Marks an onboarding step complete.

Portal session

Complete onboarding step

Mark one step at a time.

curl -X POST "http://localhost:3000/api/portal/onboarding/complete" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{ "step": "created_api_key" }'

GET

/api/portal/credentials

Lists API credentials for the current user and tenant.

Portal session + CSRF for state-changing calls

List credentials

Load the browser-facing credential list.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "X-User-ID: <user-id>" \
  "http://localhost:3000/api/portal/credentials"

POST

/api/portal/credentials

Creates a new credential with scoped access.

Portal session + CSRF

Create credential

Create a credential from the portal UI.

curl -X POST "http://localhost:3000/api/portal/credentials" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "X-User-ID: <user-id>" \
  -H "X-CSRF-Token: <csrf-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Portal key",
    "scopes": ["memories:read"]
  }'

GET

/api/portal/memories

Proxies the memory list view used by the portal UI.

Portal session

List memories

Portal proxy for the memory browser.

curl -H "X-Tenant-ID: <tenant-id>" \
  "http://localhost:3000/api/portal/memories?q=context&limit=50&offset=0"

GET

/api/portal/audit

Returns tenant audit events for the portal audit page.

Portal session

Audit logs

Portal audit view backend call.

curl -H "X-Tenant-ID: <tenant-id>" \
  "http://localhost:3000/api/portal/audit?limit=50&offset=0"

POST

/api/portal/step-up

Issues a step-up token for sensitive operations (e.g., data export, deletion).

Portal session

Step-up token

Request elevated authentication before privileged actions.

curl -X POST "http://localhost:3000/api/portal/step-up" \
  -H "X-Tenant-ID: <tenant-id>" \
  -H "X-User-ID: <user-id>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "data.export" }'

Request example

Fetch dashboard data

The portal uses browser-session-backed requests to populate the dashboard.

curl -H "X-Tenant-ID: <tenant-id>" \
  -H "X-User-ID: <user-id>" \
  "http://localhost:3000/api/portal/dashboard"

Base path

/api/portal

Schemas

OpenAPI-style field tables

Dashboard response

Portal dashboard shape used by the overview screen.

Field	Type	Required	Description
total_memories	number	required	Memory count.
writes_this_period	number	required	Write usage in the current period.
quota_status	object	required	Quota totals and utilization.
onboarding_status	object	required	Onboarding progress.

Onboarding response

Checklist used by the portal to drive setup completion.

Field	Type	Required	Description
created_api_key	boolean	required	API key created.
sent_first_memory	boolean	required	First memory written.
ran_first_search	boolean	required	First search completed.

Step-up request

Payload for POST /api/portal/step-up.

Field	Type	Required	Description
action	string	required	The sensitive action requiring step-up (e.g., 'data.export', 'data.delete', 'retention.override').

Step-up response

Response from step-up request.

Field	Type	Required	Description
step_up_token	string	required	The step-up token to include in subsequent privileged requests.
expires_in	number	required	Token validity duration in seconds.

Response examples

What the API returns

Dashboard response

Dashboard data merges usage, audit, and onboarding state.

{
  "total_memories": 12847,
  "writes_this_period": 234,
  "reads_this_period": 890,
  "storage_used": 10485760,
  "current_plan": "free",
  "quota_status": {
    "used_percentage": 10,
    "writes_used": 234,
    "writes_limit": 1000,
    "reads_used": 890,
    "reads_limit": 5000,
    "storage_used_bytes": 10485760,
    "storage_limit_bytes": 104857600
  },
  "recent_audit_events": [],
  "onboarding_status": {
    "created_api_key": true,
    "sent_first_memory": true,
    "ran_first_search": false,
    "completed_at": null
  }
}

Onboarding response

Onboarding tracks the three product-activation milestones.

{
  "created_api_key": true,
  "sent_first_memory": false,
  "ran_first_search": false,
  "completed_at": null
}

Memory list response

Portal memory responses are a presentation-friendly projection of the memory API.

{
  "memories": [
    {
      "id": "b0c6d5d9-4b0c-4ebd-bb6c-29cbdb4d7a10",
      "type": "episodic",
      "created_at": "2026-04-10T12:00:00Z",
      "updated_at": "2026-04-10T12:05:00Z",
      "sensitivity": "low",
      "status": "active",
      "contradiction": "clear",
      "title": "Launch notes",
      "tags": ["release", "product"]
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Notes

Implementation notes

Portal routes proxy the backend services instead of exposing the raw integration surface directly.
The UI uses these routes for dashboard, audit, usage, onboarding, and memory views.
The portal API shapes are defined in portal/src/lib/api.ts and portal/src/app/api/portal/*.