openapi: 3.0.3
info:
  version: '0.1'
  title: Kwaai pAI-OS API
  description: 'API for pAI-OS admin interfaces (web, app) to backend services.'
  termsOfService: 'https://paios.org'
  contact:
    name: Kwaai
    url: 'https://www.kwaai.ai'
    email: contact@kwaai.ai
  license:
    url: 'https://github.com/pAI-OS/paios/blob/main/LICENSE'
    name: MIT
servers:
  - url: /api/v1
    description: Local instance
paths:
  /abilities:
    get:
      tags:
        - Abilities Management
      summary: Retrieve all abilities
      description: Retrieve the information of all abilities.
      parameters:
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/range'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Ability'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
  '/abilities/{id}':
    get:
      tags:
        - Abilities Management
      summary: Retrieve ability by id
      description: Retrieve the information of the ability with the matching ability ID.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Ability'
    parameters:
      - $ref: '#/components/parameters/snake_id'
  '/abilities/{id}/install':
    post:
      tags:
        - Abilities Management
      summary: Install ability
      description: Installs the ability with the matching ability id to the specified or latest version.
      operationId: backend.api.AbilitiesView.install
      parameters:
        - $ref: '#/components/parameters/snake_id'
        - $ref: '#/components/parameters/versionOptional'
      responses:
        '200':
          description: Ability installed
        '400':
          description: Invalid request
        '404':
          description: Ability not found
  '/abilities/{id}/upgrade':
    post:
      tags:
        - Abilities Management
      summary: Upgrade ability
      description: Upgrades the ability with the matching ability id to the specified or latest version.
      operationId: backend.api.AbilitiesView.upgrade
      parameters:
        - $ref: '#/components/parameters/snake_id'
        - $ref: '#/components/parameters/versionOptional'
      responses:
        '200':
          description: Ability upgraded
        '400':
          description: Invalid request
        '404':
          description: Ability not found
  '/abilities/{id}/uninstall':
    post:
      tags:
        - Abilities Management
      summary: Uninstall ability
      description: Uninstalls the ability with the matching ability id.
      operationId: backend.api.AbilitiesView.uninstall
      parameters:
        - $ref: '#/components/parameters/snake_id'
      responses:
        '200':
          description: Ability uninstalled
        '400':
          description: Invalid request
        '404':
          description: Ability not found
  '/abilities/{id}/start':
    post:
      tags:
        - Abilities Management
      summary: Start ability
      description: Starts the ability with the matching ability ID.
      operationId: backend.api.AbilitiesView.start
      responses:
        '200':
          description: OK
    parameters:
      - $ref: '#/components/parameters/snake_id'
  '/abilities/{id}/stop':
    post:
      tags:
        - Abilities Management
      summary: Stop ability
      description: Stops the ability with the matching ability ID.
      operationId: backend.api.AbilitiesView.stop
      responses:
        '200':
          description: OK
    parameters:
      - $ref: '#/components/parameters/snake_id'
  '/abilities/{id}/dependencies/{dependency_id}/download':
    post:
      tags:
        - Abilities Management
      summary: Start download
      description: Downloads an ability's dependency.
      responses:
        '200':
          description: Download started
    parameters:
      - $ref: '#/components/parameters/snake_id'
      - name: dependency_id
        in: path
        description: id of the dependency
        required: true
        schema:
          $ref: '#/components/schemas/kebab-snake_id'
  '/abilities/{id}/dependencies/{dependency_id}/install':
    post:
      tags:
        - Abilities Management
      summary: Start dependency install
      description: Installs an ability's dependency.
      operationId: backend.api.AbilitiesView.install_dependency
      responses:
        '200':
          description: Install started
    parameters:
      - $ref: '#/components/parameters/snake_id'
      - name: dependency_id
        in: path
        description: id of the dependency
        required: true
        schema:
          $ref: '#/components/schemas/kebab-snake_id'
  /assets:
    get:
      tags:
        - Asset Management
      summary: Retrieve all assets
      description: Retrieve the information of all assets.
      parameters:
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/range'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Asset'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
    post:
      summary: Create new asset
      tags:
        - Asset Management
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
        '400':
          description: Missing Required Information
      description: Creates a new asset.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetCreate'
  '/assets/{id}':
    get:
      tags:
        - Asset Management
      summary: Retrieve asset by id
      description: Retrieve the information of the asset with the matching asset ID.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
    put:
      summary: Update asset by id
      tags:
        - Asset Management
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Asset'
      description: Updates the asset with the given id.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Asset'
    delete:
      summary: Delete asset by id
      description: Deletes the asset with the given id.
      tags:
        - Asset Management
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
    parameters:
      - $ref: '#/components/parameters/id'
  /channels:
    get:
      tags:
        - Channel Management
      summary: Retrieve all channels
      description: Retrieve the information of all channels.
      parameters:
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/range'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
    post:
      summary: Create new channel
      tags:
        - Channel Management
      responses:
        '200':
          description: OK
        '400':
          description: Missing Required Information
      description: Create a new channel.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChannelCreate'
  '/channels/{id}':
    get:
      tags:
        - Channel Management
      summary: Retrieve channel by id
      description: Retrieve the information of the channel with the specified id.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
    put:
      tags:
        - Channel Management
      summary: Update channel by key
      description: Updates the channel with the specified id.
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Channel'
      responses:
        '200':
          description: OK
    delete:
      tags:
        - Channel Management
      summary: Delete channel by key
      description: Delete a channel with the specified ID.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
  '/config/{key}':
    get:
      tags:
        - Configuration Management
      summary: Retrieve config by key
      description: Retrieve the config item with the specified key.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
    put:
      tags:
        - Configuration Management
      summary: Update config by key
      description: Set a config item with the specified key.
      parameters:
        - $ref: '#/components/parameters/key'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
      responses:
        '200':
          description: OK
    delete:
      tags:
        - Configuration Management
      summary: Delete config by key
      description: Delete a config item with the specified key.
      parameters:
        - $ref: '#/components/parameters/key'
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
  /downloads:
    get:
      tags:
        - Downloads Management
      summary: Retrieve all downloads
      description: Retrieve the information of all downloads.
      parameters:
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/range'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Download'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
    post:
      tags:
        - Downloads Management
      summary: Start new downloads
      description: Initiates new downloads.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/DownloadCreate'
      responses:
        '200':
          description: Downloads started
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/download'
        '400':
          description: Invalid request
  '/downloads/{id}':
    delete:
      tags:
        - Downloads Management
      summary: Delete download
      description: Deletes the download with the specified ID and removes the file.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '404':
          description: Download Not Found
  '/downloads/{id}/pause':
    post:
      tags:
        - Downloads Management
      summary: Pause download
      description: Pauses the download with the specified ID.
      operationId: backend.api.DownloadsView.pause
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Download paused
  '/downloads/{id}/resume':
    post:
      tags:
        - Downloads Management
      summary: Resume download
      description: Resumes the download with the specified ID.
      operationId: backend.api.DownloadsView.resume
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Download resumed
  /users:
    get:
      tags:
        - User Management
      summary: Retrieve all users
      description: Get all users.
      parameters:
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/range'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          headers:
            X-Total-Count:
              $ref: '#/components/headers/X-Total-Count'
    post:
      tags:
        - User Management
      summary: Create new user
      description: Create a new user.
      requestBody:
        description: Post the necessary fields for the API to create a new user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: User Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/uuid4'
        '400':
          description: Missing Required Information
        '409':
          description: Email Already Taken
  '/users/{id}':
    get:
      tags:
        - User Management
      summary: Retrieve user by id
      description: Retrieve the information of the user with the matching user ID.
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: User Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User Not Found
    delete:
      tags:
        - User Management
      summary: Delete user by id
      description: Delete the user with the specified id
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '204':
          description: No Content
        '404':
          description: Not Found
    put:
      tags:
        - User Management
      summary: Update user
      description: Update the information of an existing user.
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        description: User to update.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '200':
          description: User Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User Not Found
        '409':
          description: Email Already Taken
tags:
  - name: Abilities Management
    description: Installation and configuration of abilities
  - name: Asset Management
    description: Management of assets
  - name: Channel Management
    description: Discovery and configuration of input/output interfaces/channels
  - name: Configuration Management
    description: Management of configuration
  - name: Downloads Management
    description: Management of downloads
  - name: User Management
    description: Management of user accounts
components:
  headers:
    X-Total-Count:
      description: The total number of items
      schema:
        type: integer
      required: true
  parameters:
    id:
      name: id
      in: path
      description: id of the object
      required: true
      schema:
        $ref: '#/components/schemas/uuid4'
    snake_id:
      name: id
      in: path
      description: id of the object
      required: true
      schema:
        $ref: '#/components/schemas/snake_id'
    kebab-snake_id:
      name: id
      in: path
      description: id of the object
      required: true
      schema:
        $ref: '#/components/schemas/kebab-snake_id'
    key:
      name: key
      in: path
      description: key for config item
      required: true
      schema:
        type: string
        example: api_key
        pattern: '^[a-zA-Z0-9_]+$'
    versionOptional:
      name: version
      in: query
      description: Semantic version of the object
      required: false
      schema:
        $ref: '#/components/schemas/semVer'
    versionRequired:
      name: version
      in: query
      description: Semantic version of the object
      required: true
      schema:
        $ref: '#/components/schemas/semVer'
    sort:
      name: sort
      in: query
      description: 'Specifies the sorting order and field (e.g., ["title", "ASC"]).'
      required: false
      schema:
        type: string
        example: '["title","ASC"]'
    range:
      name: range
      in: query
      description: 'Specifies the range of results to return (e.g., [0, 24]).'
      required: false
      schema:
        type: string
        example: '[0, 24]'
    filter:
      name: filter
      in: query
      description: 'JSON string specifying the filter conditions (e.g., {"title":"bar"}).'
      required: false
      schema:
        type: string
        example: '{"title":"bar"}'
  schemas:
    snake_id:
      type: string
      minLength: 2
      maxLength: 100
      example: fetch_llama_cpp
      pattern: ^[a-z0-9]+(_[a-z0-9]+)*$
    kebab-snake_id:
      type: string
      minLength: 2
      maxLength: 100
      example: langchain-core
      pattern: ^[a-z0-9]+([_-][a-z0-9]+)*$
    semVer:
      type: string
      example: '1.1.0'
      pattern: '^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$'
    uuid4:
      type: string
      format: uuid
      example: 7bea4732-214f-40e7-9161-4e7241a2b97e
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    uuid4ReadOnly:
      type: string
      format: uuid
      readOnly: true
      example: 7bea4732-214f-40e7-9161-4e7241a2b97e
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    uri:
      type: string
      format: uri
      example: 'https://localhost:8080/v1/api'
      pattern: ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?$
    email:
      type: string
      format: email
      example: contact@kwaai.ai
      pattern: (?:[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*|"(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?|[a-z0-9-]*[a-z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\])
    name:
      type: string
      example: Kwaai
      pattern: ^[A-Za-z0-9\s\-_,.;:()!@#$%&*+=?\/\\|~^'"\[\]{}áéíóúñ©€£¥]+$
    textShort:
      type: string
      example: Lorem Ipsum
      pattern: ^[A-Za-z0-9\s\-_,.;:()!@#$%&*+=?\/\\|~^'"\[\]{}áéíóúñ©€£¥]+$
    textLong:
      type: string
      example: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
      pattern: ^[A-Za-z0-9\s\-_,.;:()!@#$%&*+=?\/\\|~^'"\[\]{}áéíóúñ©€£¥]+$
    bytes:
      type: integer
      description: Bytes
      example: 7702565088
    relativePath:
      type: string
      description: A uri-style relative path that is valid on macOS, Windows, and Linux
      example: folder/subfolder/file.txt
      pattern: '^(?![./])[^\0<>:;,?"*|]+(?:/[^\0<>:;,?"*|]+)*$'
    fileName:
      type: string
      description: A filename that is valid on macOS, Windows, and Linux
      example: Mistral-7B-Instruct-v0.3-Q8_0.gguf
      pattern: '^[^<>:;,?"*|/]+$'
    fileHash:
      type: string
      description: The hash type and hash of the file separated by colon
      example: 'sha256:404857e776114baada71a08ebd3bba79d721ec7fca99705e7e7b892ae8bc583f'
      pattern: ^[a-z0-9]+:[a-f0-9]{1,128}$
    download:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid4'
    Ability:
      type: object
      title: Ability
      description: Additional abilities (plug-ins)
      properties:
        id:
          $ref: '#/components/schemas/snake_id'
        name:
          $ref: '#/components/schemas/name'
        description:
          $ref: '#/components/schemas/textLong'
        versions:
          type: object
          properties:
            package:
              $ref: '#/components/schemas/semVer'
            product:
              type: string
              example: '0.2beta3'
              pattern: ^\d+(\.\d+)*([a-zA-Z0-9]+)?$|^[rb]\d+$|^\d+:\d+(\.\d+)*-\d+[a-zA-Z0-9]+
            latest:
              $ref: '#/components/schemas/semVer'
            installed:
              $ref: '#/components/schemas/semVer'
            available:
              type: array
              items:
                $ref: '#/components/schemas/semVer'
              uniqueItems: true
              example:
                - '0.1.0'
                - '0.2.0'
        author:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/name'
            url:
              $ref: '#/components/schemas/uri'
        maintainer:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/name'
            email:
              $ref: '#/components/schemas/email'
            url:
              $ref: '#/components/schemas/uri'
        language:
          $ref: '#/components/schemas/textShort'
        scripts:
          type: object
          properties:
            start:
              type: string
              example: chroma run
        license:
          type: string
          example: MIT
        dependencies:
          type: array
          items:
            type: object
            properties:
              type:
                $ref: '#/components/schemas/snake_id'
              id:
                $ref: '#/components/schemas/kebab-snake_id'
              name:
                $ref: '#/components/schemas/textShort'
              version:
                type: string
                example: '>=2.8'
    Asset:
      type: object
      title: Asset
      properties:
        id:
          $ref: '#/components/schemas/uuid4ReadOnly'
        user_id:
          $ref: '#/components/schemas/uuid4'
        title:
          $ref: '#/components/schemas/textShort'
        creator:
          $ref: '#/components/schemas/name'
        subject:
          $ref: '#/components/schemas/textShort'
        description:
          $ref: '#/components/schemas/textLong'
      required:
        - id
        - title
    AssetCreate:
      type: object
      title: AssetCreate
      description: Asset without id which is server-generated.
      properties:
        user_id:
          $ref: '#/components/schemas/uuid4'
        title:
          $ref: '#/components/schemas/textShort'
        creator:
          $ref: '#/components/schemas/name'
        subject:
          $ref: '#/components/schemas/textShort'
        description:
          $ref: '#/components/schemas/textShort'
      required:
        - title
    Channel:
      type: object
      title: Channel
      description: Channels (input/output)
      properties:
        id:
          $ref: '#/components/schemas/uuid4ReadOnly'
        name:
          $ref: '#/components/schemas/name'
        uri:
          $ref: '#/components/schemas/uri'
      required:
        - id
        - name
        - uri
    ChannelCreate:
      type: object
      title: Channel
      description: Channels (input/output)
      properties:
        name:
          $ref: '#/components/schemas/name'
        uri:
          $ref: '#/components/schemas/uri'
      required:
        - name
        - uri
    Config:
      title: Config
      type: object
      properties:
        key:
          type: string
          description: key for the config item.
          example: api_key
          pattern: '^[a-zA-Z0-9_]+$'
        value:
          anyOf:
            - type: string
              example: api-pk-1aEN2XGPUEKxMCcTsUZXFVEUu9GbtAjTEVc16dZBVxjfHeZACKO86vTRX
            - type: boolean
            - type: integer
            - type: number
            - type: object
            - type: array
              items:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
                  - type: object
      required:
        - key
        - value
    Download:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid4ReadOnly'
        source_url:
          $ref: '#/components/schemas/uri'
        file_name:
          $ref: '#/components/schemas/fileName'
        target_directory:
          $ref: '#/components/schemas/relativePath'
        file_hash:
          $ref: '#/components/schemas/fileHash'
        file_size:
          $ref: '#/components/schemas/bytes'
        downloaded:
          $ref: '#/components/schemas/bytes'
        progress:
          type: number
          nullable: true
          example: 10.05
        status:
          type: string
          enum:
            - downloading
            - paused
            - processing
            - completed
            - verified
            - failed
          example: downloading
        start_time:
          type: number
          nullable: true
          example: 1717398019.4677122
        transfer_rate:
          type: number
          nullable: true
          example: 49028995.95526451
      required:
        - id
        - source_url
    DownloadCreate:
      type: object
      properties:
        source_url:
          $ref: '#/components/schemas/uri'
        file_name:
          $ref: '#/components/schemas/fileName'
        target_directory:
          $ref: '#/components/schemas/relativePath'
        file_hash:
          $ref: '#/components/schemas/fileHash'
        file_size:
          $ref: '#/components/schemas/bytes'
      required:
        - source_url
    User:
      type: object
      title: User
      description: User of the system
      properties:
        id:
          $ref: '#/components/schemas/uuid4ReadOnly'
        name:
          $ref: '#/components/schemas/name'
        email:
          $ref: '#/components/schemas/email'
      required:
        - id
        - name
        - email
    UserCreate:
      type: object
      title: User
      description: User of the system
      properties:
        name:
          $ref: '#/components/schemas/name'
        email:
          $ref: '#/components/schemas/email'
      required:
        - name
        - email