Execute Tool

Execute one of Sharely.ai's first-party agent tools over REST. This gives non-TypeScript agents the same knowledge primitives the Server SDK exposes — search, retrieval, taxonomy browsing, and workspace metadata — with RBAC applied server-side.

POST /v1/workspaces/{workspaceId}/agent/tools/{name}/execute

Request Body

FieldTypeRequiredDescription
inputobjectYesTool-specific input (see catalog below)
contextobjectNoExecution context
context.spaceIdUUIDNoScope to a space
context.userIdUUIDNoActing user
context.roleIdUUIDNoRBAC role to scope results to (validated against workspace roles)
context.languageIdstringNoKnowledge language filter (e.g. en, es)
context.topKnumberNoResult limit hint (min 1, max 50)

Response (200 OK)

{
  "output": { /* tool-specific output */ },
  "sources": [ /* optional citation objects */ ]
}

If the tool itself fails, the response includes an error field instead of throwing:

{ "output": null, "error": "Knowledge item not found" }

Errors

  • 400 - Invalid input for the tool's schema
  • 404 - Unknown tool name, workspace not found, or context.roleId not found

Tool Catalog

semantic_search

Vector search over workspace knowledge. Backed by the same engine as RAG Query, with output shaped for agent loops.

Input:

FieldTypeRequiredDescription
textstringYesQuery text
topKnumberNoMin 1, max 10, default 10
languageIdstringNoKnowledge language filter

Output: knowledgeResults (scored passages with id, score, text, title, source, knowledgeId, language), plus a sources citation array suitable for the sources field when storing messages.

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/tools/semantic_search/execute' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "input": { "text": "refund policy", "topK": 5 } }'

search_knowledge

Keyword search over knowledge items.

Input:

FieldTypeRequiredDescription
querystringYesSearch term
limitnumberNoMin 1, max 50, default 10

Output: knowledgeResults — items with id, type, title, content, and file metadata (filename, mimetype) where applicable.

get_knowledge_item

Retrieve a single knowledge item with its content items.

Input:

FieldTypeRequiredDescription
knowledgeIdUUIDYesThe knowledge item
itemIdUUIDNoA specific content item within it

Output: knowledge (id, type, content, metadata) and items (content chunks).

list_taxonomies

Input: limit (number, optional, default 10)

Output: taxonomies — [{ "id", "name", "status" }] where status is DRAFT or PUBLISHED.

get_taxonomy_knowledge

Input: taxonomyId (UUID, required)

Output: categories — each with id, name, and its assigned knowledges ([{ "id", "title" }]).

get_workspace_stats

Input: none ("input": {})

Output:

{ "totalKnowledge": 1240, "totalSpaces": 87, "totalThreads": 342 }

list_roles

Input: none ("input": {})

Output: roles — [{ "id", "name", "description" }].

RBAC Notes

  • Pass context.roleId to scope results to a role; with workspace RBAC active, tools filter knowledge to that role's assignments
  • The same tool definitions ship in @sharelyai/tools as JSON-schema specs for Anthropic, OpenAI, Vercel AI SDK, and LangChain tool-use loops

Related