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

Shares

A share, or grant, gives one person or everyone in a permission group access to a resource you own: a skill, a custom HTTP tool, an MCP server, an agent or a workspace. What a grant gives depends on the resource type, as described under resource_type in Share a resource. Only the owner of a resource can list, create or revoke its shares.

A resource is addressed by its type and id. Sharing with a grantee who already has a grant updates that grant instead of adding a second one, and revoking a grant removes the access it gave.

Endpoints 3

Paths are relative to /agent-hub-api

The share object

One grant of access to a resource.

Attributes

  • id string

    Unique identifier for the grant (a UUID).

  • resource_type string

    Type of the shared resource.

    Possible values
    • skill
    • tool
    • mcp_server
    • agent
    • workspace
  • resource_id string

    Id of the shared resource. For skills this is always the skill's id, even when you shared it by name.

  • grantee_type string

    Whether the grant is for one person or for a permission group.

    Possible values
    • user
    • group
  • grantee_id integer

    Id of the user or permission group that received access.

  • permission string

    Permission recorded on the grant.

    Possible values
    • use
    • edit
  • granted_by_user_id nullable integer

    Id of the user who created or last changed the grant.

  • created_at string

    When the grant was created (UTC, ISO 8601).

The share object 
{
  "id": "6e2b9d4f-1a7c-4f35-b8e0-2d9c5a1f7e46",
  "resource_type": "skill",
  "resource_id": "b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69",
  "grantee_type": "user",
  "grantee_id": 57,
  "permission": "use",
  "granted_by_user_id": 42,
  "created_at": "2026-09-03T08:20:15.674302"
}

List shares

GET /agent-hub-api/api/shares/{resource_type}/{resource_id}

Returns every grant on a resource the caller owns.

Grants are ordered by grantee_type, then grantee_id.

Authentication
Bearer token How it works

Path parameters

  • resource_type string Required

    Type of the resource.

    Possible values
    • skill
    • tool
    • mcp_server
    • agent
    • workspace
  • resource_id string Required

    Id of the resource: the skill's id or name, the tool's tool_name, or the id of the MCP server, agent or workspace.

Returns

Returns shares, a list of share objects.

Errors

  • 400 resource_type is not one of the supported types.
  • 403 You are not the owner of this resource.
  • 404 No resource of this type has this id.
Request 
curl "$VDF_BASE_URL/agent-hub-api/api/shares/skill/b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true,
  "shares": [
    {
      "id": "9a4c7e21-5d3b-4f86-a0e2-7b1d9c3f5e68",
      "resource_type": "skill",
      "resource_id": "b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69",
      "grantee_type": "group",
      "grantee_id": 12,
      "permission": "use",
      "granted_by_user_id": 42,
      "created_at": "2026-09-02T15:02:48.913027"
    },
    {
      "id": "6e2b9d4f-1a7c-4f35-b8e0-2d9c5a1f7e46",
      "resource_type": "skill",
      "resource_id": "b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69",
      "grantee_type": "user",
      "grantee_id": 57,
      "permission": "use",
      "granted_by_user_id": 42,
      "created_at": "2026-09-03T08:20:15.674302"
    }
  ]
}

Share a resource

POST /agent-hub-api/api/shares/{resource_type}/{resource_id}

Grants a user or a permission group access to a resource the caller owns.

Creates the grant, or updates permission on an existing grant for the same grantee. Either way the response is 201 with the resulting grant.

Authentication
Bearer token How it works
Permission
Your administrator can limit sharing to roles that may share this type of resource, and publishing to groups to roles that may do so.

Path parameters

  • resource_type string Required

    Type of the resource. A grant on a skill puts it in the grantee's skill list, where they can bind it to their agents. A grant on a tool makes a custom HTTP tool available in the grantee's tool catalogue. A grant on an mcp_server makes the server and all of its tools visible to the grantee. A grant on an agent lets the grantee list it in and link it to their workspaces. A grant on a workspace is recorded, but who can open a workspace is still decided by the workspace's own visibility.

    Possible values
    • skill
    • tool
    • mcp_server
    • agent
    • workspace
  • resource_id string Required

    Id of a resource you own: the skill's id (a skill name is also accepted), the tool's tool_name, or the id of the MCP server, agent or workspace.

Body parameters application/json

  • grantee_type string

    Share with one person (user) or with everyone in a permission group (group). Also accepted as granteeType.

    Defaults to user.

    Possible values
    • user
    • group
  • grantee_id integer Required

    Id of the user or permission group. Also accepted as granteeId.

  • permission string

    Permission to record on the grant. Grantees currently get the same access with either value; neither lets them change the resource.

    Defaults to use.

    Possible values
    • use
    • edit

Returns

Returns share, the resulting share object.

Errors

  • 400 resource_type, grantee_type or permission is not one of the allowed values, or grantee_id is missing or not an integer.
  • 403 You are not the owner of this resource, or your role does not allow this kind of share.
  • 404 No resource of this type has this id.
  • 503 Sharing is not available yet because your deployment's database upgrade has not been completed.
Request 
curl -X POST "$VDF_BASE_URL/agent-hub-api/api/shares/skill/b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "grantee_type": "user",
    "grantee_id": 57,
    "permission": "use"
  }'
Response 201 
{
  "success": true,
  "share": {
    "id": "6e2b9d4f-1a7c-4f35-b8e0-2d9c5a1f7e46",
    "resource_type": "skill",
    "resource_id": "b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69",
    "grantee_type": "user",
    "grantee_id": 57,
    "permission": "use",
    "granted_by_user_id": 42,
    "created_at": "2026-09-03T08:20:15.674302"
  }
}

Revoke a share

DEL /agent-hub-api/api/shares/{resource_type}/{resource_id}/{grantee_type}/{grantee_id}

Removes one grant from a resource the caller owns.

The grantee loses the access the grant gave. As the owner you can always revoke a grant, even if your role no longer allows creating that kind of share.

Authentication
Bearer token How it works

Path parameters

  • resource_type string Required

    Type of the resource.

    Possible values
    • skill
    • tool
    • mcp_server
    • agent
    • workspace
  • resource_id string Required

    Id of a resource you own, as in Share a resource.

  • grantee_type string Required

    Type of the grantee.

    Possible values
    • user
    • group
  • grantee_id integer Required

    Id of the user or permission group.

Returns

Returns success: true once the grant is removed.

Errors

  • 400 resource_type is not one of the supported types.
  • 403 You are not the owner of this resource.
  • 404 No resource of this type has this id, or it has no grant for this grantee.
Request 
curl -X DELETE "$VDF_BASE_URL/agent-hub-api/api/shares/skill/b7e3d2a1-5c4f-4e8b-a9d6-1f2e3c4b5a69/user/57" \
  -H "Authorization: Bearer $VDF_ACCESS_TOKEN"
Response 200 
{
  "success": true
}