Eve library

Admin BFF API Contract

Guide

Revision 1

On this page

Admin-facing OSHUN BFF contract for Studio workspaces.

Base Contract#

  • Base URL: http://localhost:4010 in development or NEXT_PUBLIC_OSHUN_BFF_URL
  • Canonical paths are available at /admin/* with compatibility aliases at /v1/admin/*
  • Protected routes require Authorization: Bearer <token>
  • Admin routes require one of:
    • admin:*
    • admin:studio
    • admin:workspace:{workspaceId}
  • Workspace GET routes return short-lived private cache headers and x-oshun-cache: hit|miss

Shared Envelope#

All admin workspace routes share:

  • generatedAt: server timestamp for the payload
  • userId: authenticated admin operator id
  • revision: per-user admin workspace revision counter

Workspace summaries additionally expose:

  • workspaceId
  • title
  • description
  • ownerTeam
  • status as healthy | attention | degraded | blocked
  • summary.openItems
  • summary.urgentItems
  • summary.slaStatus
  • launch.targetPath
  • launch.shellPath

Workspace Index#

GET /admin/workspaces#

Lists the current admin workspace index for:

  • review
  • moderation
  • support
  • privacy
  • persona
  • model
  • rights
  • incident
  • policy
  • analytics

Workspace Detail#

GET /admin/workspaces/:workspaceId#

Returns one workspace-specific envelope:

  • review: queue, reviewers, metrics
  • moderation: queues, recentSimulations, metrics
  • support: cases, metrics
  • privacy: requests, metrics
  • persona: personas, metrics
  • model: models, metrics
  • rights: requests, metrics
  • incident: incidents, metrics
  • policy: policies, metrics
  • analytics: reports, metrics

Mutations#

Review#

  • POST /admin/review/items/:reviewId/assign
    • body: reviewerId
  • POST /admin/review/items/:reviewId/decision
    • body: decision=approved|rejected|changes_requested

Moderation#

  • POST /admin/moderation/queues/:queueId/simulations
    • body: policyId, sampleSize

Support#

  • POST /admin/support/cases/:caseId/escalate
    • body: targetTeam

Privacy#

  • POST /admin/privacy/requests/:requestId/resolve
    • body: resolution=completed|denied

Persona#

  • POST /admin/personas/:personaId/publish
    • body: releaseChannel=preview|staging|production
    • optional body: version

Model#

  • POST /admin/models/:modelId/promote
    • body: releaseChannel=staging|production

Rights#

  • POST /admin/rights/requests/:requestId/resolve
    • body: resolution=fulfilled|denied

Incident#

  • POST /admin/incidents/:incidentId/mitigate
    • optional body: commanderId

Policy#

  • POST /admin/policies/:policyId/publish

Analytics#

  • POST /admin/analytics/reports
    • body: metricGroup=review|moderation|privacy|model|incident
    • body: title