openapi: 3.1.0
info:
  title: Harmony REST API
  version: "1.0"
  summary: Agent-native Kanban where humans and AI stay in sync.
  description: |
    Harmony is a collaborative Kanban board built for humans and AI agents.
    Every endpoint accepts an API key via the `X-API-Key` header.

    - Marketing: https://gethmy.com
    - Quick setup: https://gethmy.com/llms.txt
    - Full docs: https://gethmy.com/llms-full.txt
    - MCP package: https://www.npmjs.com/package/@gethmy/mcp
    - Create an API key: https://gethmy.com/user/keys
  contact:
    name: Harmony
    email: hello@gethmy.com
    url: https://gethmy.com
  license:
    name: Proprietary
    url: https://gethmy.com/terms
servers:
  - url: https://gethmy.com/api
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Workspaces
  - name: Projects
  - name: Board
  - name: Cards
  - name: Columns
  - name: Labels
  - name: Subtasks
  - name: Links
  - name: Agents
  - name: NLU
paths:
  /v1/workspaces:
    get:
      tags: [Workspaces]
      summary: List workspaces accessible to the API key
      responses:
        "200": { description: OK }
  /v1/workspaces/{id}/projects:
    get:
      tags: [Projects]
      summary: List projects in a workspace
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200": { description: OK }
  /v1/workspaces/{id}/members:
    get:
      tags: [Workspaces]
      summary: Get workspace members
      parameters:
        - $ref: "#/components/parameters/Id"
      responses:
        "200": { description: OK }
  /v1/board/{projectId}:
    get:
      tags: [Board]
      summary: Get the full board state for a project
      parameters:
        - in: path
          name: projectId
          required: true
          schema: { type: string, format: uuid }
      responses:
        "200": { description: OK }
  /v1/cards:
    post:
      tags: [Cards]
      summary: Create a card
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [projectId, columnId, title]
              properties:
                projectId: { type: string, format: uuid }
                columnId: { type: string, format: uuid }
                title: { type: string }
                description: { type: string }
                priority: { type: string, enum: [low, medium, high, urgent] }
      responses:
        "201": { description: Created }
  /v1/cards/{id}:
    get:
      tags: [Cards]
      summary: Get a card
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses:
        "200": { description: OK }
    patch:
      tags: [Cards]
      summary: Update a card
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
                description: { type: string }
                priority: { type: string }
      responses:
        "200": { description: OK }
    delete:
      tags: [Cards]
      summary: Delete a card
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses:
        "204": { description: No Content }
  /v1/cards/{id}/move:
    post:
      tags: [Cards]
      summary: Move a card to a different column
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [columnId]
              properties:
                columnId: { type: string, format: uuid }
                position: { type: integer }
      responses:
        "200": { description: OK }
  /v1/search:
    get:
      tags: [Cards]
      summary: Search cards
      parameters:
        - in: query
          name: q
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /v1/columns:
    post:
      tags: [Columns]
      summary: Create a column
      responses: { "201": { description: Created } }
  /v1/columns/{id}:
    patch:
      tags: [Columns]
      summary: Update a column
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "200": { description: OK } }
    delete:
      tags: [Columns]
      summary: Delete a column
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "204": { description: No Content } }
  /v1/labels:
    post:
      tags: [Labels]
      summary: Create a label
      responses: { "201": { description: Created } }
  /v1/cards/{id}/labels:
    post:
      tags: [Labels]
      summary: Add a label to a card
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "200": { description: OK } }
  /v1/cards/{id}/labels/{labelId}:
    delete:
      tags: [Labels]
      summary: Remove a label from a card
      parameters:
        - $ref: "#/components/parameters/Id"
        - in: path
          name: labelId
          required: true
          schema: { type: string, format: uuid }
      responses: { "204": { description: No Content } }
  /v1/subtasks:
    post:
      tags: [Subtasks]
      summary: Create a subtask
      responses: { "201": { description: Created } }
  /v1/subtasks/{id}/toggle:
    post:
      tags: [Subtasks]
      summary: Toggle subtask completion
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "200": { description: OK } }
  /v1/subtasks/{id}:
    delete:
      tags: [Subtasks]
      summary: Delete a subtask
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "204": { description: No Content } }
  /v1/cards/{id}/links:
    get:
      tags: [Links]
      summary: Get card links
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "200": { description: OK } }
    post:
      tags: [Links]
      summary: Create a card link
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [targetId, linkType]
              properties:
                targetId: { type: string, format: uuid }
                linkType:
                  type: string
                  enum: [relates_to, blocks, duplicates, is_part_of]
      responses: { "201": { description: Created } }
  /v1/links/{id}:
    delete:
      tags: [Links]
      summary: Delete a card link
      parameters: [ { $ref: "#/components/parameters/Id" } ]
      responses: { "204": { description: No Content } }
  /v1/cards/{id}/prompt:
    get:
      tags: [Agents]
      summary: Generate an AI-ready prompt from a card
      parameters:
        - $ref: "#/components/parameters/Id"
        - in: query
          name: variant
          schema: { type: string, enum: [analysis, draft, execute] }
      responses: { "200": { description: OK } }
  /v1/nlu:
    post:
      tags: [NLU]
      summary: Process a natural-language command
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [command]
              properties:
                command: { type: string }
      responses: { "200": { description: OK } }
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key generated at https://gethmy.com/user/keys (starts with `hmy_`).
  parameters:
    Id:
      in: path
      name: id
      required: true
      schema: { type: string, format: uuid }