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

Workspaces

A workspace is a project-style container that groups domains and agents and attaches external building blocks: tools, callable network templates, database connections (reference only), and integrations. Passing a workspace to Run an agent scopes that run to the workspace's tools and knowledge sources.

Visibility follows ownership. System workspaces (no owner) are readable by everyone. A workspace you own is readable by you. A workspace with visibility set to company is additionally readable by any caller whose token carries a matching company. Mutation is always owner-only, and a workspace you cannot see returns 404 rather than 403, so its existence stays hidden.

A workspace's settings toggle how it behaves in chat: whether it applies to new chats, whether its network templates are callable, whether its attached knowledge sources are the only ones searched, and whether its tools are offered first.

Endpoints 10

Paths are relative to /agent-hub-api

The workspace object

A workspace and its associations.

Attributes

  • id string

    Unique identifier, a UUID.

  • name string

    Display name.

  • slug string

    URL-safe identifier, unique within the caller's scope.

  • description nullable string

    Free-text summary.

  • icon nullable string

    Icon reference used by the portal.

  • color nullable string

    Accent colour as a #RRGGBB hex string.

  • owner_user_id nullable integer

    The owning user, or null for a system workspace.

  • company_id nullable integer

    Company that a company-visible workspace is shared with.

  • visibility string

    Who can read the workspace beyond its owner.

    Possible values
    • private
    • company
  • settings object

    Behaviour toggles.

    Show child attributes Hide child attributes
    • apply_to_new_chats boolean

      Whether new chats start in this workspace.

    • allow_callable_networks boolean

      Whether the workspace's network templates can be called from a run.

    • shared_knowledge boolean

      Whether knowledge search is restricted to the workspace's attached sources.

    • workspace_tools_first boolean

      Whether the workspace's tools are offered before others.

  • updated_by_user_id nullable integer

    User who last changed the workspace.

  • is_default boolean

    Whether this is the default system workspace.

  • is_system boolean

    Whether this is a system workspace.

  • sort_order integer

    Ordering hint for display.

  • domains array of objects

    The domains mapped to the workspace.

  • domain_count integer

    Number of mapped domains.

  • agent_count integer

    Number of agents in the workspace visible to the caller.

  • explicit_agent_ids array of strings

    Agents linked directly to the workspace, beyond those implied by its domains.

  • component_counts object

    Number of attached components per type.

    Show child attributes Hide child attributes
    • tool integer

      Attached tools.

    • network_template integer

      Attached network templates.

    • db_connection integer

      Attached database connections.

    • integration integer

      Attached integrations.

  • components nullable object

    The full grouped component lists. Present on detail responses (retrieve, create, update).

  • created_at string

    Creation timestamp, ISO 8601.

  • updated_at string

    Last-update timestamp, ISO 8601.

The workspace object 
{
  "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
  "name": "Finance",
  "slug": "finance",
  "description": "Reporting and analysis agents for the finance team.",
  "icon": "mdi:finance",
  "color": "#487FFF",
  "owner_user_id": 42,
  "company_id": 7,
  "visibility": "company",
  "settings": {
    "apply_to_new_chats": true,
    "allow_callable_networks": true,
    "shared_knowledge": true,
    "workspace_tools_first": true
  },
  "updated_by_user_id": 42,
  "is_default": false,
  "is_system": false,
  "sort_order": 0,
  "domains": [
    {
      "id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
      "slug": "communication",
      "name": "Communication"
    }
  ],
  "domain_count": 1,
  "agent_count": 3,
  "explicit_agent_ids": [
    "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11"
  ],
  "component_counts": {
    "tool": 2,
    "network_template": 0,
    "db_connection": 1,
    "integration": 1
  },
  "created_at": "2026-09-01T09:30:00",
  "updated_at": "2026-09-01T09:30:00"
}

List workspaces

GET /agent-hub-api/api/workspaces

Returns every workspace the caller can see: system workspaces, workspaces you own, and company-visible workspaces that match your company. Each entry includes its domains, an agent count, the directly linked agent ids, and per-type component counts.

Authentication
Bearer token How it works

Parameters

No parameters.

Returns

Returns a list of workspace objects under data.

Request 
curl "$VDF_BASE_URL/agent-hub-api/api/workspaces" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
      "name": "Finance",
      "slug": "finance",
      "description": "Reporting and analysis agents for the finance team.",
      "color": "#487FFF",
      "owner_user_id": 42,
      "company_id": 7,
      "visibility": "company",
      "settings": {
        "apply_to_new_chats": true,
        "allow_callable_networks": true,
        "shared_knowledge": true,
        "workspace_tools_first": true
      },
      "is_default": false,
      "is_system": false,
      "sort_order": 0,
      "domains": [
        {
          "id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
          "slug": "communication",
          "name": "Communication"
        }
      ],
      "domain_count": 1,
      "agent_count": 3,
      "explicit_agent_ids": [
        "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11"
      ],
      "component_counts": {
        "tool": 2,
        "network_template": 0,
        "db_connection": 1,
        "integration": 1
      },
      "created_at": "2026-09-01T09:30:00",
      "updated_at": "2026-09-01T09:30:00"
    }
  ]
}

Create a workspace

POST /agent-hub-api/api/workspaces

Creates a workspace that you own.

Creates a workspace owned by the caller. name is required and a slug is derived from it when omitted; the slug must be unique among your workspaces. Set visibility to company to make it readable across your company, which requires your token to carry a company. domain_ids must reference domains visible to you.

Authentication
Bearer token How it works

Body parameters application/json

  • name string Required

    Display name.

  • slug string

    URL-safe identifier. Derived from name when omitted.

  • description string

    Free-text summary.

  • icon string

    Icon reference.

  • color string

    Accent colour as #RRGGBB.

  • visibility string

    Who can read the workspace beyond you. company requires a company on your token.

    Defaults to private.

    Possible values
    • private
    • company
  • settings object

    Behaviour toggles; unspecified toggles default to true.

    Show child parameters Hide child parameters
    • apply_to_new_chats boolean

      Whether new chats start here.

    • allow_callable_networks boolean

      Whether attached network templates are callable.

    • shared_knowledge boolean

      Whether knowledge search is limited to attached sources.

    • workspace_tools_first boolean

      Whether attached tools are offered first.

  • domain_ids array of strings

    Domains to map to the workspace.

  • sort_order integer

    Ordering hint.

Returns

Returns the created workspace object, including its components, under data.

Errors

  • 400 name is missing, the slug already exists in your scope, company visibility was requested without a company, or a field failed validation.
  • 401 The request carries no usable user identity.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/workspaces" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance",
    "description": "Reporting and analysis agents for the finance team.",
    "color": "#487FFF",
    "visibility": "company",
    "settings": {
      "shared_knowledge": true
    },
    "domain_ids": [
      "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90"
    ]
  }'
Response 201 
{
  "success": true,
  "data": {
    "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
    "name": "Finance",
    "slug": "finance",
    "description": "Reporting and analysis agents for the finance team.",
    "color": "#487FFF",
    "owner_user_id": 42,
    "company_id": 7,
    "visibility": "company",
    "settings": {
      "apply_to_new_chats": true,
      "allow_callable_networks": true,
      "shared_knowledge": true,
      "workspace_tools_first": true
    },
    "is_default": false,
    "is_system": false,
    "sort_order": 0,
    "domains": [
      {
        "id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
        "slug": "communication",
        "name": "Communication"
      }
    ],
    "domain_count": 1,
    "agent_count": 0,
    "explicit_agent_ids": [],
    "component_counts": {
      "tool": 0,
      "network_template": 0,
      "db_connection": 0,
      "integration": 0
    },
    "components": {
      "tool": [],
      "network_template": [],
      "db_connection": [],
      "integration": []
    },
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Retrieve a workspace

GET /agent-hub-api/api/workspaces/{workspace_id}

Retrieves a workspace by its identifier.

Returns a single workspace with its domains, agent count, linked agent ids, and the full grouped component lists. A workspace not visible to the caller returns 404.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Returns

Returns the workspace object, including its components, under data.

Errors

  • 404 No workspace with this identifier is visible to the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
    "name": "Finance",
    "slug": "finance",
    "visibility": "company",
    "settings": {
      "apply_to_new_chats": true,
      "allow_callable_networks": true,
      "shared_knowledge": true,
      "workspace_tools_first": true
    },
    "is_default": false,
    "is_system": false,
    "domains": [
      {
        "id": "b7d34a10-2f6c-4c1e-9a3e-7e2f5c8d1a90",
        "slug": "communication",
        "name": "Communication"
      }
    ],
    "domain_count": 1,
    "agent_count": 3,
    "explicit_agent_ids": [
      "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11"
    ],
    "component_counts": {
      "tool": 2,
      "network_template": 0,
      "db_connection": 1,
      "integration": 1
    },
    "components": {
      "tool": [
        {
          "id": "c1",
          "ref": "web_search",
          "label": "Web search",
          "meta": {},
          "sort_order": 0
        }
      ],
      "network_template": [],
      "db_connection": [
        {
          "id": "c2",
          "ref": "conn-42",
          "label": "Finance warehouse",
          "meta": {
            "type": "warehouse"
          },
          "sort_order": 0
        }
      ],
      "integration": [
        {
          "id": "c3",
          "ref": "confluence",
          "label": "Confluence",
          "meta": {},
          "sort_order": 0
        }
      ]
    },
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Retrieve a workspace by slug

GET /agent-hub-api/api/workspaces/slug/{slug}

Retrieves a workspace by its slug.

Resolves a slug to a workspace, preferring one you own, then a system workspace, then a company-visible one. Returns the same detail as Retrieve a workspace. A slug that resolves to nothing visible returns 404.

Authentication
Bearer token How it works

Path parameters

  • slug string Required

    The workspace slug.

Returns

Returns the workspace object, including its components, under data.

Errors

  • 404 No workspace with this slug is visible to the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/workspaces/slug/finance" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
    "name": "Finance",
    "slug": "finance",
    "visibility": "company",
    "is_default": false,
    "is_system": false,
    "domain_count": 1,
    "agent_count": 3,
    "explicit_agent_ids": [
      "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11"
    ],
    "component_counts": {
      "tool": 2,
      "network_template": 0,
      "db_connection": 1,
      "integration": 1
    },
    "created_at": "2026-09-01T09:30:00",
    "updated_at": "2026-09-01T09:30:00"
  }
}

Update a workspace

PUT /agent-hub-api/api/workspaces/{workspace_id}

Updates a workspace you own.

Applies a partial update using the same fields as create, plus color, visibility, and settings (merged over the stored settings). Only the owner may update a workspace; a workspace you do not own returns 404.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Body parameters application/json

  • name string

    Display name.

  • slug string

    URL-safe identifier; must stay unique in your scope.

  • description string

    Free-text summary.

  • icon string

    Icon reference.

  • color string

    Accent colour as #RRGGBB; an empty string clears it.

  • visibility string

    Who can read the workspace beyond you.

    Possible values
    • private
    • company
  • settings object

    Behaviour toggles to merge over the stored ones.

  • domain_ids array of strings

    Replacement set of mapped domains.

  • sort_order integer

    Ordering hint.

Returns

Returns the updated workspace object, including its components, under data.

Errors

  • 400 A field failed validation or the slug already exists in your scope.
  • 401 The request carries no usable user identity.
  • 404 No workspace with this identifier is owned by the caller.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Finance reporting workspace.",
    "settings": {
      "workspace_tools_first": false
    }
  }'
Response 200 
{
  "success": true,
  "data": {
    "id": "a2c4e6f8-1234-4abc-9def-0123456789ab",
    "name": "Finance",
    "slug": "finance",
    "description": "Finance reporting workspace.",
    "visibility": "company",
    "settings": {
      "apply_to_new_chats": true,
      "allow_callable_networks": true,
      "shared_knowledge": true,
      "workspace_tools_first": false
    },
    "is_default": false,
    "is_system": false,
    "updated_at": "2026-09-02T11:15:00"
  }
}

Delete a workspace

DEL /agent-hub-api/api/workspaces/{workspace_id}

Deletes a workspace you own, cascading its attached components and its explicit agent links; sessions that referenced it keep working with no workspace. Only the owner may delete it, so a workspace you do not own returns 404. A default workspace cannot be deleted.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Returns

Returns success: true and a confirmation message once the workspace is deleted.

Errors

  • 401 The request carries no usable user identity.
  • 404 No workspace with this identifier is owned by the caller.
  • 409 The workspace is a default workspace and cannot be deleted.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "message": "Workspace deleted"
}

List workspace agents

GET /agent-hub-api/api/workspaces/{workspace_id}/agents

Returns the agents belonging to a workspace.

Returns the agents in the workspace visible to the caller: those implied by the workspace's mapped domains together with those linked to it directly. A workspace not visible to the caller returns 404.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Returns

Returns a list of agent objects under data.

Errors

  • 404 No workspace with this identifier is visible to the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab/agents" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
      "name": "quarterly_report_writer",
      "model_name": "llama-3.3-70b-instruct",
      "is_user_created": true,
      "owner_user_id": 42
    }
  ]
}

Replace workspace agents

PUT /agent-hub-api/api/workspaces/{workspace_id}/agents

Replaces a workspace's directly linked agents.

Replaces the agents linked directly to the workspace. Agents implied by the workspace's mapped domains are unaffected. Every id must be an agent visible to you. Returns the resulting agent list (domain-implied together with the new explicit links). Only the owner may change a workspace's agents.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Body parameters application/json

  • agent_ids array of strings

    The agents to link, by identifier. An empty list clears the explicit links.

Returns

Returns the resulting list of agent objects under data.

Errors

  • 400 agent_ids is not a list, an id is malformed, or an agent is not visible to the caller.
  • 401 The request carries no usable user identity.
  • 404 No workspace with this identifier is owned by the caller.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab/agents" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_ids": [
      "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11"
    ]
  }'
Response 200 
{
  "success": true,
  "data": [
    {
      "id": "3f1a7b2e-9c4d-4e5a-8b1f-2d6c9a0e4f11",
      "name": "quarterly_report_writer",
      "model_name": "llama-3.3-70b-instruct",
      "is_user_created": true,
      "owner_user_id": 42
    }
  ]
}

List workspace components

GET /agent-hub-api/api/workspaces/{workspace_id}/components

Returns a workspace's attached components, grouped by type.

Returns the workspace's attached building blocks grouped by type: tool, network_template, db_connection, and integration. A workspace not visible to the caller returns 404.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Returns

Returns the grouped components under data.

Errors

  • 404 No workspace with this identifier is visible to the caller.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab/components" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "data": {
    "tool": [
      {
        "id": "c1",
        "ref": "web_search",
        "label": "Web search",
        "meta": {},
        "sort_order": 0
      }
    ],
    "network_template": [],
    "db_connection": [
      {
        "id": "c2",
        "ref": "conn-42",
        "label": "Finance warehouse",
        "meta": {
          "type": "warehouse"
        },
        "sort_order": 0
      }
    ],
    "integration": [
      {
        "id": "c3",
        "ref": "confluence",
        "label": "Confluence",
        "meta": {},
        "sort_order": 0
      }
    ]
  }
}

Replace workspace components

PUT /agent-hub-api/api/workspaces/{workspace_id}/components

Replaces a workspace's components for the given types.

Replaces the workspace's components for each type present in the body; a type you omit is left untouched. Each item needs a ref and may carry a label and a meta object. At most 200 items are allowed per type, and meta may be at most 4 KB when serialised. Only the owner may change a workspace's components.

Authentication
Bearer token How it works

Path parameters

  • workspace_id string Required

    The workspace identifier (UUID).

Body parameters application/json

  • components object Required

    Components grouped by type. Keys are tool, network_template, db_connection, integration; each maps to a list of items.

    Show child parameters Hide child parameters
    • ref string

      Opaque reference to the underlying resource. Required per item.

    • label string

      Display label.

    • meta object

      Metadata snapshot; at most 4 KB serialised.

Returns

Returns the resulting grouped components under data.

Errors

  • 400 An unknown component type was given, an item is missing a ref, a per-type limit was exceeded, or meta was too large.
  • 401 The request carries no usable user identity.
  • 404 No workspace with this identifier is owned by the caller.
Request 
curl -X PUT "$VDF_BASE_URL/agent-hub-api/api/workspaces/a2c4e6f8-1234-4abc-9def-0123456789ab/components" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "components": {
      "tool": [
        {
          "ref": "web_search",
          "label": "Web search"
        }
      ]
    }
  }'
Response 200 
{
  "success": true,
  "data": {
    "tool": [
      {
        "id": "c1",
        "ref": "web_search",
        "label": "Web search",
        "meta": {},
        "sort_order": 0
      }
    ],
    "network_template": [],
    "db_connection": [
      {
        "id": "c2",
        "ref": "conn-42",
        "label": "Finance warehouse",
        "meta": {
          "type": "warehouse"
        },
        "sort_order": 0
      }
    ],
    "integration": [
      {
        "id": "c3",
        "ref": "confluence",
        "label": "Confluence",
        "meta": {},
        "sort_order": 0
      }
    ]
  }
}