New VDF AI Enterprise is now available on AWS Marketplace
API Reference

Agent sessions

A session is one conversation with agents. The deployment creates it on the first run of a conversation and records every message in it: your prompts, the agents' answers and the tool calls in between. Each execution in the conversation carries the session's id as its session_id. A session also records the client application that started it and, when the conversation started inside a workspace, that workspace's id.

These endpoints only ever return and change your own sessions. Deleting a session hides it rather than erasing it.

Endpoints 4

Paths are relative to /agent-hub-api

The session object

One conversation. Retrieving a single session adds its messages.

Attributes

  • id string

    Unique identifier for the session (a UUID).

  • user_id nullable integer

    Id of the user the session belongs to.

  • client_id string

    Identifier of the client application that started the session, for example web.

  • title nullable string

    Title of the session. Starts as the first 80 characters of the first prompt and can be changed with Rename a session.

  • workspace_id nullable string

    Id of the workspace the conversation started in, or null for the default workspace.

  • deleted_at nullable string

    When the session was deleted (UTC, ISO 8601), or null.

  • created_at string

    When the session started (UTC, ISO 8601).

  • updated_at string

    When the session last changed (UTC, ISO 8601).

  • messages array of objects

    Only in Retrieve a session: every message in the session, oldest first.

    Show child attributes Hide child attributes
    • id string

      Unique identifier for the message.

    • session_id string

      Id of the session.

    • execution_id nullable string

      Id of the execution that produced the message.

    • user_id nullable integer

      Id of the user the message belongs to.

    • role string

      Who the message is from.

      Possible values
      • user
      • assistant
      • tool
      • system
    • content nullable string

      Text of the message. May be null for an assistant message that only calls tools.

    • tool_calls nullable array of objects

      Tool calls the assistant requested in this message, if any.

    • tool_call_id nullable string

      For tool messages, the id of the tool call this message answers.

    • created_at string

      When the message was recorded (UTC, ISO 8601).

The session object 
{
  "id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
  "user_id": 42,
  "client_id": "web",
  "title": "Draft the release notes for version 4.2 from this week's merged changes.",
  "workspace_id": null,
  "deleted_at": null,
  "created_at": "2026-09-01T09:29:48.296410",
  "updated_at": "2026-09-01T09:30:03.887215"
}

List agent sessions

GET /agent-hub-api/api/monitoring/sessions

Returns the caller's sessions, newest first.

Deleted sessions are left out unless include_deleted is true. Filters combine.

Authentication
Bearer token How it works

Query parameters

  • limit integer

    Maximum number of sessions to return.

    Defaults to 20.

  • offset integer

    Number of sessions to skip.

    Defaults to 0.

  • workspace_id string

    Only sessions started in this workspace, which must be one you can see. For the default workspace, sessions started outside any workspace are included too.

  • client_id string

    Only sessions started by this client application.

  • date_from string

    Only sessions started at or after this time: an ISO 8601 date-time such as 2026-09-01T00:00:00Z, or a date such as 2026-09-01. A value that cannot be parsed is ignored.

  • date_to string

    Only sessions started at or before this time, in the same formats as date_from.

  • include_deleted boolean

    Set to true to include sessions you have deleted.

    Defaults to false.

Returns

Returns data, a page of session objects without messages, and pagination with total, limit, offset and has_more.

Errors

  • 400 workspace_id is not a UUID.
  • 404 workspace_id is not a workspace you can see.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/monitoring/sessions?limit=20" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
      "user_id": 42,
      "client_id": "web",
      "title": "Draft the release notes for version 4.2 from this week's merged changes.",
      "workspace_id": null,
      "deleted_at": null,
      "created_at": "2026-09-01T09:29:48.296410",
      "updated_at": "2026-09-01T09:30:03.887215"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Retrieve an agent session

GET /agent-hub-api/api/monitoring/sessions/{session_id}

Returns one of the caller's sessions with all of its messages.

Messages are ordered oldest first. A deleted session returns 404.

Authentication
Bearer token How it works

Path parameters

  • session_id string Required

    Id of the session.

Returns

Returns data, the session object with its messages.

Errors

  • 404 You have no session with this id, or it has been deleted.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/monitoring/sessions/5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
    "user_id": 42,
    "client_id": "web",
    "title": "Draft the release notes for version 4.2 from this week's merged changes.",
    "workspace_id": null,
    "deleted_at": null,
    "created_at": "2026-09-01T09:29:48.296410",
    "updated_at": "2026-09-01T09:30:03.887215",
    "messages": [
      {
        "id": "7a1e3c5b-9d2f-4e86-b0a4-3c6e8f1d2b95",
        "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
        "execution_id": "e4a7c2d9-1b3f-4c8e-9a5d-6f2b8e1c3a70",
        "user_id": 42,
        "role": "user",
        "content": "Draft the release notes for version 4.2 from this week's merged changes.",
        "tool_calls": null,
        "tool_call_id": null,
        "created_at": "2026-09-01T09:29:48.310552"
      },
      {
        "id": "d3b5f7a9-1c2e-4d68-8f0b-6a4c2e9d1f37",
        "session_id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
        "execution_id": "e4a7c2d9-1b3f-4c8e-9a5d-6f2b8e1c3a70",
        "user_id": 42,
        "role": "assistant",
        "content": "## Release 4.2\n\n### Features\n- Added bulk export for invoices.\n\n### Fixes\n- Fixed rounding in quarterly totals.",
        "tool_calls": null,
        "tool_call_id": null,
        "created_at": "2026-09-01T09:30:03.879046"
      }
    ]
  }
}

Rename an agent session

PATCH /agent-hub-api/api/monitoring/sessions/{session_id}

Changes the title of one of the caller's sessions.

Authentication
Bearer token How it works

Path parameters

  • session_id string Required

    Id of the session.

Body parameters application/json

  • title string

    New title. Runs of whitespace are collapsed to single spaces and the title is cut to 255 characters. An empty or null title, or leaving it out, clears the title.

Returns

Returns data, the updated session object.

Errors

  • 400 The new title could not be saved.
  • 404 You have no session with this id, or it has been deleted.
Request 
curl -X PATCH "$VDF_BASE_URL/agent-hub-api/api/monitoring/sessions/5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Release 4.2 notes"
  }'
Response 200 
{
  "success": true,
  "data": {
    "id": "5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58",
    "user_id": 42,
    "client_id": "web",
    "title": "Release 4.2 notes",
    "workspace_id": null,
    "deleted_at": null,
    "created_at": "2026-09-01T09:29:48.296410",
    "updated_at": "2026-09-02T16:41:25.119874"
  }
}

Delete an agent session

DEL /agent-hub-api/api/monitoring/sessions/{session_id}

Deletes one of the caller's sessions.

Marks the session deleted: it drops out of List sessions unless include_deleted is true, and can no longer be retrieved or renamed. Deleting a session that is already deleted succeeds.

Authentication
Bearer token How it works

Path parameters

  • session_id string Required

    Id of the session.

Returns

Returns success: true once the agent session is deleted.

Errors

  • 400 The session could not be deleted.
  • 404 You have no session with this id.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/monitoring/sessions/5b8e1f3a-2c9d-4a67-b1e4-7f0c3d9a2e58" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true
}