Kairon Initiatives API

openapi: 3.2.0
info:
  title: Kairon Initiatives API
  description: B2B agentic go-to-market platform
  version: 0.0.0
  contact: {}
servers: []
security:
- api-key: []
tags:
- name: initiatives
paths:
  /api/initiatives:
    get:
      operationId: InitiativesController_list
      parameters:
      - name: status
        required: false
        in: query
        schema:
          type: string
          enum:
          - draft
          - active
          - completed
          - canceled
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller list
      x-summary-source: derived
    post:
      operationId: InitiativesController_create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiativeCreateDto'
      responses:
        '201':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller create
      x-summary-source: derived
  /api/initiatives/{id}:
    get:
      operationId: InitiativesController_get
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller get
      x-summary-source: derived
    patch:
      operationId: InitiativesController_update
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiativeUpdateDto'
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller update
      x-summary-source: derived
    delete:
      operationId: InitiativesController_remove
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller remove
      x-summary-source: derived
  /api/initiatives/{id}/checkpoints:
    get:
      operationId: InitiativesController_checkpoints
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller checkpoints
      x-summary-source: derived
    post:
      operationId: InitiativesController_publishCheckpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckpointPublishDto'
      responses:
        '201':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller publish checkpoint
      x-summary-source: derived
  /api/initiatives/{id}/checkpoints/{checkpointId}:
    patch:
      operationId: InitiativesController_updateCheckpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: checkpointId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckpointUpdateDto'
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller update checkpoint
      x-summary-source: derived
    delete:
      operationId: InitiativesController_removeCheckpoint
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      - name: checkpointId
        required: true
        in: path
        schema:
          type: string
      responses:
        '204':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller remove checkpoint
      x-summary-source: derived
  /api/initiatives/{id}/owner:
    put:
      operationId: InitiativesController_setOwner
      parameters:
      - name: id
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitiativeOwnerSetDto'
      responses:
        '200':
          description: ''
      tags:
      - initiatives
      summary: Initiatives controller set owner
      x-summary-source: derived
components:
  schemas:
    InitiativeUpdateDto:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Short, scannable name for the initiative — "Expansión Centroamérica".
          x-nestjs_zod-uses-3-point-1-syntax: true
        body:
          description: 'The thinking, in markdown: what it tries, why, what would prove it worked, and what has been learned. Free-form on purpose — write what an operator would want to reread in three weeks. Put a teammate on a step by mentioning them: `[@Ana](#kairon-ana@co.com)`, a normal markdown link whose destination is `#kairon-` plus their user id, email, or name (spaces as `+`). It is stored as their id; a name nobody here matches, or one two teammates share, is refused. `seat_list` names them.'
          anyOf:
          - type: string
            maxLength: 20000
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        status:
          description: '`draft` while it is being shaped, `active` once it is being worked.'
          type: string
          enum:
          - draft
          - active
          - completed
          - canceled
          x-nestjs_zod-uses-3-point-1-syntax: true
        priority:
          description: 0 is highest. Lower sorts first, matching every other priority in Kairon.
          anyOf:
          - type: integer
            minimum: 0
            maximum: 3
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        startDate:
          description: '`YYYY-MM-DD`, this century. An initiative starts on a date, not at a moment.'
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        endDate:
          description: '`YYYY-MM-DD`, this century. When the initiative should have paid off, or be called. Must not be before `startDate`.'
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
    InitiativeOwnerSetDto:
      type: object
      properties:
        userId:
          anyOf:
          - type: string
            minLength: 1
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
      required:
      - userId
    CheckpointPublishDto:
      type: object
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 20000
          description: 'What happened and the ONE thing to do next, in markdown. Say the numbers you read and how they compare to this org’s own baseline, and whether the last checkpoint’s recommendation was actually done. To put a teammate’s name on a next step, mention them: `[@Ana](#kairon-ana@co.com)` — a normal markdown link whose destination is `#kairon-` plus their user id, email, or name (spaces as `+`). Whichever you use is stored as their id, and a name nobody here matches, or one two teammates share, is refused rather than saved as prose. Read user ids and names off `seat_list`.'
        health:
          type: string
          enum:
          - on_track
          - at_risk
          - off_track
          description: 'The verdict, frozen at publish: `on_track`, `at_risk` or `off_track`. Judge VOLUME before rates — a low number of sends is not a bad result, it is not a result yet.'
      required:
      - body
      - health
    InitiativeCreateDto:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: Short, scannable name for the initiative — "Expansión Centroamérica".
          x-nestjs_zod-uses-3-point-1-syntax: true
        body:
          description: 'The thinking, in markdown: what it tries, why, what would prove it worked, and what has been learned. Free-form on purpose — write what an operator would want to reread in three weeks. Put a teammate on a step by mentioning them: `[@Ana](#kairon-ana@co.com)`, a normal markdown link whose destination is `#kairon-` plus their user id, email, or name (spaces as `+`). It is stored as their id; a name nobody here matches, or one two teammates share, is refused. `seat_list` names them.'
          anyOf:
          - type: string
            maxLength: 20000
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        status:
          description: '`draft` while it is being shaped, `active` once it is being worked.'
          type: string
          enum:
          - draft
          - active
          - completed
          - canceled
          x-nestjs_zod-uses-3-point-1-syntax: true
        priority:
          description: 0 is highest. Lower sorts first, matching every other priority in Kairon.
          anyOf:
          - type: integer
            minimum: 0
            maximum: 3
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        startDate:
          description: '`YYYY-MM-DD`, this century. An initiative starts on a date, not at a moment.'
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
        endDate:
          description: '`YYYY-MM-DD`, this century. When the initiative should have paid off, or be called. Must not be before `startDate`.'
          anyOf:
          - type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          - type: 'null'
          x-nestjs_zod-uses-3-point-1-syntax: true
          x-nestjs_zod-empty-type: true
      required:
      - name
    CheckpointUpdateDto:
      type: object
      properties:
        body:
          type: string
          minLength: 1
          maxLength: 20000
          description: 'What happened and the ONE thing to do next, in markdown. Say the numbers you read and how they compare to this org’s own baseline, and whether the last checkpoint’s recommendation was actually done. To put a teammate’s name on a next step, mention them: `[@Ana](#kairon-ana@co.com)` — a normal markdown link whose destination is `#kairon-` plus their user id, email, or name (spaces as `+`). Whichever you use is stored as their id, and a name nobody here matches, or one two teammates share, is refused rather than saved as prose. Read user ids and names off `seat_list`.'
        health:
          type: string
          enum:
          - on_track
          - at_risk
          - off_track
          description: 'The verdict, frozen at publish: `on_track`, `at_risk` or `off_track`. Judge VOLUME before rates — a low number of sends is not a bad result, it is not a result yet.'
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'A Kairon API key (Settings → Integrations → API access), sent as `x-api-key`. NOT an `Authorization: Bearer` token — that header belongs to the separate /mcp door and is ignored here.'
    session:
      type: apiKey
      in: cookie
      name: better-auth.session_token