---
title: "Run headless assistant orchestration with tool execution"
method: POST
path: "/orchestrations"
tags: ["Inference"]
---

# Run headless assistant orchestration with tool execution

`POST /orchestrations`

Optionally loads assistant settings by `assistant_id`, executes server-side MCP tool calls, and continues generation until the model returns a final response.

## Request body

- object
  - `assistant_id` string — Optional assistant id to load system prompt/model hint from
  - `project_id` string, nullable — Reserved for future parity; MCP-only execution currently
  - `model` string — Optional model override. If omitted, uses assistant's model hint or the first running local model.
  - `messages` object[], required
    - `role` 'system' | 'user' | 'assistant', required
    - `content` string, required
  - `stream` boolean — Streaming is not supported for this endpoint.
  - `max_turns` integer — Maximum tool-calling turns before giving up.

## Response `200`

Completion result

- ChatCompletionResponseDto — Response from `POST /v1/chat/completion`.
  - `id` string, required — Unique identifier for the completion.
  - `object` 'chat.completion', required
  - `created` integer, required — Unix timestamp of creation.
  - `model` string, required — Model used for the completion.
  - `choices` ChoiceDto[], required — List of generated choices.
    - `index` integer, required
    - `message` ChatCompletionMessage, required — A single turn in a chat conversation.
      - `role` 'system' | 'assistant' | 'user', required — Who sent the message.
      - `content` string, required — The textual content of the message.
    - `finish_reason` string, required — Why the generation stopped (e.g., `stop`, `length`, `model`).
    - `logprobs` ChatChoiceLogprobs[], nullable — Log probability information for the choice, if requested.
      - `id` integer — The token ID.
      - `token` string — The most likely token.
      - `logprob` number — The log probability of the most likely token.
      - `prob` number — The probability of the most likely token (if post_sampling_probs is true).
      - `bytes` integer[] — The most likely token represented as a list of bytes.
      - `top_logprobs` LogprobContent[] — List of the most likely tokens and their log probs.
        - `id` integer — The token ID.
        - `token` string — The token string.
        - `logprob` number — The log probability of this token.
        - `prob` number — The probability of this token (if post_sampling_probs is true).
        - `bytes` integer[] — The token represented as a list of bytes.
      - `top_probs` LogprobContent[] — List of the most likely tokens and their probs (if post_sampling_probs is true).
        - `id` integer — The token ID.
        - `token` string — The token string.
        - `logprob` number — The log probability of this token.
        - `prob` number — The probability of this token (if post_sampling_probs is true).
        - `bytes` integer[] — The token represented as a list of bytes.
  - `usage` UsageDto, required — Token usage statistics.
    - `prompt_tokens` integer, required
    - `completion_tokens` integer, required
    - `total_tokens` integer, required
  - `system_fingerprint` string — Fingerprint of the system configuration used.
  - `generation_settings` object — The generation settings used for the completion.
  - `prompt` string — The processed prompt.
  - `truncated` boolean — True if the context size was exceeded.
  - `tokens_cached` integer — Number of tokens from the prompt which were reused from a cache.
  - `tokens_evaluated` integer — Number of tokens evaluated in total from the prompt.

## Changes

- **2026-07-17** `8e64bd346c2f` — 1 info
  - endpoint added
- **2025-09-19** `97bc26aa608a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/janhq/apis/jan-api-server-endpoints/changes/orchestrations/post.md)

---

[API](https://skmtc.dev/janhq/apis/jan-api-server-endpoints.md) · [All operations](https://skmtc.dev/janhq/apis/jan-api-server-endpoints/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/janhq/jan-api-server-endpoints/revisions/8e64bd346c2f/schema)