---
title: "Run a model with specified tools and messages."
method: POST
path: "/api/v1/{model_id}/run"
tags: ["model"]
---

# Run a model with specified tools and messages.

`POST /api/v1/{model_id}/run`

## Path parameters

- `model_id` string, required

## Query parameters

- `wait` boolean

## Request body

- ModelRunRequest
  - `tools` ChatCompletionTool[] — A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
    - `type` 'function', required — The type of the tool. Currently, only `function` is supported.
    - `function` FunctionObject, required — unresolved $ref
  - `messages` object[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool'
    - `content` string
  - `model` string, required
  - `stream` boolean, required
  - `temperature` number, nullable — An alternative to sampling with temperature, called nucleus sampling.
  - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling.
  - `n` integer, nullable — How many chat completion choices to generate for each input message.
  - `max_tokens` integer, nullable — The maximum number of tokens that can be generated in the chat completion.
  - `tool_choice` union
    - 'none' | 'auto' | 'required' — Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.
    - ChatCompletionNamedToolChoice
      - `type` 'function', required
      - `function` FunctionObject, required — unresolved $ref
  - `knowledgebases` string[] — A list of knowledgebase IDs to use in the model.

## Response `200`

Successful response

- ModelRunResponse
  - `id` string
  - `object` string
  - `created` integer
  - `model` string
  - `choices` object[]
    - `index` integer
    - `message` object
      - `role` string
      - `content` string
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
  - `toolCalls` object[]
    - `type` 'function'
    - `function` FunctionObject — unresolved $ref

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

## Changes

- **2024-07-09** `93c619d49ece` — 1 info
  - added the new optional request property `knowledgebases`
- **2024-06-12** `13377337b826` — 2 warning, 2 info
  - removed the optional property `toolCalls/items/name` from the response with the `200` status
  - removed the optional property `toolCalls/items/parameters` from the response with the `200` status
  - added the optional property `toolCalls/items/function` to the response with the `200` status
  - added the optional property `toolCalls/items/type` to the response with the `200` status
- **2024-06-11** `56ef2faeac8e` — 1 info
  - api tag `model` added

[Change history](https://skmtc.dev/propulsion-ai/apis/propulsionai-api/changes/api/v1/:model_id/run/post.md)

---

[API](https://skmtc.dev/propulsion-ai/apis/propulsionai-api.md) · [All operations](https://skmtc.dev/propulsion-ai/apis/propulsionai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propulsion-ai/apis/propulsionai-api/revisions/93c619d49ece?raw)