Create an agent identity without issuing credentials

POST

/v1/admin/orgs/{org_id}/projects/{project_id}/agents

• Production
• Local

Creates an active, project-bound agent for console-managed inboxes. API keys can be issued separately.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

project_id

required

string

Request Body ^required

object

name

required

Human-facing agent name. The server generates its technical handle.

string

>= 1 characters <= 120 characters

Responses

201

Created

object

id

string

handle

string

name

string

status

string

Allowed values: active disabled

mailbox_count

Inboxes owned by this agent in the active project.

integer

last_seen_at

Latest authenticated API-key activity.

string format: date-time

nullable

created_at

string format: date-time

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope