openapi: 3.1.0
info:
  title: ShipRepo API — Public
  version: 1.0.0
  description: |
    Subset of the ShipRepo API safe to publish. Covers task creation, status, streaming logs, results, and BYOK management.

    Two token kinds:
      - Full token (sr_...) from cp.shiprepo.com/tokens.html — full pipeline.
      - Demo token (sr_demo_...) from POST /v1/demo/token — file-level insights only (no code fix, no PR), 2-task lifetime.

    Bearer on every request: `Authorization: Bearer sr_...`
servers:
  - url: https://api.shiprepo.com
security:
  - bearerAuth: []

paths:
  /v1/demo/token:
    post:
      summary: Claim a demo token (no signup needed)
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        '201':
          description: Returns demo token (valid 30 days, 2 tasks max, file insights only)
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  limits: { type: object }

  /v1/tasks:
    post:
      summary: Create a task
      tags: [tasks]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                repo_url:
                  type: string
                  format: uri
                  example: https://github.com/expressjs/express
                prompt:
                  type: string
                  example: fix the memory leak in LiveFeed when unmounted
                base_branch:
                  type: string
                  default: main
                task_type:
                  type: string
                  enum: [fix, scaffold]
                  default: fix
      responses:
        '201':
          description: Task queued
        '402':
          description: Limits — FREE_LIMIT_REACHED · NO_CREDITS · DEMO_LIMIT_REACHED · DEMO_PUBLIC_REPOS_ONLY
        '429':
          description: Rate limited — 20 POSTs / 60s per account
    get:
      summary: List your recent tasks
      tags: [tasks]

  /v1/tasks/{id}:
    get:
      summary: Get a task and its step logs
      tags: [tasks]
      parameters:
        - name: id
          in: path
          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 }

  /v1/tasks/{id}/logs/stream:
    get:
      summary: Server-Sent Events stream of step logs
      tags: [tasks]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: text/event-stream — events "log", "state", "end"

  /v1/tasks/{id}/feedback:
    post:
      summary: Rate a completed task (feeds 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 }

  /v1/tasks/limits:
    get:
      summary: Your plan limits and monthly usage

  /v1/me:
    get:
      summary: Profile (email, plan, credits, connected GitHub, BYOK flag)

  /v1/me/byok:
    post:
      summary: Enable or disable BYOK mode
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled: { type: boolean }

  /v1/me/keys:
    post:
      summary: Add a provider API key (encrypted vault)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [provider, api_key]
              properties:
                provider: { type: string, enum: [openai, together, fireworks] }
                api_key: { type: string }
                base_url: { type: string, format: uri }
                default_model: { type: string }
    get:
      summary: List saved provider keys (metadata only, no secrets)

  /health:
    get:
      summary: Health check
      security: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sr_