openapi: 3.0.3
info:
  title: BuildProxy API
  description: GitLab Build API Proxy
  version: 1.0.0
servers:
  - url: https://builds.aikester.com
    description: Production server
paths:
  /projects:
    get:
      summary: Get list of all projects
      responses:
        '200':
          description: List of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '500':
          description: Internal server error
  /projects/{slug}:
    get:
      summary: Get a specific project by slug
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            example: hugo
          description: The project slug to retrieve
      responses:
        '200':
          description: Project details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
        '500':
          description: Internal server error
  /projects/{slug}/pipelines:
    get:
      summary: Get all pipelines for a project
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            example: hugo
          description: The project slug to retrieve pipelines for
      responses:
        '200':
          description: List of pipelines
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pipeline'
        '404':
          description: No pipelines found or project not found
        '500':
          description: Internal server error
  /projects/{slug}/pipelines/{ref}:
    get:
      summary: Get pipelines for a specific ref (branch/tag) for a project
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
            example: hugo
          description: The project slug to retrieve pipelines for
        - name: ref
          in: path
          required: true
          schema:
            type: string
            example: main
          description: The Git ref (branch or tag) to get pipelines for
      responses:
        '200':
          description: List of pipelines for the specified ref
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pipeline'
        '404':
          description: No pipelines found or project not found
        '500':
          description: Internal server error
  /jobs/{id}:
    get:
      summary: Get job information for a specific job
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            example: 25
          description: The GitLab job ID to retrieve
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          description: Job not found
        '500':
          description: Internal server error
  /jobs/{id}/console:
    get:
      summary: Get console output for a specific job
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            example: 25
          description: The GitLab job ID to retrieve console output for
      responses:
        '200':
          description: Console output
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsoleOutput'
        '404':
          description: Job not found
        '500':
          description: Internal server error
components:
  schemas:
    Pipeline:
      type: object
      properties:
        id:
          type: integer
          description: Pipeline ID
        iid:
          type: integer
          description: Pipeline internal ID
        status:
          type: string
          description: Pipeline status (running, success, failed, canceled)
        source:
          type: string
          description: Pipeline source (push, schedule, api)
        when:
          type: string
          description: When the pipeline was created (created, pushed, scheduled)
        created_at:
          type: string
          format: date-time
          description: When the pipeline was created
        updated_at:
          type: string
          format: date-time
          description: When the pipeline was last updated
        duration:
          type: integer
          description: Pipeline duration in seconds
        ref:
          type: string
          description: Git reference (branch or tag)
        sha:
          type: string
          description: Git commit SHA
        user:
          $ref: '#/components/schemas/User'
        details:
          type: object
          description: Pipeline details
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        username:
          type: string
        avatar_url:
          type: string
          format: uri
        web_url:
          type: string
          format: uri
    Project:
      type: object
      required:
        - gitlab_id
        - docker_hub_link
        - docs_link
        - container_name
        - slug
        - tags
      properties:
        gitlab_id:
          type: integer
          example: 1
          description: GitLab project ID
        docker_hub_link:
          type: string
          format: uri
          example: https://hub.docker.com/u/example/project-1
          description: Link to Docker Hub repository
        docs_link:
          type: string
          format: uri
          example: https://docs.example.com/project-1
          description: Link to project documentation
        container_name:
          type: string
          example: example/project-1
          description: Docker container name
        slug:
          type: string
          example: project-1
          description: URL-friendly slug for accessing the project
        tags:
          type: array
          items:
            type: string
          example:
            - production
            - staging
            - internal
          description: Array of supported tags for this project
    Job:
      type: object
      properties:
        id:
          type: integer
          description: Job ID
        project_id:
          type: integer
          description: Project ID
        build_job:
          type: boolean
          description: Whether this is a build job
        name:
          type: string
          description: Job name
        tags:
          type: array
          items:
            type: string
          description: Job tags
        status:
          type: string
          description: Job status (success, failed, running, canceled)
        when:
          type: string
          description: When the job was created
        created_at:
          type: string
          format: date-time
          description: When the job was created
        finished_at:
          type: string
          format: date-time
          description: When the job finished
        duration:
          type: integer
          description: Job duration in seconds
        artifacts:
          type: array
          items:
            type: object
          description: Job artifacts
    ConsoleOutput:
      type: object
      properties:
        output:
          type: string
          description: Console output from the job
