openapi: 3.0.1
info:
  title: Chutes API
  description: >-
    Specification of the Chutes API. Chutes is a permissionless, serverless AI
    compute platform on Bittensor Subnet 64. It exposes two REST surfaces: an
    OpenAI-compatible inference endpoint at https://llm.chutes.ai/v1 for chat
    completions and model listing across hundreds of open-source models, and a
    management API at https://api.chutes.ai for building images and deploying,
    listing, and operating chutes (serverless AI apps). All requests authenticate
    with a Bearer API key (prefix `cpk_`).
  termsOfService: https://chutes.ai/terms
  contact:
    name: Chutes Support
    url: https://chutes.ai/docs
  version: '1.0'
servers:
  - url: https://llm.chutes.ai/v1
    description: OpenAI-compatible LLM inference endpoint (chat completions, models).
  - url: https://api.chutes.ai
    description: Management API for chutes and images.
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: OpenAI-compatible chat completions.
  - name: Models
    description: List models available on the Chutes network.
  - name: Chutes
    description: Deploy, list, retrieve, update, and delete chutes.
  - name: Images
    description: Build, list, retrieve, and delete container images.
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      servers:
        - url: https://llm.chutes.ai/v1
      tags:
        - Chat
      summary: Create a chat completion.
      description: >-
        OpenAI-compatible chat completions. Reachable for any model currently
        running on the Chutes network via the shared endpoint
        https://llm.chutes.ai/v1. Set `stream: true` to receive the response as
        Server-Sent Events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events stream of `chat.completion.chunk` objects
                  when `stream` is true, terminated by `data: [DONE]`.
        '401':
          description: Unauthorized - missing or invalid API key.
        '422':
          description: Validation error.
        '429':
          description: Too Many Requests - rate or quota limit exceeded.
  /models:
    get:
      operationId: listModels
      servers:
        - url: https://llm.chutes.ai/v1
      tags:
        - Models
      summary: List available models.
      description: Lists the live models currently reachable on the Chutes network.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListModelsResponse'
  /chutes/:
    get:
      operationId: listChutes
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: List chutes.
      description: List (and optionally filter/paginate) chutes.
      parameters:
        - name: include_public
          in: query
          required: false
          schema:
            type: boolean
        - name: template
          in: query
          required: false
          schema:
            type: string
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: image
          in: query
          required: false
          schema:
            type: string
        - name: slug
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChuteList'
        '422':
          description: Validation error.
    post:
      operationId: deployChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Deploy a chute.
      description: >-
        Standard deploy from the Chutes development kit (CDK). Stores the chute
        code, image reference, node selector, and configuration, then schedules
        it onto suitable miner GPU capacity.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployChuteRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chute'
        '422':
          description: Validation error.
  /chutes/{chute_id_or_name}:
    get:
      operationId: getChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Get a chute.
      description: Retrieve a chute's details by ID or name.
      parameters:
        - name: chute_id_or_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chute'
        '404':
          description: Not found.
    put:
      operationId: updateChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Update a chute.
      description: >-
        Update chute metadata such as readme, tagline, logo, and autoscaling
        settings.
      parameters:
        - name: chute_id_or_name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateChuteRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chute'
        '422':
          description: Validation error.
  /chutes/{chute_id}:
    delete:
      operationId: deleteChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Delete a chute.
      description: Remove a chute by ID.
      parameters:
        - name: chute_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '404':
          description: Not found.
  /chutes/code/{chute_id}:
    get:
      operationId: getChuteCode
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Get chute code.
      description: Load a chute's source code by ID or name.
      parameters:
        - name: chute_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
  /chutes/{chute_id}/hf_info:
    get:
      operationId: getChuteHfInfo
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Get Hugging Face info.
      description: >-
        Return the Hugging Face repo_id and revision for a chute, used by miners
        to pre-download model weights.
      parameters:
        - name: chute_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HfInfo'
  /chutes/warmup/{chute_id_or_name}:
    get:
      operationId: warmupChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Warm up a chute.
      description: Activate a chute (cold start) with an optional quick status check.
      parameters:
        - name: chute_id_or_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /chutes/utilization:
    get:
      operationId: getChutesUtilization
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Get utilization.
      description: Obtain utilization data from recent capacity logs.
      responses:
        '200':
          description: OK
  /chutes/vllm:
    post:
      operationId: deployVllmChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Deploy a templated vLLM chute.
      description: Deploy a templated vLLM model as a chute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployTemplateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chute'
  /chutes/diffusion:
    post:
      operationId: deployDiffusionChute
      servers:
        - url: https://api.chutes.ai
      tags:
        - Chutes
      summary: Deploy a templated diffusion chute.
      description: Deploy a templated diffusion (image generation) model as a chute.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeployTemplateRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Chute'
  /images/:
    get:
      operationId: listImages
      servers:
        - url: https://api.chutes.ai
      tags:
        - Images
      summary: List images.
      description: List (and optionally filter/paginate) images.
      parameters:
        - name: include_public
          in: query
          required: false
          schema:
            type: boolean
        - name: name
          in: query
          required: false
          schema:
            type: string
        - name: tag
          in: query
          required: false
          schema:
            type: string
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageList'
        '422':
          description: Validation error.
    post:
      operationId: createImage
      servers:
        - url: https://api.chutes.ai
      tags:
        - Images
      summary: Create an image.
      description: >-
        Store image metadata in the database and kick off an asynchronous image
        build that is published to the Chutes registry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImageRequest'
      responses:
        '202':
          description: Accepted - build started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '422':
          description: Validation error.
  /images/{image_id_or_name}:
    get:
      operationId: getImage
      servers:
        - url: https://api.chutes.ai
      tags:
        - Images
      summary: Get an image.
      description: Load a single image by ID or name.
      parameters:
        - name: image_id_or_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Image'
        '422':
          description: Validation error.
    delete:
      operationId: deleteImage
      servers:
        - url: https://api.chutes.ai
      tags:
        - Images
      summary: Delete an image.
      description: Delete an image by ID or name:tag.
      parameters:
        - name: image_id_or_name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
        '422':
          description: Validation error.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Chutes API key passed as `Authorization: Bearer cpk_...`. Management
        endpoints alternatively accept a Bittensor hotkey signature
        (X-Chutes-Hotkey, X-Chutes-Signature, X-Chutes-Nonce).
  schemas:
    CreateChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Model identifier, e.g. `deepseek-ai/DeepSeek-V3-0324`.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        max_tokens:
          type: integer
        temperature:
          type: number
          format: float
        top_p:
          type: number
          format: float
        stream:
          type: boolean
          default: false
        stop:
          type: array
          items:
            type: string
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          type: string
    CreateChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/ChatMessage'
              finish_reason:
                type: string
        usage:
          $ref: '#/components/schemas/Usage'
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    ListModelsResponse:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: model
        created:
          type: integer
        owned_by:
          type: string
    Chute:
      type: object
      properties:
        chute_id:
          type: string
        name:
          type: string
        slug:
          type: string
        tagline:
          type: string
        readme:
          type: string
        image:
          type: string
        public:
          type: boolean
        created_at:
          type: string
          format: date-time
    ChuteList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Chute'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    DeployChuteRequest:
      type: object
      required:
        - name
        - image
      properties:
        name:
          type: string
        image:
          type: string
          description: Image ID or name:tag the chute runs from.
        code:
          type: string
          description: Chute source code from the CDK.
        node_selector:
          type: object
          description: GPU / node requirements (e.g. gpu_count, min_vram_gb).
          additionalProperties: true
        public:
          type: boolean
    UpdateChuteRequest:
      type: object
      properties:
        readme:
          type: string
        tagline:
          type: string
        logo:
          type: string
        scaling:
          type: object
          additionalProperties: true
    DeployTemplateRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: Hugging Face model repo to template-deploy.
        node_selector:
          type: object
          additionalProperties: true
        public:
          type: boolean
    HfInfo:
      type: object
      properties:
        repo_id:
          type: string
        revision:
          type: string
    Image:
      type: object
      properties:
        image_id:
          type: string
        name:
          type: string
        tag:
          type: string
        status:
          type: string
          description: Build status (e.g. building, built, error).
        public:
          type: boolean
        created_at:
          type: string
          format: date-time
    ImageList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Image'
        total:
          type: integer
        page:
          type: integer
        limit:
          type: integer
    CreateImageRequest:
      type: object
      required:
        - name
        - tag
      properties:
        name:
          type: string
        tag:
          type: string
        dockerfile:
          type: string
          description: Dockerfile or build definition for the image.
        public:
          type: boolean