---
title: "Create a run (non-streaming)"
method: POST
path: "/v1/threads/{threadId}/runs"
---

# Create a run (non-streaming)

`POST /v1/threads/{threadId}/runs`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/threads/{threadId}/runs`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Execute a conversation with the assistant and return the complete response. Automatically generates a thread title if this is the first message.

## Path parameters

- `threadId` string, uuid, required: Unique identifier of the thread

## Request body

- CreateThreadRunRequest
  - `assistant_id` string, uuid, required: Unique identifier of the assistant
  - `messages` object[], required: Array of messages to process
    - `role` 'user' | 'assistant' | 'system', required: Role of the message sender. `system` is only accepted from API-key authenticated requests.
    - `content` string, required: Content of the message
    - `id` string: Optional unique identifier for the message. Used as the deduplication key for the turn, so two distinct ids are two turns and a repeated id is one. Reserved prefix: an id beginning with `rbc:` must be `rbc:<uuid>:<uuid>`, the form the SDK mints for a component click.
    - `attachments` object[]
      - `name` string, required: Name of the attached file
      - `url` string, uri, required: URL of the attached file
      - `contentType` string, required: MIME type of the attached file
  - `config` object: Configuration options for the run
    - `userContext` object: User context metadata for scoping tool calls and retrievals

## Response `200`

Default Response

- CreateThreadRunResponse
  - `message` object, required
    - `id` string: ID of the response message
    - `content` string, required: Content of the assistant's response

## Other responses

- `401`: The credential is missing, malformed, or expired. `code` discriminates the cause; only `pass_expired` is renewable.
- `403`: The presented credential is not permitted to perform this action against this agent.
- `404`: The thread does not exist, or it is not accessible with the presented credential. Absent and inaccessible threads are deliberately indistinguishable. Also returned when `assistant_id` does not name an agent in your organization.
- `422`: The request cannot be processed by the addressed agent: either its type cannot be executed by this API, or a message carries more file attachments than the agent's runtime accepts. Also returned when a request authenticated with a widget session pass includes a `system` message. Raised before the response begins, so it applies to the streaming variant too. A failure discovered *during* a turn cannot use this status — the response has already begun — and is reported per the streaming error contract instead.
- `429`: Rate limit exceeded for this organization and agent. Retry after the number of seconds in the `Retry-After` header. Every response — not only a 429 — carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`.

---

[API](https://skmtc.dev/runbear/apis/runbear-api.md) - [All operations](https://skmtc.dev/runbear/apis/runbear-api/llms.txt) - [OpenAPI document](https://skmtc.dev/runbear/apis/runbear-api/revisions/c6a9c3066a5a?raw)