Skip to main content
POST
cURL

Body

application/json
projectId
string

The ID of the Agent Vault project.

Required string length: 1 - 36
accessBundle
string

The name of the access bundle this session carries. Leave it out to start a session that has only services and skills, from the project or sent with it.

Required string length: 1 - 64
services
(string | HTTP · object | MCP · object | PostgreSQL · object | MySQL · object | SSH · object)[]

The services this session reaches besides its access bundle's. Each entry is either the name of a service in the project, up to 50, or a service sent inline, up to 20. Names must be unique across the list. If a name repeats, the request fails with a 422 error that says which one.

The name of a service in this project. An Agent Vault admin can use any of them, and a member only a service in an access bundle granted to them. A session on behalf of a user can use only a service in an access bundle granted to both the user and the machine identity. On every request, the session reaches the service only while its owner still does.

Required string length: 1 - 64
skills
(string | Inline skill · object)[]

The skills an agent gets in this session besides its access bundle's. Each entry is either the name of a skill in the project, up to 20, or a skill sent inline, up to 5. Names must be unique across the list. If a name repeats, the request fails with a 422 error that says which one.

The name of a skill in this project. An Agent Vault admin can use any of them, and a member only a skill in an access bundle granted to them. A session on behalf of a user can use only a skill in an access bundle granted to both the user and the machine identity. Each time an agent asks for the session's skills, it gets the skill's latest version, and only while the session's owner can still use it.

Required string length: 1 - 64
ttl
string

How long the session lasts: a duration such as 30m, 8h or 7d (at least 1m), or never. Defaults to 7d, or to 1h for a session started on behalf of a user.

onBehalfOf
object

Start the session on behalf of a user instead of yourself. Only a machine identity whose delegation covers the user can do this. The session can use only an access bundle that both the user and the machine identity can use, and it uses the user's personal values. The session still belongs to the machine identity, so only the machine identity and Agent Vault admins can see it and its session logs, not the user. Name the user by userId or by userEmail, not both.

Example:
label
string | null

A short description of what the session is for, such as nightly deploy or support ticket triage. Up to 128 characters, without line breaks, tabs, or invisible characters. Shown wherever the session is listed.

Maximum string length: 128
metadata
object

Key/value pairs that describe the session, such as a run ID, a ticket or the end user an agent works for, so whoever reads the session later can tell what it was for. Up to 20 entries. Each key is 1 to 255 characters and each value 1 to 1020, without line breaks, tabs, or invisible characters. A key can't contain =. Keys and values are trimmed, and each key can be used once.

Response

Default Response

session
object
required