Save a new agent at revision 1.

Requires an Idempotency-Key. A replay of the same key with the same body returns the original agent (201) before any catalog or connection check runs; the same key with a different body is 409 IDEMPOTENCY_CONFLICT. Validation failures are 422 (not 400) with a code and per-field fields; the first failing check wins, except catalog support, which reports every unsupported field at once under UNSUPPORTED_PROFILE.

Authenticate with a signed-in session token (an API key cannot call this route).

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

Headers

Idempotency-Keystringrequired

1–128 characters after trimming.

at most 128 characters

Request body

namestringrequired

Trimmed.

at most 80 characters

handlestringrequired

Trimmed and lowercased before matching; unique per caller.

descriptionstringoptional

at most 500 characters

instructionsstringoptional

At most 16 KiB of UTF-8, no NUL.

harnessstringrequired

Launch-boundary managed harnesses.

One ofclaudecodexopencode

catalog_revisionstringrequired

Must equal the current catalog_revision from GET /o/{org}/agents/available.

runtimeobject | objectoptional

1 fields

selectionstringrequired

defaultsobjectoptional

Omitted model/effort take the harness's workhorse suggested setup; speed defaults to standard (fast is refused today).

3 fields

modelSavedAgentModeloptional

2 fields

selectionstringrequired

idstringrequired

A model id the harness lists in GET /o/{org}/agents/available.

at most 200 characters

effortstring | nulloptional

speedstringoptional

One ofstandardfast

connection_refsarray of SavedAgentConnectionRefoptional

Each must be one of the caller's own usable connections.

2 item fields

kindstringrequired

One ofoauthmcp

idstringrequired

capabilitiesobjectoptional

Missing keys are false; values are coerced to boolean.

2 fields

browserbooleanoptional

computerbooleanoptional

toolsobject | objectoptional

1 fields

modestringrequired

networkobject | objectoptional

1 fields

modestringrequired

pluginsarray of objectoptional

Only catalog_id is read; the version is locked from the catalog at save.

1 item fields

catalog_idstringrequired

sourceobject | objectoptional

2 fields

profile_idstringrequired

revisionintegerrequired

min 1

Responses

201Saved (or replayed) agent.

idstringrequired

Format uuid

namestringrequired

handlestringrequired

descriptionstringrequired

harnessstringrequired

Launch-boundary managed harnesses.

One ofclaudecodexopencode

revisionintegerrequired

min 1

archivedbooleanrequired

sourceobject | object | nullrequired

configSavedAgentConfigrequired

The desired configuration stored with one revision.

10 fields

harnessstringrequired

Launch-boundary managed harnesses.

One ofclaudecodexopencode

catalog_revisionstringrequired

runtimeobject | objectrequired

1 fields

selectionstringrequired

defaultsobjectrequired

3 fields

modelSavedAgentModelrequired

2 fields

selectionstringrequired

idstringrequired

A model id the harness lists in GET /o/{org}/agents/available.

at most 200 characters

effortstring | nullrequired

speedstringrequired

One ofstandardfast

instructionsstringrequired

connection_refsarray of SavedAgentConnectionRefrequired

2 item fields

kindstringrequired

One ofoauthmcp

idstringrequired

capabilitiesobjectrequired

2 fields

browserbooleanrequired

computerbooleanrequired

toolsobject | objectrequired

1 fields

modestringrequired

networkobject | objectrequired

1 fields

modestringrequired

pluginsarray of objectrequired

1 item fields

catalog_idstringrequired

resolved_at_saveSavedAgentResolvedrequired

What the config resolved to against the catalog when this revision was saved.

9 fields

modelstringrequired

effortstring | nullrequired

speedstringrequired

One ofstandardfast

harness_versionstring | nullrequired

tool_idsarray of string | nullrequired

pluginsarray of objectrequired

3 item fields

catalog_idstringrequired

versionstringrequired

digeststringrequired

runtime_idstring | nullrequired

catalog_revisionstringrequired

pin_guaranteebooleanrequired

created_atstringrequired

Format date-time

updated_atstringrequired

Format date-time

400Missing or over-long Idempotency-Key (IDEMPOTENCY_KEY_REQUIRED).

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

404Org not found, or source.profile_id/source.revision is not one of the caller's agents (SOURCE_NOT_FOUND).

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

409IDEMPOTENCY_CONFLICT (key reused with a different body) or HANDLE_TAKEN (the caller already has an agent with this handle).

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

422Body refused.

Body refused. code is one of INVALID_BODY, INVALID_NAME, INVALID_HANDLE, INVALID_DESCRIPTION, INVALID_HARNESS, INVALID_CATALOG, CATALOG_REFRESH_REQUIRED (catalog_revision is not the current one), INVALID_INSTRUCTIONS, INVALID_RUNTIME, INVALID_TOOLS, INVALID_NETWORK, INVALID_CONNECTION_REFS, INVALID_SOURCE, INVALID_MODEL, INVALID_EFFORT, INVALID_SPEED, INVALID_PLUGINS, UNSUPPORTED_PROFILE (field codes such as UNKNOWN_MODEL, SPEED_NOT_QUALIFIED, NETWORK_ENFORCEMENT_NOT_QUALIFIED, UNKNOWN_PLUGIN), or CONNECTION_NOT_OWNED.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional

500INTERNAL_ERROR.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional

requestIdstringoptional