openapi.yaml

openapi: 3.1.0
info:
  title: Ripple API
  version: 0.1.0
  description: Local JSON API for bot-driven task management.
servers:
  - url: http://localhost:8080
paths:
  /api:
    get:
      summary: Discover API capabilities and bot rules
      responses:
        "200":
          description: API discovery document
  /api/docs:
    get:
      summary: Bot-facing Markdown usage guide
      responses:
        "200":
          description: Markdown documentation
  /api/openapi.yaml:
    get:
      summary: OpenAPI schema
      responses:
        "200":
          description: OpenAPI YAML
  /api/projects:
    get:
      summary: List projects
      responses:
        "200":
          description: Projects
    post:
      summary: Create a project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                id:
                  type: string
                name:
                  type: string
                prefix:
                  type: string
                workingDirectory:
                  type: string
                  description: Absolute path to the repo or folder where Codex should work (agent mode).
                deliveryMode:
                  type: string
                  enum: [agent, backlog]
                  description: agent = one-repo delivery loop (default). backlog = portfolio planning across repos; agent queue runs disabled.
                autonomyMode:
                  type: string
                  enum: [autonomous, supervised]
                  description: How far automation may go without a human (agent mode). Defaults to autonomous. Invalid values normalize to autonomous.
                defaultBranchOverride:
                  type: string
                  description: Optional default branch name when auto-detect is wrong. Empty means auto-detect.
                prBaseBranch:
                  type: string
                  description: Optional PR base branch. Empty uses the resolved default branch.
                qualityGateMode:
                  type: string
                  enum: [strict, warn]
                  description: strict fails on quality gate errors; warn logs and continues. Defaults to strict.
                deleteBranchOnMerge:
                  type: boolean
                  description: Delete the feature branch after merge. Defaults to true.
                branchNameTemplate:
                  type: string
                  description: Feature branch template. Placeholders {id}, {slug}, {prefix}. Must include {id}. Defaults to ripple/{id}-{slug}.
      responses:
        "201":
          description: Created project
  /api/epics:
    get:
      summary: List epics
      parameters:
        - name: projectId
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Epics
    post:
      summary: Create an epic
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projectId, name]
              properties:
                id:
                  type: string
                projectId:
                  type: string
                name:
                  type: string
                description:
                  type: string
      responses:
        "201":
          description: Created epic
  /api/stories:
    get:
      summary: List stories
      description: Closed stories are excluded unless showClosed=1 or status=closed.
      parameters:
        - name: projectId
          in: query
          schema:
            type: string
        - name: epicId
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/StoryStatus"
        - name: showClosed
          in: query
          schema:
            type: string
            enum: ["1"]
        - name: targetRepo
          in: query
          schema:
            type: string
          description: Filter by story targetRepo (portfolio multi-repo targeting).
        - name: updatedSince
          in: query
          schema:
            type: string
          description: RFC3339 or YYYY-MM-DD. Returns stories with updated_at on or after this time.
      responses:
        "200":
          description: Stories
    post:
      summary: Create a story
      description: Creates or reuses a project/epic when projectName or epicName are supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, description]
              properties:
                title:
                  type: string
                description:
                  type: string
                  description: Markdown description.
                status:
                  $ref: "#/components/schemas/BotWritableStatus"
                projectId:
                  type: string
                projectName:
                  type: string
                projectPrefix:
                  type: string
                workingDirectory:
                  type: string
                  description: Fills the project's working directory when the project has none.
                projectPath:
                  type: string
                  deprecated: true
                  description: Alias for workingDirectory.
                epicId:
                  type: string
                epicName:
                  type: string
                targetRepo:
                  type: string
                  description: Optional target repository name for portfolio/backlog projects.
      responses:
        "201":
          description: Created story
  /api/stories/{id}:
    get:
      summary: Get a story
      parameters:
        - $ref: "#/components/parameters/StoryID"
      responses:
        "200":
          description: Story
    patch:
      summary: Update story details
      parameters:
        - $ref: "#/components/parameters/StoryID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                epicId:
                  type: string
                  description: Empty string removes the epic.
                targetRepo:
                  type: string
                  description: Target repository name. Empty string clears it.
      responses:
        "200":
          description: Updated story
  /api/stories/{id}/status:
    patch:
      summary: Move a story through the bot-writable workflow
      description: Bots may set backlog, in_progress, or done. queued, in_review, and closed are not bot-writable.
      parameters:
        - $ref: "#/components/parameters/StoryID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  $ref: "#/components/schemas/BotWritableStatus"
      responses:
        "200":
          description: Updated story
        "400":
          description: Invalid status
  /api/stories/{id}/events:
    get:
      summary: Get story event history
      parameters:
        - $ref: "#/components/parameters/StoryID"
      responses:
        "200":
          description: Story events
components:
  parameters:
    StoryID:
      name: id
      in: path
      required: true
      schema:
        type: string
      example: ACM-001
  schemas:
    StoryStatus:
      type: string
      enum: [backlog, queued, in_progress, in_review, done, closed]
    BotWritableStatus:
      type: string
      enum: [backlog, in_progress, done]