Clarity Mini Apps Admin API

openapi: 3.2.0
info:
  title: Fast Mini Apps Admin API
  version: 0.1.0
tags:
- name: mini_apps_admin
paths:
  /api/v1/admin/projects/{project_id}/mini-apps:
    get:
      tags:
      - mini_apps_admin
      summary: List Mini Apps
      description: 'The project''s mini-apps, newest first, each with its shareable ``url``. ``source`` says

        where the LIVE version''s bytes are — ``''html''`` (markup published through this API) or

        ``''copilot''`` (a conversation''s figure) — and either kind takes a new version through

        ``PUT``.'
      operationId: list_mini_apps_api_v1_admin_projects__project_id__mini_apps_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - mini_apps_admin
      summary: Create Mini App
      description: 'Publish a mini-app from raw HTML; the response''s ``url`` is the shareable link.


        The server wraps the markup in the shared figure shell (CSP deny-all network, design

        tokens, resize bridge and the ``window.voc.*`` SDK — every mini-app is live). Content

        rules are enforced with actionable 400s (size cap, credentials scan, navigation lint)

        — fix the markup and retry, exactly like copilot''s ``update_canvas`` loop.'
      operationId: create_mini_app_api_v1_admin_projects__project_id__mini_apps_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateMiniAppRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/mini-apps/{slug}:
    get:
      tags:
      - mini_apps_admin
      summary: Get Mini App
      description: One mini-app with a fresh signed ``render_url`` (admin preview / verification).
      operationId: get_mini_app_api_v1_admin_projects__project_id__mini_apps__slug__get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppRenderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - mini_apps_admin
      summary: Update Mini App
      description: 'Partial update. New ``html`` re-validates, re-wraps and bumps ``version`` — the link

        is unchanged, so everyone holding it gets the fix on their next open. It publishes over

        any app, one built in the copilot included: start from ``GET /{slug}/source``, which

        serves the live markup whichever way it was published.


        Pass the ``version`` that ``/source`` returned as ``base_version``. If another version has

        gone live since, the publish is a 409 naming the live one, and nothing changes: fetch that

        version''s source, reapply the change on top of it, and retry with its number.


        New ``html`` also appends a row to the app''s history, so the previous version stays

        restorable — pass a one-line ``note`` saying what changed, or the entry records the

        default "Published via API". A name/caption-only edit is not a publish and adds no

        history entry.'
      operationId: update_mini_app_api_v1_admin_projects__project_id__mini_apps__slug__put
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateMiniAppRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - mini_apps_admin
      summary: Delete Mini App
      description: 'Unpublish: the link 404s from here on. Soft — the row and the bytes are kept, so an

        accidental removal is recoverable by an admin.'
      operationId: delete_mini_app_api_v1_admin_projects__project_id__mini_apps__slug__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/mini-apps/{slug}/versions:
    get:
      tags:
      - mini_apps_admin
      summary: List Mini App Versions
      description: 'The app''s publish history, newest first, with ``live_version`` alongside.


        Metadata only — no bytes and no signed URLs (fetching every version''s document to list

        them would be absurd); ``GET /{slug}/versions/{n}`` mints those for one version.


        The ``sha256`` of the live version is the cheap way to check nobody has published over

        your copy: compare it with the hash of your local source BEFORE sending a ``PUT``.'
      operationId: list_mini_app_versions_api_v1_admin_projects__project_id__mini_apps__slug__versions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppVersionListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/mini-apps/{slug}/versions/{version}:
    get:
      tags:
      - mini_apps_admin
      summary: Get Mini App Version
      description: 'One version, with a fresh signed ``render_url`` for the document it made live — look

        at a version before rolling back to it.


        ``source_url`` is the RAW author markup the version kept, present only when

        ``has_source``: versions published before the history existed kept none, and a copilot

        version''s markup lives in its figure. ``GET /{slug}/source?v=N`` recovers it for both.'
      operationId: get_mini_app_version_api_v1_admin_projects__project_id__mini_apps__slug__versions__version__get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppVersionDetailResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/mini-apps/{slug}/source:
    get:
      tags:
      - mini_apps_admin
      summary: Get Mini App Source
      description: 'The RAW author markup of the live app, or of version ``v``, as a short-lived signed

        ``text/plain`` URL — where an edit starts. Download it, change it, and publish it with

        ``PUT /{slug}`` passing the response''s ``version`` as ``base_version``.


        Every version has one, whichever way it was published: an API version kept its source,

        and a copilot figure''s is peeled off its wrapped document (and kept) on the first read —

        the same answer the copilot gets on the app page. Signed as ``text/plain`` on purpose:

        the bytes are unwrapped, so they are for editing, never for rendering or for a human.


        An unknown slug or version is the uniform 404; a document the shell cannot be peeled off

        is a 400 with the reason, never an approximate source.'
      operationId: get_mini_app_source_api_v1_admin_projects__project_id__mini_apps__slug__source_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      - name: v
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: This version's source instead of the live one
          title: V
        description: This version's source instead of the live one
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppSourceResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/admin/projects/{project_id}/mini-apps/{slug}/rollback:
    post:
      tags:
      - mini_apps_admin
      summary: Rollback Mini App
      description: 'Restore a past version as the app''s NEXT version — the link never changes, and the

        history keeps growing forwards.


        ``rewrapped`` tells you which restore happened: true when the target''s stored raw

        source was re-validated and re-wrapped with the CURRENT shell, false when the target

        had no stored source (pre-history or copilot) and the new version simply re-points at

        the document that version was serving — still correct, but wrapped by the shell of its

        day. Rolling back onto the version that is already live is a 400, and an unknown

        version is the same uniform 404 an unknown slug gets.'
      operationId: rollback_mini_app_api_v1_admin_projects__project_id__mini_apps__slug__rollback_post
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
          title: Project Id
      - name: slug
        in: path
        required: true
        schema:
          type: string
          title: Slug
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MiniAppRollbackRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MiniAppRollbackResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    MiniAppRollbackResponse:
      properties:
        slug:
          type: string
          title: Slug
        url:
          type: string
          title: Url
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
        source:
          type: string
          title: Source
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
        version:
          type: integer
          title: Version
        live_version:
          type: integer
          title: Live Version
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
        wrapper_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Wrapper Version
        created_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        rewrapped:
          type: boolean
          title: Rewrapped
      type: object
      required:
      - slug
      - url
      - source
      - version
      - live_version
      - created_at
      - updated_at
      - rewrapped
      title: MiniAppRollbackResponse
      description: 'The app after a rollback — already pointing at the NEW version.


        ``rewrapped`` says which of the two restores happened: true when the target''s raw

        source was re-validated and re-wrapped with the CURRENT shell (a real re-publish),

        false when it had no stored source and the new version simply re-points at the document

        the target was serving.'
    AdminUpdateMiniAppRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
        caption:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Caption
        html:
          anyOf:
          - type: string
          - type: 'null'
          title: Html
        note:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Note
          description: One-line release note recorded against the new version; defaults to 'Published via API'
        base_version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Base Version
          description: The version this html was built on (the `version` GET /source returned). If another version has gone live since, the publish is refused with a 409. Ignored without html.
      type: object
      title: AdminUpdateMiniAppRequest
      description: 'Partial update. New ``html`` re-validates, re-wraps and bumps ``version`` — the

        shared link is unchanged, so everyone holding it sees the fix on their next open. It

        publishes over any app, one built in the copilot included; the version it replaces stays

        in the history.


        Pass ``base_version`` with ``html``: a publish built on a version that is no longer live is

        refused with a 409 naming the live one, instead of silently replacing it.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    MiniAppSourceResponse:
      properties:
        slug:
          type: string
          title: Slug
        version:
          type: integer
          title: Version
        source_url:
          type: string
          title: Source Url
      type: object
      required:
      - slug
      - version
      - source_url
      title: MiniAppSourceResponse
      description: 'The RAW author markup of the live app, or of one version, as a short-lived signed

        ``text/plain`` URL — what the copilot downloads into its sandbox, and an API caller to its

        disk, to read or edit the app. Fetch it when needed, never persist it.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MiniAppVersionListResponse:
      properties:
        slug:
          type: string
          title: Slug
        live_version:
          type: integer
          title: Live Version
        versions:
          items:
            $ref: '#/components/schemas/MiniAppVersionEntry'
          type: array
          title: Versions
      type: object
      required:
      - slug
      - live_version
      - versions
      title: MiniAppVersionListResponse
      description: The app's history, newest first. No pagination — one row per publish stays small.
    MiniAppRenderResponse:
      properties:
        slug:
          type: string
          title: Slug
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
        version:
          type: integer
          title: Version
        live_version:
          type: integer
          title: Live Version
        render_url:
          type: string
          title: Render Url
        is_favorite:
          type: boolean
          title: Is Favorite
          default: false
        needs_thumbnail:
          type: boolean
          title: Needs Thumbnail
          default: false
      type: object
      required:
      - slug
      - version
      - live_version
      - render_url
      title: MiniAppRenderResponse
      description: 'A published mini-app: a fresh signed render URL plus its display meta. Served to any

        user authorized on the project; the figure''s live data still self-fetches under the

        viewer''s own auth. ``render_url`` is short-lived — fetch per mount, never persist it.'
    MiniAppResponse:
      properties:
        slug:
          type: string
          title: Slug
        url:
          type: string
          title: Url
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
        source:
          type: string
          title: Source
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
        version:
          type: integer
          title: Version
        live_version:
          type: integer
          title: Live Version
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
        wrapper_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Wrapper Version
        created_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - slug
      - url
      - source
      - version
      - live_version
      - created_at
      - updated_at
      title: MiniAppResponse
      description: 'A mini-app as the admin contour sees it: identity, provenance and the shareable

        ``url`` to hand to a human.'
    MiniAppVersionEntry:
      properties:
        version:
          type: integer
          title: Version
        source:
          type: string
          title: Source
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
        wrapper_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Wrapper Version
        has_source:
          type: boolean
          title: Has Source
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
        restored_from:
          anyOf:
          - type: integer
          - type: 'null'
          title: Restored From
        created_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - version
      - source
      - has_source
      - created_at
      title: MiniAppVersionEntry
      description: 'One entry in a mini-app''s publish history. Metadata only — never bytes: the list is

        a timeline, and fetching a version''s document is a separate, signed read.'
    MiniAppListResponse:
      properties:
        apps:
          items:
            $ref: '#/components/schemas/MiniAppResponse'
          type: array
          title: Apps
      type: object
      required:
      - apps
      title: MiniAppListResponse
    MiniAppVersionDetailResponse:
      properties:
        version:
          type: integer
          title: Version
        source:
          type: string
          title: Source
        artifact_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Artifact Id
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
        wrapper_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Wrapper Version
        has_source:
          type: boolean
          title: Has Source
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
        restored_from:
          anyOf:
          - type: integer
          - type: 'null'
          title: Restored From
        created_by:
          anyOf:
          - type: integer
          - type: 'null'
          title: Created By
        created_at:
          type: string
          format: date-time
          title: Created At
        render_url:
          type: string
          title: Render Url
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
      type: object
      required:
      - version
      - source
      - has_source
      - created_at
      - render_url
      title: MiniAppVersionDetailResponse
      description: 'One version with a fresh signed URL for the document it made live, so an admin can

        look at a version before deciding to roll back to it. ``source_url`` is the RAW author

        markup and is present only when ``has_source``; ``GET /{slug}/source?v=N`` recovers the

        markup of every version, copilot ones included.'
    AdminCreateMiniAppRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
          description: Shown in the app's top bar and gallery
        caption:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Caption
          description: Provenance line under the figure
        html:
          type: string
          title: Html
          description: Raw figure HTML; wrapped server-side (never pre-wrap it)
        user:
          anyOf:
          - type: string
          - type: 'null'
          title: User
          description: Owner's email for audit (`created_by`), same contract as report creation; 404 when unknown
        file_name:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: File Name
          description: S3 object name; default app.html
      type: object
      required:
      - html
      title: AdminCreateMiniAppRequest
      description: 'Publish a mini-app from raw HTML (admin contour).


        ``html`` is the RAW figure markup — the server wraps it in the shared figure shell

        (CSP deny-all network, design tokens, resize bridge and the ``window.voc.*`` SDK), so

        never pre-wrap it. The authoring contract (limits, the ``voc.*`` method list, the D3

        asset rule) is the same as the copilot canvas figure and widget-catalog contract: one

        shell, one set of rules.'
    MiniAppRollbackRequest:
      properties:
        to_version:
          type: integer
          minimum: 1.0
          title: To Version
          description: The version to restore; 400 when it is already live
        note:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Note
          description: Release note for the new version; defaults to 'Rolled back to vN'
      type: object
      required:
      - to_version
      title: MiniAppRollbackRequest
      description: 'Restore a past version. This is a PUBLISH, not an edit: the target''s content becomes

        the app''s NEXT version, so the history stays an append-only account of what the link

        served and the numbers a human already saw keep their meaning.'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic