Session Store

View as Markdown

A workspace-scoped session store.

Get a session storeGET /api/2.0/agents/{name=session-stores/*}List session storesGET /api/2.0/agents/session-storesCreate a session storePOST /api/2.0/agents/session-storesUpdate a session storePATCH /api/2.0/agents/{name=session-stores/*}Delete a session storeDELETE /api/2.0/agents/{name=session-stores/*}Grant session store permissionPOST /api/2.0/agents/{name=session-stores/*}/permissions:grantGet session store permissionGET /api/2.0/agents/{name=session-stores/*}/permissions/selfList session store permissionsGET /api/2.0/agents/{parent=session-stores/*}/permissionsRevoke session store permissionPOST /api/2.0/agents/{name=session-stores/*}/permissions:revoke

SessionStore object

A workspace-scoped session store.

creator_user_idstringBetaOutput only

Workspace-local user ID of the authenticated principal that created the store. This is immutable server-set attribution and does not grant access; authorization is evaluated from the authenticated request context.

create_timestringBetaOutput only

Time when the store was created.

update_timestringBetaOutput only

Time when the store was last updated.

descriptionstringBeta

Human-readable description of the session store.

metadataobjectBeta

Mutable caller-defined string labels.

namestringBetaOutput onlyIDImmutable

Resource name in the form session-stores/{session_store_id}.

View as Markdown

The SessionStore object

{
  "creator_user_id": "string",
  "create_time": "string",
  "update_time": "string",
  "description": "string",
  "metadata": {},
  "name": "string"
}

Get a session store Beta

GET /api/2.0/agents/{name=session-stores/*}

Gets a session store by resource name.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}.

Response

Returns the SessionStore object.

View as Markdown

Response

{
  "creator_user_id": "string",
  "create_time": "string",
  "update_time": "string",
  "description": "string",
  "metadata": {},
  "name": "string"
}

List session stores Beta

GET /api/2.0/agents/session-stores

Lists session stores.

API scopes: agent-kit

Parameters

page_sizeint32query

Maximum number of session stores to return. Defaults to 10; must be between 1 and 100.

page_tokenstringquery

Token returned by a previous list request.

Response

Returns a list of SessionStore objects.

View as Markdown

Response

{
  "session_stores": [
    {
      "creator_user_id": "string",
      "create_time": "string",
      "update_time": "string",
      "description": "string",
      "metadata": {},
      "name": "string"
    }
  ],
  "next_page_token": "string"
}

Create a session store Beta

POST /api/2.0/agents/session-stores

Creates a session store.

API scopes: agent-kit

Parameters

session_store_idstring^[a-z]([a-z0-9-]{0,53}[a-z0-9])?$[ 3 .. 55 ] charactersRequiredquery

Caller-provided, workspace-unique session store ID. It must be 3-55 characters, begin with a lowercase letter, and contain only lowercase letters, digits, and hyphens.

Request body

The session store to create.

descriptionstring

Human-readable description of the session store.

metadataobject

Mutable caller-defined string labels.

Response

Returns the SessionStore object.

View as Markdown

Request

{
  "description": "string",
  "metadata": {}
}

Response

{
  "creator_user_id": "string",
  "create_time": "string",
  "update_time": "string",
  "description": "string",
  "metadata": {},
  "name": "string"
}

Update a session store Beta

PATCH /api/2.0/agents/{name=session-stores/*}

Updates a session store's description and metadata.

API scopes: agent-kit

Parameters

namestringRequiredIDImmutablepath

Resource name in the form session-stores/{session_store_id}.

update_maskstringRequiredquery

Fields to update. Only description and metadata are mutable; any other path returns INVALID_PARAMETER_VALUE.

Request body

Session store to update.

descriptionstring

Human-readable description of the session store.

metadataobject

Mutable caller-defined string labels.

Response

Returns the SessionStore object.

View as Markdown

Request

{
  "description": "string",
  "metadata": {}
}

Response

{
  "creator_user_id": "string",
  "create_time": "string",
  "update_time": "string",
  "description": "string",
  "metadata": {},
  "name": "string"
}

Delete a session store Beta

DELETE /api/2.0/agents/{name=session-stores/*}

Deletes a session store, its sessions and items, and its service-managed storage. Memory entries retained by a separate Memory Store are not deleted.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}.

View as Markdown

Response

{}

Grant session store permission Beta

POST /api/2.0/agents/{name=session-stores/*}/permissions:grant

1 more path

POST /api/agents/v1/{name=session-stores/*}/permissions:grant

Grants a READ or WRITE permission on a session store to a principal. Only the owner or a workspace admin may grant permissions.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}.

Request body

principalobjectRequired

Principal to grant the permission to.

Show child attributesHide child attributes

namestringRequired

principal_typestring

The kind of principal. Required unless the deprecated type alias is supplied.

Values:

• USER
• SERVICE_PRINCIPAL

permissionstringRequired

Permission level to grant.

Values:

• READ
• WRITE

View as Markdown

Request

{
  "principal": {
    "name": "string",
    "principal_type": "USER"
  },
  "permission": "READ"
}

Response

{}

Get session store permission Beta

GET /api/2.0/agents/{name=session-stores/*}/permissions/self

1 more path

GET /api/agents/v1/{name=session-stores/*}/permissions/self

Retrieves the current caller's effective session store permission. Returns PERMISSION_LEVEL_UNSPECIFIED when the caller has no access.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}.

Response

principalobjectOutput only

The principal whose permission is reported.

Show child attributesHide child attributes

namestringRequired

principal_typestring

The kind of principal. Required unless the deprecated type alias is supplied.

Values:

• USER
• SERVICE_PRINCIPAL

permissionstringOutput only

The permission level. WRITE includes READ; PERMISSION_LEVEL_UNSPECIFIED means neither is available.

Values:

• READ
• WRITE

View as Markdown

Response

{
  "principal": {
    "name": "string",
    "principal_type": "USER"
  },
  "permission": "READ"
}

List session store permissions Beta

GET /api/2.0/agents/{parent=session-stores/*}/permissions

1 more path

GET /api/agents/v1/{parent=session-stores/*}/permissions

Lists explicit session store grants. Only the owner or a workspace admin may list permissions.

API scopes: agent-kit

Parameters

parentstringRequiredpath

Resource name of the store, in the form session-stores/{session_store_id}.

page_sizeint32query

Maximum number of permissions to return. Defaults to 100; maximum is 1000.

page_tokenstringquery

Continuation token from a previous response.

Response

session_store_permissionsarray of objectOutput only

Explicit READ or WRITE grants. Implicit owner/admin access and inherited grants are excluded.

Show child attributesHide child attributes

principalobjectOutput only

The principal whose permission is reported.

Show child attributesHide child attributes

namestringRequired

principal_typestring

The kind of principal. Required unless the deprecated type alias is supplied.

Values:

• USER
• SERVICE_PRINCIPAL

permissionstringOutput only

The permission level. WRITE includes READ; PERMISSION_LEVEL_UNSPECIFIED means neither is available.

Values:

• READ
• WRITE

next_page_tokenstringOutput only

Token for the next page, omitted when all permissions have been returned.

View as Markdown

Response

{
  "session_store_permissions": [
    {
      "principal": {},
      "permission": "READ"
    }
  ],
  "next_page_token": "string"
}

Revoke session store permission Beta

POST /api/2.0/agents/{name=session-stores/*}/permissions:revoke

1 more path

POST /api/agents/v1/{name=session-stores/*}/permissions:revoke

Removes a principal's explicit READ and WRITE grants on a session store. Only the owner or a workspace admin may revoke permissions. Ownership and inherited access are unaffected.

API scopes: agent-kit

Parameters

namestringRequiredpath

Resource name in the form session-stores/{session_store_id}.

Request body

principalobjectRequired

Principal whose READ and WRITE grants will be removed.

Show child attributesHide child attributes

namestringRequired

principal_typestring

The kind of principal. Required unless the deprecated type alias is supplied.

Values:

• USER
• SERVICE_PRINCIPAL

View as Markdown

Request

{
  "principal": {
    "name": "string",
    "principal_type": "USER"
  }
}

Response

{}