---
title: "Save an agent."
method: POST
path: "/o/{org}/agents"
tags: ["Saved agents"]
---

# Save an agent.

`POST /o/{org}/agents`

## Request

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

A harness with its model, effort, instructions, skills and connections, to start sessions
from by sending its id as `agent`. Skills are fetched and pinned when the agent is saved (a GitHub
source to its commit, any other to its content), and every session from the agent loads
exactly that pin. A field this route does not take is `400 UNKNOWN_FIELD`; `defaults` and
`connection_refs` are `400 FIELD_REMOVED`. A refused body is `422` with a `code`, and
per-field `fields` where the catalog does not support a choice (`UNSUPPORTED_PROFILE`, with
field codes such as `UNKNOWN_MODEL` and `INVALID_EFFORT`).

Send `template` instead to make an agent from a saved agent, one per user of your own app:
it runs the template's current instructions, harness, model, skills and capabilities, and
the accounts connected to it alone (`POST /me/connections` with `agent`). It takes only
`template`, `name`, `description` and `handle`; any field the template sets is `422 TEMPLATE_FIELDS`.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - SavedAgentCreate
    - `name` string, required
    - `description` string
    - `harness` 'claude' | 'codex' | 'opencode', required: Launch-boundary managed harnesses.
    - `model` string: A model `id` `GET /o/{org}/agents/available` lists for the harness. Omitted: the harness's first model.
    - `effort` string: One of the model's effort levels.
    - `instructions` string: At most 16 KiB.
    - `skills` SkillUrl[]: Skills by URL, as on session create; fetched and pinned when saved.
      - union: A skill by public URL, as a string or `{url}`.
        - string, uri
        - object
          - `url` string, uri, required
    - `connections` string[]: Ids or names of your own connections (`GET /me/connections`), as on session create.
    - `capabilities` object
      - `browser` boolean
      - `computer` boolean
  - SavedAgentFromTemplate
    - `template` string, required: The id or name of a saved agent you created that is not itself made from a template.
    - `name` string, required: Yours to choose, such as your own user id.
    - `description` string
    - `handle` string: A lowercase slug; made from `name` when omitted.

## Response `201`

The saved agent.

- SavedAgent: A saved agent. A field appears only when it has a value.
  - `visibility` 'private' | 'org': Private by default; org makes the agent usable by current org members.
  - `id` string, uuid, required
  - `template` string, uuid: Present on an agent made from a template; everything but its name and description is the template's.
  - `name` string, required
  - `description` string
  - `harness` 'claude' | 'codex' | 'opencode', required: Launch-boundary managed harnesses.
  - `model` string, required
  - `effort` string
  - `instructions` string
  - `skills` object[]
    - `url` string, uri, required
    - `name` string, required
  - `connections` object[]: The agent's connections from `GET /me/connections`, each with the name a run's `connections` takes. A deleted connection has no `name`. On an agent made from a template, one entry per connection the template names: `id` is the agent's own account of that app, absent until connected.
    - `id` string
    - `name` string
  - `capabilities` object: Present when browser or computer use is on.
    - `browser` boolean
    - `computer` boolean
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: An unknown field (`UNKNOWN_FIELD`), a removed one (`FIELD_REMOVED`), a malformed `connections` or `skills` entry, or a bad `Idempotency-Key`.
- `401`: No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
- `403`: A `template` someone else created (`FORBIDDEN`); only a template's creator makes agents from it.
- `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.
- `409`: `IDEMPOTENCY_CONFLICT`.
- `422`: Body refused: `INVALID_NAME`, `INVALID_DESCRIPTION`, `INVALID_HARNESS`, `INVALID_INSTRUCTIONS`, `INVALID_MODEL`, `INVALID_EFFORT`, `UNSUPPORTED_PROFILE` (a model the harness does not list, or an effort that model does not take), a connection that is not one of yours or not connected (`CONNECTION_NOT_READY`, `CONNECTION_AMBIGUOUS`), or a skill that cannot be fetched (`SKILL_FETCH_FAILED`, `SKILL_INVALID`). With `template`: a field the template sets (`TEMPLATE_FIELDS`), or a `template` that is itself made from a template or names two templates (`INVALID_BODY`).

## Changes

- **2026-10-20** `e351f947926b`: 2 breaking, 9 warning, 3 info
  - the request's body type changed from `object` to no type
  - the response property `connections/items/id` became optional for the status `201`
  - removed the request property `capabilities`
  - removed the request property `connections`
  - …10 more

[Operation history](https://skmtc.dev/getrush/apis/rush-api/changes/o/:org/agents/post.md)

---

[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/e351f947926b?raw)