openapi: 3.1.0
info:
  title: ShipRepo API
  version: 1.0.0
  description: |
    ShipRepo runs AI agents that read a GitHub repository, edit files, run tests
    in an isolated Docker sandbox and open a pull request — or scaffold a full
    marketing site to a fresh repo and a live shiprepo.com/s/<slug>/ URL.

    Authenticate with a Bearer Personal Access Token (create one at
    https://cp.shiprepo.com/tokens.html).
servers:
  - url: https://api.shiprepo.com
    description: Production
security:
  - bearerAuth: []
paths:
  /tasks:
    post:
      summary: Create a coding task (fix or scaffold)
      tags: [tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                repo_url:
                  type: string
                  example: https://github.com/acme/auth-service
                prompt:
                  type: string
                  example: Fix login bug when user.email is undefined
                base_branch:
                  type: string
                  default: main
                task_type:
                  type: string
                  enum: [fix, scaffold]
                  default: fix
      responses:
        '201': { description: Task queued, returns full task row }
        '402': { description: Free limit or credits exhausted }
        '429': { description: Rate limited }
    get:
      summary: List your recent tasks
      tags: [tasks]
      responses:
        '200': { description: Array of task summaries }
  /tasks/{id}:
    get:
      summary: Get task + step logs
      tags: [tasks]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Task + logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  task: { type: object }
                  logs: { type: array, items: { type: object } }
  /tasks/{id}/logs/stream:
    get:
      summary: Stream step logs as Server-Sent Events
      tags: [tasks]
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: text/event-stream with events "log", "state", "end"
  /tasks/{id}/continue:
    post:
      summary: Approve a preview task and run the full PR pipeline
      tags: [tasks]
  /tasks/{id}/kill:
    post:
      summary: Force-stop a running task
      tags: [tasks]
  /tasks/{id}/feedback:
    post:
      summary: Rate the task result (improves repo memory)
      tags: [tasks]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                rating: { type: integer, minimum: 0, maximum: 5 }
                correct: { type: string, enum: [yes, partial, no] }
                reuse: { type: string, enum: [yes, no] }
                note: { type: string }
  /tasks/{id}/deploy-git:
    post:
      summary: Create a new GitHub repo and push the scaffolded files (scaffold tasks only)
      tags: [tasks]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [repo_name]
              properties:
                repo_name: { type: string }
                private: { type: boolean, default: false }
  /tasks/limits:
    get:
      summary: Current plan limits + monthly usage
      tags: [tasks]
  /me:
    get:
      summary: Profile + plan + api keys
      tags: [account]
  /me/byok:
    post:
      summary: Enable or disable BYOK mode
      tags: [account]
  /me/keys:
    post:
      summary: Add a provider API key (encrypted vault)
      tags: [account]
    get:
      summary: List saved provider keys (prefixes only)
      tags: [account]
  /me/tokens:
    post:
      summary: Issue a new Personal Access Token
      tags: [account]
      responses:
        '201':
          description: Returns the one-time token
    get:
      summary: List your tokens (no secret)
      tags: [account]
  /metrics:
    get:
      summary: Prometheus-style metrics (queue depth, tasks, cost, merged PRs)
      tags: [ops]
      security: []
  /health:
    get:
      summary: Health check
      tags: [ops]
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sr_