Sessions API

listSessions

GET /api/v2/sessions

Requires: invoke role

Index of the caller's sessions, newest activity first (updated_at descending, keyset cursor). Each row carries the run count, the distinct root targets, the latest root traverser, the Studio label (run metadata studio.label) and the brief artifact bytes. target keeps sessions with a root of that label.capability (Studio passes studio.build); status matches the latest root; label matches studio.label; updated_after is Unix milliseconds. limit defaults to 50, at most 200. An admin may pass principal to list another principal's sessions and include_deleted to see soft-deleted ones (403 otherwise). Deleted sessions are hidden by default.

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.list_sessions()

Parameters

Responses

Example response 200

{
  "items": [
    {
      "active_root_id": "string",
      "artifact_bytes": 0,
      "created_at": 0,
      "deleted_at": 0,
      "id": "string",
      "label": "string",
      "last_traverser": {
        "created_at": 0,
        "id": "string",
        "status": {},
        "target": "string",
        "updated_at": 0
      },
      "namespace": "string",
      "principal": "string",
      "targets": [
        "string"
      ],
      "traverser_count": 0,
      "updated_at": 0
    }
  ],
  "next_cursor": "string"
}

createSession

POST /api/v2/sessions

Requires: invoke role

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.create_session()

Request body

CreateSession (required)

{
  "id": "string"
}

Responses

Example response 201

{
  "created_at": 0,
  "id": "string",
  "namespace": "string",
  "principal": "string"
}

getSession

GET /api/v2/sessions/{id}

Requires: invoke role, worker role

One session as the index reports it, including deleted_at once it was deleted. The owner, an admin, or a worker whose leased task (task_id + lease_token) runs in the session may read it; any other session, including another principal's, is 404 session_not_found so existence is not leaked.

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.get_session()

Parameters

Responses

Example response 200

{
  "active_root_id": "string",
  "artifact_bytes": 0,
  "created_at": 0,
  "deleted_at": 0,
  "id": "string",
  "label": "string",
  "last_traverser": {
    "created_at": 0,
    "id": "string",
    "status": "queued",
    "target": "string",
    "updated_at": 0
  },
  "namespace": "string",
  "principal": "string",
  "targets": [
    "string"
  ],
  "traverser_count": 0,
  "updated_at": 0
}

deleteSession

DELETE /api/v2/sessions/{id}

Requires: invoke role

Soft-delete the session and hard-delete its private data: brief artifacts, session-scoped memory entries and vectors, and session-scoped knowledge documents (with their chunks and postings) are removed and counted in removed; the builder's transcript entries on the session's runs become tombstones and shell-command approval prompts keep only their identifiers (transcript_entries, scrubbed_prompts); traversers, checkpoints and approvals stay for audit and cost and are counted in kept. Refused with 409 session_busy while any traverser in the session is queued, running or waiting (cancel first). Afterwards the session is hidden from the index and a new traverser, binding or session-scoped write answers 410 session_deleted. Idempotent: deleting again returns 200 with zero removed counts and the original deleted_at. Harness teardown is the studio node's (studio.discard), not the server's.

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.delete_session()

Parameters

Responses

Example response 200

{
  "deleted": false,
  "deleted_at": 0,
  "id": "string",
  "kept": {
    "approvals": 0,
    "checkpoints": 0,
    "traversers": 0
  },
  "removed": {
    "brief_artifacts": 0,
    "knowledge_documents": 0,
    "memory_entries": 0,
    "memory_vectors": 0,
    "scrubbed_prompts": 0,
    "transcript_entries": 0
  }
}

getSessionSecrets

GET /api/v2/sessions/{id}/secrets

Requires: invoke role, worker role

Two readers. The deploying worker (task_id + lease_token of a task in this session) receives label and values exactly once; the entry is cleared and a second read is 404 secrets_not_found. The owner or an admin passes names=1 and receives label, names and expires_at without values; an owner read without names=1 is 403 forbidden, because values are for the worker only. Expired or never-provided secrets are 404 secrets_not_found. If the server restarted before the deploy collected them, the values are gone and the Console asks for them again.

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.get_session_secrets()

Parameters

Responses

Example response 200

{
  "expires_at": 0,
  "label": "string",
  "names": [
    "string"
  ],
  "session_id": "string",
  "values": {
    "key": "string"
  }
}

putSessionSecrets

PUT /api/v2/sessions/{id}/secrets

Requires: invoke role

Store the secret values a Studio brief provides for the node it will deploy (label). Names match ^[A-Z][A-Z0-9_]{1,63}$ (400 invalid_input naming the offender), at most 50 names, each value at most 65536 bytes (413 secret_too_large). The values live in the server's process memory only, for one hour; a repeat PUT replaces the set; nothing reaches the database, the event log, run metadata or a log line, and this request body is never logged. The answer carries the sorted names and expires_at, never values. Owner or admin; 404 session_not_found for another principal's session; 410 session_deleted.

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.put_session_secrets()

Parameters

Request body

SessionSecretsPut (required)

{
  "label": "string",
  "values": {
    "key": "string"
  }
}

Responses

Example response 200

{
  "expires_at": 0,
  "label": "string",
  "names": [
    "string"
  ],
  "session_id": "string",
  "values": {
    "key": "string"
  }
}

deleteSessionSecrets

DELETE /api/v2/sessions/{id}/secrets

Requires: invoke role

Clear waiting secrets for the session without handing them out. Owner or admin; idempotent (cleared is always true, had_secrets says whether anything was waiting).

Generated Python client internals: atfgraph._generated.api.sessions_api.SessionsApi.delete_session_secrets()

Parameters

Responses

Example response 200

{
  "cleared": false,
  "had_secrets": false,
  "session_id": "string"
}