# Admin BFF API Contract

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`
