todowindy/api/openapi.yaml

openapi: 3.0.3
info:
  title: TodoWindy API
  version: 0.1.0
servers:
  - url: http://localhost:8080
paths:
  /healthz:
    get:
      summary: Health check
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
  /ingest:
    post:
      summary: Ingest natural language instruction into tasks and schedule suggestions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                timezone:
                  type: string
                now:
                  type: string
      responses:
        '200':
          description: Plan created
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan_id:
                    type: string
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  suggestions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Suggestion'
  /tasks:
    get:
      summary: List tasks
      parameters:
        - in: query
          name: start
          schema: { type: string }
        - in: query
          name: end
          schema: { type: string }
        - in: query
          name: status
          schema:
            type: string
            enum: [pending, scheduled, done]
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
    post:
      summary: Create task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskCreate'
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{id}:
    get:
      summary: Get one task
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
    patch:
      summary: Update task
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaskUpdate'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
  /tasks/{id}/complete:
    post:
      summary: Complete task
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  task:
                    $ref: '#/components/schemas/Task'
  /calendar:
    get:
      summary: Calendar items grouped by day
      parameters:
        - in: query
          name: start
          required: true
          schema: { type: string }
        - in: query
          name: end
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  days:
                    type: array
                    items:
                      $ref: '#/components/schemas/Day'
components:
  schemas:
    Task:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        notes: { type: string }
        status:
          type: string
          enum: [pending, scheduled, done, canceled]
        priority: { type: integer }
        tags:
          type: array
          items: { type: string }
        estimate_minutes: { type: integer, nullable: true }
        due_at: { type: string, nullable: true }
        scheduled_start: { type: string, nullable: true }
        scheduled_end: { type: string, nullable: true }
        recurrence_rule: { type: string, nullable: true }
        source_text: { type: string }
        tz: { type: string }
        created_at: { type: string }
        updated_at: { type: string }
    TaskCreate:
      type: object
      properties:
        title: { type: string }
        notes: { type: string }
        status: { type: string }
        priority: { type: integer }
        tags:
          type: array
          items: { type: string }
        estimate_minutes: { type: integer, nullable: true }
        due_at: { type: string, nullable: true }
        scheduled_start: { type: string, nullable: true }
        scheduled_end: { type: string, nullable: true }
        recurrence_rule: { type: string, nullable: true }
        source_text: { type: string }
        tz: { type: string }
    TaskUpdate:
      type: object
      additionalProperties: true
    Suggestion:
      type: object
      properties:
        task_id: { type: string, description: The related task id for which the options are suggested }
        reason: { type: string }
        options:
          type: array
          items:
            type: object
            properties:
              start: { type: string }
              end: { type: string }
    Day:
      type: object
      properties:
        date: { type: string }
        items:
          type: array
          items:
            $ref: '#/components/schemas/CalendarItem'
        count: { type: integer }
        done_count: { type: integer }
        pending_count: { type: integer }
        scheduled_count: { type: integer }
    CalendarItem:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        start: { type: string }
        end: { type: string }
        tags:
          type: array
          items: { type: string }
        status: { type: string }