---
title: "Start a session (console, by Project)"
method: POST
path: "/o/{org}/p/{project}/sessions"
tags: ["Sessions"]
---

# Start a session (console, by Project)

`POST /o/{org}/p/{project}/sessions`

## Request

- Base URL: `https://api.prix.dev`
- URL: `https://api.prix.dev/o/{org}/p/{project}/sessions`
- Auth: HTTP bearer

The console's form of `POST /o/{org}/sessions`, with the Project in the path
(`_` for none). A signed-in caller reads the console's own session shape.

## Headers

- `Idempotency-Key` string

## Request body

- SessionCreate: `agent` is required, and the repository, if any, is a `resources` URL. Any other field is `400 UNKNOWN_FIELD`; `name`, `metadata`, `output_schema`, `harness`, `agent_id` and `profile_id` are `400 FIELD_REMOVED`.
  - `agent` string: What runs: a harness (`claude`, `codex` or `opencode`), or a saved agent's id (`GET /o/{org}/agents`), which brings its harness, model, effort, instructions, skills and connections.
  - `input` union, required: The task, as a string or as content blocks. Text blocks are joined, with a blank line between them, into the prompt (at most 256 KiB, at least one text block). Every file block is stored before the run starts and downloaded into the sandbox at `/workspace/.rush/attachments/`, where the prompt names it.
    - string
    - InputBlock[]
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'image' | 'document' | 'file', required: What the file is. `image` must be an `image/*` type; `document` and `file` take any type.
          - `name` string: The file name in the sandbox. No `/`, `\`, `..`, leading `.`, or control characters. Default: the URL's last segment, else `input-<n>`, given the extension its `Content-Type` reads as when it has none.
          - `source` union, required: Where the bytes come from. `url`: a public https file Rush fetches (public addresses only, at most 3 redirects, 60 seconds, no size limit). `base64`: the bytes in the request, which is limited to 32 MB in all. `file`: an id from `POST /o/{org}/files`, for a large private file; each id rides on one run.
            - object
              - …
            - object
              - …
            - object
              - …
  - `model` string: A model `id` that GET /o/{org}/agents/available lists for this harness. Omitted: the harness default.
  - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto': Reasoning effort; must be one the model's row lists.
  - `account_id` string: Run on this one of the caller's own accounts (a Claude or ChatGPT subscription, or an Anthropic or OpenAI API key). Omitted: their subscriptions first, then their API key.
  - `strategy` 'platform': Run on Rush's models, metered on the caller's plan, instead of their own accounts.
  - `skills` SkillUrl[]: Skills the agent loads for this run, each by public URL, as a string or `{url}`: a GitHub `tree` URL to a directory holding `SKILL.md`, a URL to a `SKILL.md` file (`github.com/…/blob/…`, `raw.githubusercontent.com/…` or any https host), or a `.zip` URL. Fetched when the run is created; a GitHub source is pinned to the commit its branch or tag points at, and the pin is kept with the run. All of a run's skills pack to at most 96 KiB compressed. An unreachable URL is `422 SKILL_FETCH_FAILED`; no `SKILL.md`, a bad name or too large is `422 SKILL_INVALID`.
    - union: A skill by public URL, as a string or `{url}`.
      - string, uri
      - object
        - `url` string, uri, required
  - `connections` union[]: What this run connects to, each entry in one of three forms: - **An id** of one of the caller's own connections (`GET /me/connections`): an MCP server (connected with a token, by OAuth, or with no auth), a Google or Microsoft product (Gmail, Outlook, OneDrive, ...) of one account, or a GitLab account. Secrets are never named: a session gets every secret of its Project (`/o/{org}/secrets`). - **A name** of one of them, the `name` `GET /me/connections` lists: the name the caller gave an MCP server (`"deepwiki"`, `"EXA_API_KEY"`), or the provider of an account or a built-in connector, which `GET /me/connections` lists as `{type: "app", name: "linear"}` (`"linear"`, `"gmail"`). Only the caller's own rows match, and only user-level ones or ones in this run's Project. A name that matches two of them is `422 CONNECTION_AMBIGUOUS`, whose message lists their ids; send one id instead. - **An inline MCP server** `{url, name?, auth?}`, used by this run and its follow-ups only and never added to `/me/connections`. `url` is a streamable HTTP endpoint on https whose host resolves to public addresses only (else `422 MCP_SERVER_URL_INVALID`). `auth` is the shape `POST /me/connections` takes: `{mode: "bearer", token}` sends the token as `Authorization: Bearer`; `{mode: "none"}` or no `auth` sends none. A `token` beside `url` is `400 FIELD_REMOVED`. The token is stored encrypted on the run and never returned. `name` defaults to a slug of the host (`mcp-deepwiki-com`), and may not be a built-in connection's or share a name with another entry (`422 CONNECTION_AMBIGUOUS` when it matches a named server). Ids and names fit Anthropic's stored-credential model (a vault id per run); the inline form fits OpenAI's inline `authorization` and Cursor's `mcpServers` headers. An id or name that is unknown, still connecting, or waiting on a reconnect is `422 CONNECTION_NOT_READY`. Follow-ups keep all three.
    - union
      - string: A connection id or name.
      - object
        - `url` string, uri, required
        - `name` string
        - `auth` union
          - object
            - `mode` 'none', required
          - object
            - `mode` 'bearer', required
            - `token` string, required
  - `resources` object[]: What Rush puts in front of the agent before it starts, each by URL, with `connection` naming the account that reaches it when more than one could: `https://github.com/<owner>/<repo>` clones the repository at its default branch, `…/tree/<branch>` at that branch, and `…/pull/<n>` on that open pull request's branch; at most one repository per run, reached through a GitHub App installation of the caller (`connection` is an installation id from `GET /o/{org}/github`). On a Project run it may only name the Project's repository. `https://linear.app/<workspace>/issue/<ID>` puts the issue in the prompt, read through the caller's Linear connection. Any other URL is `422 RESOURCE_UNSUPPORTED`; a repository no installation covers, or an issue with no Linear connection, is `422 RESOURCE_NOT_ACCESSIBLE`.
    - `url` string, uri, required
    - `connection` string

## Response `202`

The console's answer.

## Other responses

- `401`: No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
- `404`: No such resource for the caller, including one in an org the caller is not in or a Project that is private to someone else.

---

[API](https://skmtc.dev/getrush/apis/rush-api.md) · [All operations](https://skmtc.dev/getrush/apis/rush-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getrush/apis/rush-api/revisions/05fb36ca864f?raw)