Skip to main content
POST
Find or create a user's personal agent
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

Provisions a PERSONAL agent for a user of your external application, or returns the existing one if the (app, user) pair has already been provisioned. The operation is idempotent — calling it multiple times with the same application and user always returns the same agent. The HTTP status code distinguishes create from find: 201 Created on first provision, 200 OK when returning an existing agent. Uniqueness is enforced per (principalExternalApplicationId, userId, agentType=PERSONAL) — one personal agent per app-user pair. The principalExternalApplicationId is always derived server-side from the bearer token.

Request

Headers

Body

Creation fields are write-once. All optional fields (name, description, model, prompt, etc.) are applied only when the agent is first created. If an agent already exists for the (app, user) pair, the endpoint returns the existing record without modification. To update an existing agent’s definition, use the management API’s PATCH /api/v2/agents/update endpoint.

User identity resolution

The endpoint resolves the user through one of two paths, tried in order: 1. X-Forge-User-JWT header (preferred) Pass the JWT your application issued for the current user. Forge validates it against your application’s JWKS configuration and JIT-provisions a Forge user record if the user has never been seen before. The resulting Forge userId is used as the personal agent’s owner. This is the right path for first-time user provisioning. After the first call, the response includes the userId — you can cache it and use the explicit body param path on subsequent calls. 2. Explicit userId in body Pass the Forge userId directly. This path is find-only: Forge verifies the user exists, was provisioned as an external user (not a Forge employee or another internal account type), is active, and was provisioned under your application specifically — not a different external application that happens to know the same userId. Returns 404 Not Found if the user has never been provisioned, or 403 Forbidden if any of the other checks fail — use the JWT path to provision a user before referencing them this way. If neither X-Forge-User-JWT nor userId is provided, the endpoint returns 400 Bad Request.

Response

201 Created — agent provisioned

200 OK — existing agent returned

Same shape as 201. The _id, agentId, and createdAt fields reflect the original creation values.

Response fields

principalExternalApplicationId is not returned. The response projection does not include principalExternalApplicationId or principalKind. These are internal governance fields — your application already knows its own ID from the bearer token, and echoing them in the response would add no information.

Errors


Example


See also

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

X-Forge-User-JWT
string

Your user's identity token, signed by your app's identity provider. Forge provisions the user on first sight and acts for them; without it, name a user already provisioned that way (userId).

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Body

application/json
agentType
enum<string>
required

Only PERSONAL is accepted.

Available options:
PERSONAL
userId
string

A user already provisioned through X-Forge-User-JWT; ignored when that header is sent.

agentId
string

The slug for a new agent; generated when absent.

name
string
description
string
purpose
string
status
string
tags
string[]
model
object
prompt
object
externalModelAllowlist
string[]

The Gloo models the agent may call; every one must be active and not deprecated. Absent: every active, non-deprecated Gloo model.

Response

The user's existing personal agent

data
object
required
meta
object
required