byre/api/openapi.yaml

openapi: 3.0.3
info:
  title: byre
  version: 0.0.0
paths:
  /api/me:
    get:
      operationId: getMe
      responses:
        "200":
          description: The calling user.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
    put:
      operationId: updateMe
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UserUpdate" }
      responses:
        "200":
          description: The updated user.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
        "400": { $ref: "#/components/responses/Error" }

  /api/projects:
    get:
      operationId: listProjects
      responses:
        "200":
          description: All projects.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Project" }
    post:
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ProjectCreate" }
      responses:
        "201":
          description: The new project.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Project" }
        "400": { $ref: "#/components/responses/Error" }

  /api/projects/{projectId}:
    parameters:
      - { name: projectId, in: path, required: true, schema: { type: string } }
    get:
      operationId: getProject
      responses:
        "200":
          description: The project.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Project" }
        "404": { $ref: "#/components/responses/Error" }

  /api/projects/{projectId}/tasks:
    parameters:
      - { name: projectId, in: path, required: true, schema: { type: string } }
    get:
      operationId: listTasks
      responses:
        "200":
          description: The project's tasks, newest first.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Task" }
        "404": { $ref: "#/components/responses/Error" }
    post:
      operationId: createTask
      description: Creates the task's branch and worktree from the project's default branch.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/TaskCreate" }
      responses:
        "201":
          description: The new task.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }
        "400": { $ref: "#/components/responses/Error" }
        "404": { $ref: "#/components/responses/Error" }

  /api/tasks/{taskId}:
    parameters:
      - { name: taskId, in: path, required: true, schema: { type: string } }
    get:
      operationId: getTask
      responses:
        "200":
          description: The task.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }
        "404": { $ref: "#/components/responses/Error" }

  /api/tasks/{taskId}/complete:
    parameters:
      - { name: taskId, in: path, required: true, schema: { type: string } }
    post:
      operationId: completeTask
      description: Removes the task's worktree and branch. The task's record and events remain.
      responses:
        "200":
          description: The completed task.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Task" }
        "404": { $ref: "#/components/responses/Error" }
        "409": { $ref: "#/components/responses/Error" }

  /api/events:
    get:
      operationId: streamEvents
      description: >
        Server-sent events. Each event's id is its seq; data is the Event as JSON.
        Events after Last-Event-ID (or the after query parameter) are replayed before live events.
      parameters:
        - { name: Last-Event-ID, in: header, required: false, schema: { type: integer, format: int64 } }
        - { name: after, in: query, required: false, schema: { type: integer, format: int64 } }
      responses:
        "200":
          description: Event stream.
          content:
            text/event-stream:
              schema: { type: string }

  /api/admin/status:
    get:
      operationId: getStatus
      responses:
        "200":
          description: Server health and usage.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Status" }

components:
  responses:
    Error:
      description: Error.
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }

  schemas:
    Error:
      type: object
      required: [message]
      properties:
        message: { type: string }

    User:
      type: object
      required: [login, display_name, git_name, git_email]
      properties:
        login: { type: string }
        display_name: { type: string }
        git_name: { type: string }
        git_email: { type: string }

    UserUpdate:
      type: object
      required: [git_name, git_email]
      properties:
        git_name: { type: string }
        git_email: { type: string }

    Project:
      type: object
      required: [id, name, repo_path, default_branch, remote, created_by, created_at]
      properties:
        id: { type: string }
        name: { type: string }
        repo_path: { type: string }
        default_branch: { type: string }
        remote: { type: string }
        created_by: { type: string }
        created_at: { type: string, format: date-time }

    ProjectCreate:
      type: object
      required: [name, repo_path]
      properties:
        name: { type: string }
        repo_path: { type: string }

    Task:
      type: object
      required: [id, project_id, title, branch, worktree_path, base_ref, status, created_by, created_at]
      properties:
        id: { type: string }
        project_id: { type: string }
        title: { type: string }
        branch: { type: string }
        worktree_path: { type: string }
        base_ref: { type: string }
        status: { type: string, enum: [active, completed] }
        created_by: { type: string }
        created_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }

    TaskCreate:
      type: object
      required: [title]
      properties:
        title: { type: string }

    Event:
      type: object
      required: [seq, kind, actor, payload, created_at]
      properties:
        seq: { type: integer, format: int64 }
        kind: { type: string }
        project_id: { type: string }
        task_id: { type: string }
        actor: { type: string }
        payload: { type: object }
        created_at: { type: string, format: date-time }

    Status:
      type: object
      required: [started_at, db_bytes, last_event_seq, projects, active_tasks, sse_clients]
      properties:
        started_at: { type: string, format: date-time }
        db_bytes: { type: integer, format: int64 }
        last_event_seq: { type: integer, format: int64 }
        projects: { type: integer }
        active_tasks: { type: integer }
        sse_clients: { type: integer }