openapi: 3.1.0
info:
  description: Loopback-only HTTP surface served by the Go daemon. Generated from
    Go (code-first) — do not edit by hand; run `go generate ./...`.
  title: Agent Orchestrator HTTP daemon
  version: 0.1.0-route-shell
servers:
- description: Local daemon (loopback only)
  url: http://127.0.0.1:3001
paths:
  /api/v1/events:
    get:
      operationId: streamEvents
      parameters:
      - description: Replay events with seq greater than this cursor. When omitted,
          clients may send Last-Event-ID instead.
        in: query
        name: after
        schema:
          description: Replay events with seq greater than this cursor. When omitted,
            clients may send Last-Event-ID instead.
          minimum: 0
          type:
          - "null"
          - integer
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                type: string
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Stream CDC events with durable replay
      tags:
      - events
  /api/v1/notifications:
    get:
      operationId: listNotifications
      parameters:
      - description: Notification status filter. V1 supports only unread.
        in: query
        name: status
        schema:
          description: Notification status filter. V1 supports only unread.
          enum:
          - unread
          type: string
      - description: Maximum notifications to return. Defaults to 50; capped at 100.
        in: query
        name: limit
        schema:
          description: Maximum notifications to return. Defaults to 50; capped at
            100.
          maximum: 100
          minimum: 1
          type: integer
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListNotificationsResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: List unread notifications
      tags:
      - notifications
  /api/v1/notifications/{id}:
    patch:
      operationId: markNotificationRead
      parameters:
      - description: Notification identifier.
        in: path
        name: id
        required: true
        schema:
          description: Notification identifier.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkNotificationReadRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationEnvelope'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Mark a notification read
      tags:
      - notifications
  /api/v1/notifications/read-all:
    post:
      operationId: markAllNotificationsRead
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarkAllNotificationsReadResponse'
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Mark all unread notifications read
      tags:
      - notifications
  /api/v1/notifications/stream:
    get:
      operationId: streamNotifications
      parameters:
      - description: Optional project id filter for live notifications.
        in: query
        name: projectId
        schema:
          description: Optional project id filter for live notifications.
          type: string
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                type: string
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Stream created notifications
      tags:
      - notifications
  /api/v1/orchestrators:
    get:
      operationId: listOrchestrators
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: List orchestrator sessions across projects
      tags:
      - sessions
    post:
      operationId: spawnOrchestrator
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpawnOrchestratorRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpawnOrchestratorResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Spawn an orchestrator session
      tags:
      - sessions
  /api/v1/orchestrators/{id}:
    get:
      operationId: getOrchestrator
      parameters:
      - description: Orchestrator session identifier, e.g. project-orchestrator.
        in: path
        name: id
        required: true
        schema:
          description: Orchestrator session identifier, e.g. project-orchestrator.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Fetch one orchestrator session
      tags:
      - sessions
  /api/v1/projects:
    get:
      operationId: listProjects
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProjectsResponse'
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: List all registered projects (active + degraded)
      tags:
      - projects
    post:
      operationId: addProject
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddProjectInput'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Register a new project from a git repository path
      tags:
      - projects
  /api/v1/projects/{id}:
    delete:
      operationId: removeProject
      parameters:
      - description: Project identifier (registry key).
        in: path
        name: id
        required: true
        schema:
          description: Project identifier (registry key).
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveProjectResult'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Remove a project; stops sessions, cleans workspaces, unregisters
      tags:
      - projects
    get:
      operationId: getProject
      parameters:
      - description: Project identifier (registry key).
        in: path
        name: id
        required: true
        schema:
          description: Project identifier (registry key).
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectGetResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Fetch one project; discriminates ok vs degraded
      tags:
      - projects
  /api/v1/projects/{id}/config:
    put:
      operationId: setProjectConfig
      parameters:
      - description: Project identifier (registry key).
        in: path
        name: id
        required: true
        schema:
          description: Project identifier (registry key).
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetProjectConfigInput'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Replace a project's per-project config
      tags:
      - projects
  /api/v1/prs/{id}/merge:
    post:
      operationId: mergePR
      parameters:
      - description: PR number.
        in: path
        name: id
        required: true
        schema:
          description: PR number.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MergePRResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Squash-merge a pull request
      tags:
      - prs
  /api/v1/prs/{id}/resolve-comments:
    post:
      operationId: resolveComments
      parameters:
      - description: PR number.
        in: path
        name: id
        required: true
        schema:
          description: PR number.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveCommentsResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Resolve review threads on a pull request
      tags:
      - prs
  /api/v1/sessions:
    get:
      operationId: listSessions
      parameters:
      - description: Project id filter.
        in: query
        name: project
        schema:
          description: Project id filter.
          type: string
      - description: When true, return non-terminated sessions; when false, return
          terminated sessions.
        in: query
        name: active
        schema:
          description: When true, return non-terminated sessions; when false, return
            terminated sessions.
          type:
          - "null"
          - boolean
      - description: When true, return only orchestrator sessions.
        in: query
        name: orchestratorOnly
        schema:
          description: When true, return only orchestrator sessions.
          type:
          - "null"
          - boolean
      - description: When true, return only fresh non-terminated sessions.
        in: query
        name: fresh
        schema:
          description: When true, return only fresh non-terminated sessions.
          type:
          - "null"
          - boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionsResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: List sessions
      tags:
      - sessions
    post:
      operationId: spawnSession
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpawnSessionRequest'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
          description: Created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Spawn a new agent session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}:
    get:
      operationId: getSession
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Fetch one session
      tags:
      - sessions
    patch:
      operationId: renameSession
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenameSessionRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenameSessionResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Rename a session display name
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/activity:
    post:
      operationId: setSessionActivity
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetActivityRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetActivityResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Report an agent activity-state signal for a session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/kill:
    post:
      operationId: killSession
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KillSessionResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Mark a session terminated and tear down runtime/workspace resources
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/pr:
    get:
      operationId: listSessionPRs
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSessionPRsResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: List pull requests owned by a session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/pr/claim:
    post:
      operationId: claimSessionPR
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimPRRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimPRResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
        "503":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Service Unavailable
      summary: Claim an existing pull request for a session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/preview:
    get:
      operationId: getSessionPreview
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPreviewResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Discover a browser preview URL for a session workspace
      tags:
      - sessions
    post:
      operationId: setSessionPreview
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetSessionPreviewRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Set (or autodetect) the browser preview URL for a session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/preview/files/*:
    get:
      operationId: getSessionPreviewFile
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            text/html:
              schema:
                type: string
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Serve a static browser preview file from a session workspace
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/restore:
    post:
      operationId: restoreSession
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreSessionResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Restore a terminated session
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/reviews:
    get:
      operationId: listReviews
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListReviewsResponse'
          description: OK
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: List a worker's code-review runs
      tags:
      - reviews
  /api/v1/sessions/{sessionId}/reviews/submit:
    post:
      operationId: submitReview
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitReviewInput'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewRunResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Record a reviewer's result for a worker's PR
      tags:
      - reviews
  /api/v1/sessions/{sessionId}/reviews/trigger:
    post:
      operationId: triggerReview
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewRunResponse'
          description: OK
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewRunResponse'
          description: Created
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "422":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Unprocessable Entity
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Trigger a code review of a worker's PR
      tags:
      - reviews
  /api/v1/sessions/{sessionId}/rollback:
    post:
      operationId: rollbackSession
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RollbackSessionResponse'
          description: OK
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "409":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Conflict
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Undo a partially-completed spawn (delete seed row, or kill if spawn
        output exists)
      tags:
      - sessions
  /api/v1/sessions/{sessionId}/send:
    post:
      operationId: sendSessionMessage
      parameters:
      - description: Session identifier, e.g. project-1.
        in: path
        name: sessionId
        required: true
        schema:
          description: Session identifier, e.g. project-1.
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendSessionMessageRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendSessionMessageResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
      summary: Send a message to a running session's agent
      tags:
      - sessions
  /api/v1/sessions/cleanup:
    post:
      operationId: cleanupSessions
      parameters:
      - description: Project id filter. When omitted, clean terminated sessions across
          all projects.
        in: query
        name: project
        schema:
          description: Project id filter. When omitted, clean terminated sessions
            across all projects.
          type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CleanupSessionsResponse'
          description: OK
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Internal Server Error
        "501":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Implemented
      summary: Clean up terminated session workspaces
      tags:
      - sessions
components:
  schemas:
    APIError:
      properties:
        code:
          type: string
        details:
          additionalProperties: {}
          type: object
        error:
          type: string
        message:
          type: string
        requestId:
          type: string
      required:
      - error
      - code
      - message
      type: object
    AddProjectInput:
      properties:
        asWorkspace:
          type: boolean
        config:
          $ref: '#/components/schemas/ProjectConfig'
        name:
          type:
          - "null"
          - string
        path:
          type: string
        projectId:
          type:
          - "null"
          - string
      required:
      - path
      type: object
    AgentConfig:
      properties:
        model:
          type: string
        permissions:
          type: string
      type: object
    ClaimPRRequest:
      properties:
        allowTakeover:
          type:
          - "null"
          - boolean
        pr:
          minLength: 1
          type: string
      required:
      - pr
      type: object
    ClaimPRResponse:
      properties:
        branchChanged:
          type: boolean
        ok:
          type: boolean
        prs:
          items:
            $ref: '#/components/schemas/SessionPRFacts'
          type: array
        sessionId:
          type: string
        takenOverFrom:
          items:
            type: string
          type: array
      required:
      - ok
      - sessionId
      - prs
      - branchChanged
      - takenOverFrom
      type: object
    CleanupSessionsResponse:
      properties:
        cleaned:
          items:
            type: string
          type: array
        ok:
          type: boolean
        skipped:
          items:
            $ref: '#/components/schemas/CleanupSkippedSession'
          type: array
      required:
      - ok
      - cleaned
      - skipped
      type: object
    CleanupSkippedSession:
      properties:
        reason:
          type: string
        sessionId:
          type: string
      required:
      - sessionId
      - reason
      type: object
    ControllersSessionView:
      properties:
        activity:
          $ref: '#/components/schemas/DomainActivity'
        branch:
          type: string
        createdAt:
          format: date-time
          type: string
        displayName:
          type: string
        harness:
          type: string
        id:
          type: string
        isTerminated:
          type: boolean
        issueId:
          type: string
        kind:
          type: string
        previewUrl:
          type: string
        projectId:
          type: string
        prs:
          items:
            $ref: '#/components/schemas/SessionPRFacts'
          type: array
        status:
          enum:
          - working
          - pr_open
          - draft
          - ci_failed
          - review_pending
          - changes_requested
          - approved
          - mergeable
          - merged
          - needs_input
          - idle
          - terminated
          - no_signal
          type: string
        terminalHandleId:
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
      - id
      - projectId
      - kind
      - activity
      - isTerminated
      - createdAt
      - updatedAt
      - status
      - prs
      type: object
    DegradedProject:
      properties:
        id:
          type: string
        kind:
          type: string
        name:
          type: string
        path:
          type: string
        resolveError:
          type: string
      required:
      - id
      - name
      - kind
      - path
      - resolveError
      type: object
    DomainActivity:
      properties:
        lastActivityAt:
          format: date-time
          type: string
        state:
          type: string
      required:
      - state
      - lastActivityAt
      type: object
    DomainReviewerConfig:
      properties:
        harness:
          type: string
      required:
      - harness
      type: object
    KillSessionResponse:
      properties:
        freed:
          type: boolean
        ok:
          type: boolean
        sessionId:
          type: string
      required:
      - ok
      - sessionId
      type: object
    ListNotificationsResponse:
      properties:
        notifications:
          items:
            $ref: '#/components/schemas/NotificationResponse'
          type: array
      required:
      - notifications
      type: object
    ListProjectsResponse:
      properties:
        projects:
          items:
            $ref: '#/components/schemas/ProjectSummary'
          type: array
      required:
      - projects
      type: object
    ListReviewsResponse:
      properties:
        reviewerHandleId:
          type: string
        reviews:
          items:
            $ref: '#/components/schemas/ReviewRun'
          type: array
      required:
      - reviewerHandleId
      - reviews
      type: object
    ListSessionPRsResponse:
      properties:
        prs:
          items:
            $ref: '#/components/schemas/SessionPRSummary'
          type: array
        sessionId:
          type: string
      required:
      - sessionId
      - prs
      type: object
    ListSessionsResponse:
      properties:
        sessions:
          items:
            $ref: '#/components/schemas/ControllersSessionView'
          type: array
      required:
      - sessions
      type: object
    MarkAllNotificationsReadResponse:
      properties:
        notifications:
          items:
            $ref: '#/components/schemas/NotificationResponse'
          type: array
      required:
      - notifications
      type: object
    MarkNotificationReadRequest:
      properties:
        status:
          description: V1 supports only marking an unread notification read.
          enum:
          - read
          type: string
      required:
      - status
      type: object
    MergePRResponse:
      properties:
        method:
          type: string
        ok:
          type: boolean
        prNumber:
          type: integer
      required:
      - ok
      - prNumber
      - method
      type: object
    NotificationEnvelope:
      properties:
        notification:
          $ref: '#/components/schemas/NotificationResponse'
      required:
      - notification
      type: object
    NotificationResponse:
      properties:
        body:
          type: string
        createdAt:
          format: date-time
          type: string
        id:
          type: string
        prUrl:
          type: string
        projectId:
          type: string
        sessionId:
          type: string
        status:
          enum:
          - unread
          - read
          type: string
        target:
          $ref: '#/components/schemas/NotificationTarget'
        title:
          type: string
        type:
          enum:
          - needs_input
          - ready_to_merge
          - pr_merged
          - pr_closed_unmerged
          type: string
      required:
      - id
      - sessionId
      - projectId
      - prUrl
      - type
      - title
      - body
      - status
      - createdAt
      - target
      type: object
    NotificationTarget:
      properties:
        kind:
          enum:
          - session
          - pr
          type: string
        prUrl:
          type: string
        sessionId:
          type: string
      required:
      - kind
      - sessionId
      type: object
    OrchestratorResponse:
      properties:
        id:
          type: string
        projectId:
          type: string
        projectName:
          type: string
      required:
      - id
      - projectId
      type: object
    Project:
      properties:
        agent:
          type: string
        config:
          $ref: '#/components/schemas/ProjectConfig'
        defaultBranch:
          type: string
        id:
          type: string
        kind:
          type: string
        name:
          type: string
        path:
          type: string
        repo:
          type: string
        workspaceRepos:
          items:
            $ref: '#/components/schemas/WorkspaceRepo'
          type: array
      required:
      - id
      - name
      - kind
      - path
      - repo
      - defaultBranch
      type: object
    ProjectConfig:
      properties:
        agentConfig:
          $ref: '#/components/schemas/AgentConfig'
        defaultBranch:
          type: string
        env:
          additionalProperties:
            type: string
          type: object
        orchestrator:
          $ref: '#/components/schemas/RoleOverride'
        postCreate:
          items:
            type: string
          type: array
        reviewers:
          items:
            $ref: '#/components/schemas/DomainReviewerConfig'
          type: array
        sessionPrefix:
          type: string
        symlinks:
          items:
            type: string
          type: array
        worker:
          $ref: '#/components/schemas/RoleOverride'
      type: object
    ProjectGetResponse:
      properties:
        project:
          $ref: '#/components/schemas/ProjectOrDegraded'
        status:
          enum:
          - ok
          - degraded
          type: string
      required:
      - status
      - project
      type: object
    ProjectOrDegraded:
      oneOf:
      - $ref: '#/components/schemas/Project'
      - $ref: '#/components/schemas/DegradedProject'
      type: object
    ProjectResponse:
      properties:
        project:
          $ref: '#/components/schemas/Project'
      required:
      - project
      type: object
    ProjectSummary:
      properties:
        id:
          type: string
        kind:
          type: string
        name:
          type: string
        path:
          type: string
        resolveError:
          type: string
        sessionPrefix:
          type: string
      required:
      - id
      - name
      - path
      - kind
      - sessionPrefix
      type: object
    RemoveProjectResult:
      properties:
        projectId:
          type: string
        removedStorageDir:
          type: boolean
      required:
      - projectId
      - removedStorageDir
      type: object
    RenameSessionRequest:
      properties:
        displayName:
          minLength: 1
          type: string
      required:
      - displayName
      type: object
    RenameSessionResponse:
      properties:
        displayName:
          type: string
        ok:
          type: boolean
        sessionId:
          type: string
      required:
      - ok
      - sessionId
      - displayName
      type: object
    ResolveCommentsResponse:
      properties:
        ok:
          type: boolean
        resolved:
          type: integer
      required:
      - ok
      - resolved
      type: object
    RestoreSessionResponse:
      properties:
        ok:
          type: boolean
        session:
          $ref: '#/components/schemas/ControllersSessionView'
        sessionId:
          type: string
      required:
      - ok
      - sessionId
      - session
      type: object
    ReviewRun:
      properties:
        body:
          type: string
        createdAt:
          format: date-time
          type: string
        githubReviewId:
          type: string
        harness:
          type: string
        id:
          type: string
        prUrl:
          type: string
        reviewId:
          type: string
        sessionId:
          type: string
        status:
          type: string
        targetSha:
          type: string
        verdict:
          type: string
      required:
      - id
      - reviewId
      - sessionId
      - harness
      - prUrl
      - targetSha
      - status
      - verdict
      - body
      - githubReviewId
      - createdAt
      type: object
    ReviewRunResponse:
      properties:
        review:
          $ref: '#/components/schemas/ReviewRun'
        reviewerHandleId:
          type: string
      required:
      - review
      - reviewerHandleId
      type: object
    RoleOverride:
      properties:
        agent:
          type: string
        agentConfig:
          $ref: '#/components/schemas/AgentConfig'
      type: object
    RollbackSessionResponse:
      properties:
        deleted:
          type: boolean
        killed:
          type: boolean
        ok:
          type: boolean
        sessionId:
          type: string
      required:
      - ok
      - sessionId
      type: object
    SendSessionMessageRequest:
      properties:
        message:
          maxLength: 4096
          minLength: 1
          type: string
      required:
      - message
      type: object
    SendSessionMessageResponse:
      properties:
        message:
          type: string
        ok:
          type: boolean
        sessionId:
          type: string
      required:
      - ok
      - sessionId
      - message
      type: object
    SessionPRCISummary:
      properties:
        failingChecks:
          items:
            $ref: '#/components/schemas/SessionPRFailingCheck'
          type: array
        state:
          enum:
          - unknown
          - pending
          - passing
          - failing
          type: string
      required:
      - state
      - failingChecks
      type: object
    SessionPRConflictFile:
      properties:
        path:
          type: string
        url:
          type: string
      required:
      - path
      type: object
    SessionPRFacts:
      properties:
        ci:
          enum:
          - unknown
          - pending
          - passing
          - failing
          type: string
        mergeability:
          enum:
          - unknown
          - mergeable
          - conflicting
          - blocked
          - unstable
          type: string
        number:
          type: integer
        review:
          enum:
          - none
          - approved
          - changes_requested
          - review_required
          type: string
        reviewComments:
          type: boolean
        state:
          enum:
          - draft
          - open
          - merged
          - closed
          type: string
        updatedAt:
          format: date-time
          type: string
        url:
          type: string
      required:
      - url
      - number
      - state
      - ci
      - review
      - mergeability
      - reviewComments
      - updatedAt
      type: object
    SessionPRFailingCheck:
      properties:
        conclusion:
          type: string
        name:
          type: string
        status:
          enum:
          - failed
          - cancelled
          type: string
        url:
          type: string
      required:
      - name
      - status
      - conclusion
      type: object
    SessionPRMergeabilitySummary:
      properties:
        conflictFiles:
          items:
            $ref: '#/components/schemas/SessionPRConflictFile'
          type: array
        prUrl:
          type: string
        reasons:
          items:
            type: string
          type: array
        state:
          enum:
          - unknown
          - mergeable
          - conflicting
          - blocked
          - unstable
          type: string
      required:
      - state
      - reasons
      - prUrl
      type: object
    SessionPRReviewCommentLink:
      properties:
        file:
          type: string
        line:
          type: integer
        url:
          type: string
      type: object
    SessionPRReviewSummary:
      properties:
        decision:
          enum:
          - none
          - approved
          - changes_requested
          - review_required
          type: string
        hasUnresolvedHumanComments:
          type: boolean
        unresolvedBy:
          items:
            $ref: '#/components/schemas/SessionPRUnresolvedReviewer'
          type: array
      required:
      - decision
      - hasUnresolvedHumanComments
      - unresolvedBy
      type: object
    SessionPRSummary:
      properties:
        additions:
          type: integer
        author:
          type: string
        changedFiles:
          type: integer
        ci:
          $ref: '#/components/schemas/SessionPRCISummary'
        ciObservedAt:
          format: date-time
          type: string
        deletions:
          type: integer
        headSha:
          type: string
        htmlUrl:
          type: string
        mergeability:
          $ref: '#/components/schemas/SessionPRMergeabilitySummary'
        number:
          type: integer
        observedAt:
          format: date-time
          type: string
        provider:
          enum:
          - github
          type: string
        repo:
          type: string
        review:
          $ref: '#/components/schemas/SessionPRReviewSummary'
        reviewObservedAt:
          format: date-time
          type: string
        sourceBranch:
          type: string
        state:
          enum:
          - draft
          - open
          - merged
          - closed
          type: string
        targetBranch:
          type: string
        title:
          type: string
        updatedAt:
          format: date-time
          type: string
        url:
          type: string
      required:
      - url
      - number
      - title
      - state
      - provider
      - repo
      - author
      - sourceBranch
      - targetBranch
      - headSha
      - additions
      - deletions
      - changedFiles
      - ci
      - review
      - mergeability
      - updatedAt
      type: object
    SessionPRUnresolvedReviewer:
      properties:
        count:
          type: integer
        links:
          items:
            $ref: '#/components/schemas/SessionPRReviewCommentLink'
          type: array
        reviewerId:
          type: string
      required:
      - reviewerId
      - count
      - links
      type: object
    SessionPreviewResponse:
      properties:
        entry:
          type: string
        previewUrl:
          type: string
        sessionId:
          type: string
      required:
      - sessionId
      type: object
    SessionResponse:
      properties:
        session:
          $ref: '#/components/schemas/ControllersSessionView'
      required:
      - session
      type: object
    SetActivityRequest:
      properties:
        state:
          description: Agent activity state reported by an agent hook.
          enum:
          - active
          - idle
          - waiting_input
          - exited
          type: string
      required:
      - state
      type: object
    SetActivityResponse:
      properties:
        ok:
          type: boolean
        sessionId:
          type: string
        state:
          type: string
      required:
      - ok
      - sessionId
      - state
      type: object
    SetProjectConfigInput:
      properties:
        config:
          $ref: '#/components/schemas/ProjectConfig'
      required:
      - config
      type: object
    SetSessionPreviewRequest:
      properties:
        url:
          description: Preview target URL. When empty, the daemon autodetects a static
            entry point in the session workspace.
          type: string
      type: object
    SpawnOrchestratorRequest:
      properties:
        clean:
          type: boolean
        projectId:
          type: string
      required:
      - projectId
      type: object
    SpawnOrchestratorResponse:
      properties:
        orchestrator:
          $ref: '#/components/schemas/OrchestratorResponse'
      required:
      - orchestrator
      type: object
    SpawnSessionRequest:
      properties:
        branch:
          type: string
        harness:
          enum:
          - claude-code
          - codex
          - aider
          - opencode
          - grok
          - droid
          - amp
          - agy
          - crush
          - cursor
          - qwen
          - copilot
          - goose
          - auggie
          - continue
          - devin
          - cline
          - kimi
          - kiro
          - kilocode
          - vibe
          - pi
          - autohand
          type: string
        issueId:
          type: string
        kind:
          enum:
          - worker
          - orchestrator
          type: string
        projectId:
          type: string
        prompt:
          maxLength: 4096
          type: string
      required:
      - projectId
      type: object
    SubmitReviewInput:
      properties:
        body:
          description: Review body recorded by AO. Required for changes_requested.
          type: string
        githubReviewId:
          description: Id of the GitHub PR review the reviewer posted, if any.
          type: string
        runId:
          description: Review run id being completed.
          type: string
        verdict:
          description: 'Review verdict: approved or changes_requested.'
          type: string
      required:
      - runId
      - verdict
      - body
      - githubReviewId
      type: object
    WorkspaceRepo:
      properties:
        name:
          type: string
        relativePath:
          type: string
        repo:
          type: string
      required:
      - name
      - relativePath
      - repo
      type: object
tags:
- description: Project registry, configuration, and lifecycle administration
  name: projects
- description: Agent session lifecycle and messaging
  name: sessions
- description: Pull-request actions (SCM lane)
  name: prs
- description: Code-review runs and findings
  name: reviews
- description: Durable dashboard notifications
  name: notifications
- description: Server-sent CDC event stream with durable replay
  name: events