Eformogi Admin API

openapi: 3.2.0
info:
  title: Eformogi Admin API
  version: 33.5.1
  description: 'Eformogi is a record of learning the student owns, witnessed by the adults who were there, verifiable at one link with no login, and issued by the schools and counselors who hold the learners. The family-issued receipt (`tr_`) is a Witness Transcript. This document describes the machine-readable surface: verification, witness attestation, consent, the agent protocol, and the issuer rail (enrollment, roster, declared courses, and the family side that folds them into the transcript). The open record format itself is published at https://eformogi.com/spec.'
  contact:
    url: https://eformogi.com
  license:
    name: Proprietary
servers:
- url: https://eformogi.com
  description: Production
tags:
- name: Admin
  description: Admin dashboard and user management
paths:
  /api/admin-users:
    get:
      summary: Admin user management
      description: Paginated user list with vault/credential/share counts. Pass userId query param for single user detail. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      - name: userId
        in: query
        schema:
          type: string
        description: Get single user detail
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 50
      - name: search
        in: query
        schema:
          type: string
        description: Search by email or name
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - email
          - last_sign_in_at
      - name: order
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
      responses:
        '200':
          description: User list or single user detail
        '401':
          description: Admin authorization required
        '429':
          description: Rate limited (20/min)
      operationId: getApiAdminUsers
      x-operation-id-source: derived
  /api/admin-broadcast:
    get:
      summary: List recent broadcasts
      description: Returns deduplicated list of recent system-wide broadcast notifications. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of recent broadcasts with recipient counts
        '401':
          description: Admin authorization required
      operationId: getApiAdminBroadcast
      x-operation-id-source: derived
    post:
      summary: Send broadcast notification
      description: Sends a notification to all users. Batched in groups of 100. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                  maxLength: 200
                  description: Notification title
                body:
                  type: string
                  maxLength: 1000
                  description: Optional body text
                type:
                  type: string
                  enum:
                  - system
                  - account_update
                  default: system
      responses:
        '200':
          description: Broadcast sent with recipient count and broadcast ID
        '400':
          description: Invalid input
        '401':
          description: Admin authorization required
        '429':
          description: Rate limited (10/min)
      operationId: postApiAdminBroadcast
      x-operation-id-source: derived
  /api/admin-feature-flags:
    get:
      summary: List all feature flags
      description: Returns all feature flags with current values, defaults, override status, and descriptions. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of feature flags with enabled state and metadata
        '401':
          description: Admin authorization required
        '429':
          description: Rate limited (30/min)
      operationId: getApiAdminFeatureFlags
      x-operation-id-source: derived
    patch:
      summary: Toggle feature flags
      description: Update one or more feature flags. Values are persisted in the database and override defaults. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - flags
              properties:
                flags:
                  type: object
                  description: Map of flag names to boolean values
                  example:
                    FAMILY_VAULT_ADVANCED: true
                    CHAT_ACTIONS: false
      responses:
        '200':
          description: Flags updated successfully
        '207':
          description: 'Partial success: some flags updated, some failed'
        '400':
          description: Invalid input or unknown flag names
        '401':
          description: Admin authorization required
        '429':
          description: Rate limited (30/min)
      operationId: patchApiAdminFeatureFlags
      x-operation-id-source: derived
  /api/admin-error-logs:
    get:
      summary: View error logs
      description: Returns recent error reports from the error_logs table with filtering, pagination, and summary stats. Requires admin secret.
      tags:
      - Admin
      parameters:
      - name: x-admin-secret
        in: header
        required: true
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 25
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      - name: type
        in: query
        schema:
          type: string
          description: Filter by error_type
      - name: env
        in: query
        schema:
          type: string
          description: Filter by environment
      - name: search
        in: query
        schema:
          type: string
          description: Search in error message
      - name: hours
        in: query
        schema:
          type: integer
          description: Only errors from last N hours
      responses:
        '200':
          description: Error logs with summary stats, pagination, and type breakdown
        '401':
          description: Admin authorization required
        '429':
          description: Rate limited (20/min)
      operationId: getApiAdminErrorLogs
      x-operation-id-source: derived
  /api/feedback:
    get:
      summary: List feedback (admin)
      description: Returns submitted feedback with filtering and summary stats. Admin secret required.
      tags:
      - Admin
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - bug
          - feature
          - general
          - question
      - name: status
        in: query
        schema:
          type: string
          enum:
          - new
          - reviewed
          - resolved
          - archived
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Feedback list with summary stats
        '401':
          description: Admin authentication required
      operationId: getApiFeedback
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Supabase JWT access token
    orgApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Institutional org API key. Use "Bearer efg_org_..." or "Api-Key efg_org_..." header. Keys are scoped to specific data categories.