Pokee Enterprise APISessions
Sessions, lifecycle, and per-session file access scoping.
A session is one agent process in a per-session sandbox, running inside your dedicated pod. Sessions are independent: each has its own conversation history, its own file-access scope, its own busy state.
POST /v1/sessions
Create a session.
Request body (all fields optional):
| Field | Type | Default | Description |
|---|---|---|---|
persistent | bool | false | If false, session auto-destroys 5 minutes after the last response completes. If true, lives until ttl expires or you DELETE it. |
ttl | int (seconds) | 14400 (4h) | Hard upper bound on session lifetime. |
metadata | object | {} | Free-form key/value attached to the session. Returned on GET. |
file_access | object | full workspace | Restrict which files the agent (and your file API calls) can see. See File access. |
Response (201 Created): full session record.
{
"id": "sess_a86118c06688",
"created_at": 1777222996.07,
"last_activity": 1777222996.07,
"busy": false,
"persistent": false,
"ttl": 14400,
"status": "ready",
"metadata": {},
"file_access": {"read": [""], "write": [""]}
}GET /v1/sessions
List all sessions for the tenant. Returns [<session_record>, ...].
GET /v1/sessions/{id}
Get a session record. Returns 404 if the session has been destroyed. Watch metadata for tool-specific status fields.
DELETE /v1/sessions/{id}
Destroy a session. Returns 204. Idempotent for an already-destroyed session (returns 404).
DELETE /v1/sessions
Bulk delete with query params:
| Param | Description |
|---|---|
status=idle | Only destroy idle (non-busy) sessions |
older_than=2h | Destroy sessions inactive for at least N (s/m/h suffix; combinable: 1h30m) |
Response: {"deleted": <count>}.
File access
By default a session sees the entire workspace. To restrict, pass file_access at create time:
{
"file_access": {
"read": ["projects/my-project", "shared/templates"],
"write": ["projects/my-project/output"]
}
}Rules:
- Paths are workspace-relative. No leading slash.
- Empty string
""= whole workspace (the default). writeimpliesread— no need to list a path twice.- The session's own dir
.sessions/{session_id}/is always included automatically. - Effective scope is immutable for the session's lifetime. To change it, destroy and recreate.
The agent literally cannot see files outside its scope (filesystem-level enforcement via per-session mount namespaces — out-of-scope paths return ENOENT, not "permission denied"). The HTTP file API enforces the same scope.