Clarity Routines Admin API

openapi: 3.2.0
info:
  title: Fast Routines Admin API
  version: 0.1.0
tags:
- name: routines_admin
paths:
  /api/admin/v1/routines/execute:
    post:
      tags:
      - routines_admin
      summary: Execute Routine
      description: 'Launch a run for a routine (invoked by the schedule''s Lambda, and by the user "Run now" path

        which invokes this same Lambda asynchronously).


        Only *launches* — opens the session and sends the prompt, then returns the ``running`` run without

        waiting for the agent. ``RoutineReconciler`` finalizes the run later from the session status.'
      operationId: execute_routine_api_admin_v1_routines_execute_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminExecuteRoutineRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/admin/v1/routines/runs/reconcile:
    post:
      tags:
      - routines_admin
      summary: Reconcile Runs
      description: 'Finalize routine runs stuck in ``running`` whose session changed status outside the runner''s

        watch (invoked by the reconciler Lambda ~every 5 min). Returns ``{reconciled: N}``.'
      operationId: reconcile_runs_api_admin_v1_routines_runs_reconcile_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/admin/v1/routines:
    get:
      tags:
      - routines_admin
      summary: List Routines
      description: List a project's routines (newest first), including admin-only ones.
      operationId: list_routines_api_admin_v1_routines_get
      security:
      - HTTPBearer: []
      parameters:
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoutineResponse'
                title: Response List Routines Api Admin V1 Routines Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - routines_admin
      summary: Create Routine
      description: Create a routine in a project. Defaults to ``admin_only=True`` (hidden from the user API).
      operationId: create_routine_api_admin_v1_routines_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateRoutineRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/routines/{routine_id}:
    get:
      tags:
      - routines_admin
      summary: Get Routine
      description: Get a routine by id within a project (admin-only routines included).
      operationId: get_routine_api_admin_v1_routines__routine_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - routines_admin
      summary: Update Routine
      description: Edit a routine; re-syncs its EventBridge schedule. ``admin_only`` is fixed at create time.
      operationId: update_routine_api_admin_v1_routines__routine_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateRoutineRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - routines_admin
      summary: Delete Routine
      description: Delete a routine and its EventBridge schedule.
      operationId: delete_routine_api_admin_v1_routines__routine_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/routines/{routine_id}/pause:
    post:
      tags:
      - routines_admin
      summary: Pause Routine
      description: Pause a routine (status → paused; schedule disabled).
      operationId: pause_routine_api_admin_v1_routines__routine_id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/routines/{routine_id}/resume:
    post:
      tags:
      - routines_admin
      summary: Resume Routine
      description: Resume a routine (status → active; schedule enabled/created).
      operationId: resume_routine_api_admin_v1_routines__routine_id__resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/routines/{routine_id}/runs:
    get:
      tags:
      - routines_admin
      summary: List Routine Runs
      description: Run history for a routine (newest first), with the total count for pagination.
      operationId: list_routine_runs_api_admin_v1_routines__routine_id__runs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Cursor
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineRunListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/admin/v1/routines/{routine_id}/runs/{run_id}:
    get:
      tags:
      - routines_admin
      summary: Get Routine Run
      description: Run detail (status/timestamps/session_id) within a project.
      operationId: get_routine_run_api_admin_v1_routines__routine_id__runs__run_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: routine_id
        in: path
        required: true
        schema:
          type: integer
          title: Routine Id
      - name: run_id
        in: path
        required: true
        schema:
          type: integer
          title: Run Id
      - name: project_id
        in: query
        required: true
        schema:
          type: integer
          title: Project Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutineRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    src__routines__constants__RunStatus:
      type: string
      enum:
      - running
      - success
      - failed
      - needs_input
      title: RunStatus
      description: 'Status of a single routine run.


        Derived from the bound managed-agent session: agent terminal (``done``) → ``success``;

        still awaiting input at end of budget (``waiting``) → ``needs_input``; provider/exception

        → ``failed``. Stored as ``text`` in the DB.'
    RoutineRunResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Run id.
        routine_id:
          type: integer
          title: Routine Id
          description: Owning routine id.
        session_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Session Id
          description: Bound managed-agent session id, if started.
        trigger_type:
          $ref: '#/components/schemas/TriggerType'
          description: How the run was triggered.
        status:
          $ref: '#/components/schemas/src__routines__constants__RunStatus'
          description: Run status.
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Failure detail, if any.
        email_message_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Email Message Id
          description: OutboundMessage id for email delivery.
        slack_message_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Slack Message Id
          description: OutboundMessage id for Slack delivery.
        started_at:
          type: string
          format: date-time
          title: Started At
          description: When the run started.
        finished_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Finished At
          description: When the run finished, if terminal.
      type: object
      required:
      - id
      - routine_id
      - trigger_type
      - status
      - started_at
      title: RoutineRunResponse
      description: 'A routine run as returned by the API.


        No ``summary``/``output`` — the agent''s reply/transcript is fetched from the bound session''s

        events (managed-agents ``GET …/sessions/{session_id}/events``) via ``session_id``.'
    RoutineRunListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/RoutineRunResponse'
          type: array
          title: Items
          description: Runs on this page (newest first).
        total:
          type: integer
          title: Total
          description: Total runs for the routine (across all pages).
      type: object
      required:
      - items
      - total
      title: RoutineRunListResponse
      description: A page of routine runs plus the total count (for pagination).
    ScheduleTrigger:
      properties:
        type:
          type: string
          const: schedule
          title: Type
          description: 'Trigger type. v1: ''schedule'' only.'
          default: schedule
        mode:
          type: string
          enum:
          - simple
          - raw
          title: Mode
          description: Which cron editor produced the expression.
          default: simple
        cron:
          type: string
          title: Cron
          description: 5-field cron expression.
          examples:
          - 0 9 * * MON
        timezone:
          type: string
          title: Timezone
          description: IANA timezone for the schedule.
          examples:
          - America/New_York
      type: object
      required:
      - cron
      - timezone
      title: ScheduleTrigger
      description: 'A schedule trigger fires the routine on a cron schedule (the only v1 trigger).


        The prototype''s ``cron`` trigger maps onto this ``schedule`` type. ``mode`` records which editor

        produced the cron string (the simple Day/Week/Month picker vs. a raw cron field).'
    RoutineResponse:
      properties:
        id:
          type: integer
          title: Id
          description: Routine id.
        project_id:
          type: integer
          title: Project Id
          description: Owning project id.
        created_by:
          type: integer
          title: Created By
          description: User id of the creator.
        agent_id:
          type: integer
          title: Agent Id
          description: Managed agent the routine runs.
        name:
          type: string
          title: Name
          description: Routine name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Human description.
        status:
          $ref: '#/components/schemas/RoutineStatus'
          description: Routine status.
        admin_only:
          type: boolean
          title: Admin Only
          description: Admin-API only when true; hidden from the user-facing API.
          default: false
        prompt:
          type: string
          title: Prompt
          description: First user message of each run.
        triggers:
          items:
            $ref: '#/components/schemas/ScheduleTrigger'
          type: array
          title: Triggers
          description: Schedule triggers.
        destinations:
          $ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
          description: Delivery targets.
        schedule_arn:
          anyOf:
          - type: string
          - type: 'null'
          title: Schedule Arn
          description: EventBridge schedule ARN, if scheduled.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp.
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp.
        last_run_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Run At
          description: Start time of the most recent run.
        recent_runs:
          items:
            $ref: '#/components/schemas/src__routines__constants__RunStatus'
          type: array
          title: Recent Runs
          description: Recent run statuses (oldest→newest) for the list-card sparkline; list view only.
        recent_run_details:
          items:
            $ref: '#/components/schemas/RecentRunDetail'
          type: array
          title: Recent Run Details
          description: Dated recent run outcomes, oldest to newest; list view only.
        success_rate:
          anyOf:
          - type: number
          - type: 'null'
          title: Success Rate
          description: Percent of finished recent runs that succeeded (0–100); list view only.
      type: object
      required:
      - id
      - project_id
      - created_by
      - agent_id
      - name
      - status
      - prompt
      - created_at
      - updated_at
      title: RoutineResponse
      description: Routine as returned by the API.
    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
    src__routines__schemas__destinations__Destinations:
      properties:
        emails:
          items:
            type: string
          type: array
          title: Emails
          description: Email recipients.
        slack:
          anyOf:
          - $ref: '#/components/schemas/src__routines__schemas__destinations__SlackDestination'
          - type: 'null'
          description: Slack channel, if any.
        attach_files:
          type: boolean
          title: Attach Files
          description: Deliver any file the run produces (export, report, deck) as a real email attachment, keeping its download link in the body. Email only. Files over the size cap are sent as a link. Routines saved before this field existed read as true.
          default: true
      type: object
      title: Destinations
      description: Where a routine run's result is delivered. All fields optional — a draft may have none.
    RoutineStatus:
      type: string
      enum:
      - draft
      - active
      - paused
      title: RoutineStatus
      description: 'Lifecycle status of a routine.


        ``draft`` — saved but not scheduled (no EventBridge schedule created).

        ``active`` — scheduled and firing.

        ``paused`` — schedule disabled, kept for later resume.

        Stored as ``text`` in the DB (no PG enum), mirroring managed-agents ``SessionStatus``.'
    src__routines__schemas__destinations__SlackDestination:
      properties:
        channel_id:
          type: string
          title: Channel Id
          description: Slack channel id.
          examples:
          - C0VOCWEEK
        channel_name:
          type: string
          title: Channel Name
          description: Slack channel name (without '#').
          examples:
          - voc-weekly
      type: object
      required:
      - channel_id
      - channel_name
      title: SlackDestination
      description: A Slack channel a routine run is delivered to.
    TriggerType:
      type: string
      enum:
      - schedule
      - manual
      title: TriggerType
      description: 'How a run was triggered.


        ``schedule`` — the routine''s cron fired (EventBridge schedule -> execute Lambda).

        ``manual`` — a user hit "Run now" in the UI (the same Lambda, invoked on demand, not by the cron).

        Stored as ``text`` in the DB; ``api`` stays reserved for later without a migration.'
    RecentRunDetail:
      properties:
        status:
          $ref: '#/components/schemas/src__routines__constants__RunStatus'
        started_at:
          type: string
          format: date-time
          title: Started At
      type: object
      required:
      - status
      - started_at
      title: RecentRunDetail
    AdminExecuteRoutineRequest:
      properties:
        project_id:
          type: integer
          title: Project Id
          description: Owning project id (the schedule's target project).
        routine_id:
          type: integer
          title: Routine Id
          description: Routine to run.
        trigger_type:
          $ref: '#/components/schemas/TriggerType'
          description: 'How the run was triggered: ''schedule'' or ''manual''.'
          default: schedule
      type: object
      required:
      - project_id
      - routine_id
      title: AdminExecuteRoutineRequest
      description: 'Body for the admin ``/execute`` endpoint, sent by the execute Lambda (no user token).


        Just enough to identify the routine and its project; the routine (prompt, agent, destinations) is

        loaded by id. ``trigger_type`` distinguishes a scheduled fire from a UI "Run now"; it defaults to

        ``schedule`` so the EventBridge target input (which omits it) keeps working unchanged.'
    AdminCreateRoutineRequest:
      properties:
        name:
          type: string
          title: Name
          description: Routine name (not unique).
          examples:
          - Weekly VoC digest
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional human description.
        agent_id:
          type: integer
          title: Agent Id
          description: Managed agent to run.
        prompt:
          type: string
          title: Prompt
          description: First user message sent on each run.
        triggers:
          items:
            $ref: '#/components/schemas/ScheduleTrigger'
          type: array
          title: Triggers
          description: 'v1: at most one schedule trigger.'
        destinations:
          $ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
          description: Slack/email delivery targets.
        status:
          $ref: '#/components/schemas/RoutineStatus'
          description: Initial status. 'draft' creates no schedule.
          default: draft
        project_id:
          type: integer
          title: Project Id
          description: Owning project id.
        created_by:
          type: integer
          title: Created By
          description: User id to record as the creator.
        admin_only:
          type: boolean
          title: Admin Only
          description: Hide from the user-facing API (admin-only).
          default: true
      type: object
      required:
      - name
      - agent_id
      - prompt
      - project_id
      - created_by
      title: AdminCreateRoutineRequest
      description: 'Admin ``POST /routines`` body (no user token): the user create payload plus the admin-only

        fields. ``project_id``/``created_by`` come from the body (the admin contour has no session);

        ``admin_only`` defaults to ``True`` (the admin API''s purpose), but a user-visible routine can be

        created by setting it ``False``.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AdminUpdateRoutineRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: New name.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: New description.
        agent_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Agent Id
          description: New managed agent.
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
          description: New prompt.
        triggers:
          anyOf:
          - items:
              $ref: '#/components/schemas/ScheduleTrigger'
            type: array
          - type: 'null'
          title: Triggers
          description: New triggers.
        destinations:
          anyOf:
          - $ref: '#/components/schemas/src__routines__schemas__destinations__Destinations'
          - type: 'null'
          description: New destinations.
        status:
          anyOf:
          - $ref: '#/components/schemas/RoutineStatus'
          - type: 'null'
          description: New status.
        project_id:
          type: integer
          title: Project Id
          description: Owning project id (scopes the routine).
      type: object
      required:
      - project_id
      title: AdminUpdateRoutineRequest
      description: 'Admin ``PATCH /routines/{id}`` body: the user update payload, scoped by ``project_id``

        (``admin_only`` is fixed at create time).'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    HTTPBasic:
      type: http
      scheme: basic