Sharely.ai API Reference

Welcome to the Sharely.ai API documentation. The Sharely.ai API allows you to programmatically manage knowledge, spaces, roles, and more within your Sharely.ai workspace.

API Version

The current API version is v1 and is in BETA. All v1 endpoints include an X-API-Version: v1 header in their responses.

Base URL

All API requests should be made to:

https://api.sharely.ai/v1/workspaces/{workspaceId}/

Replace {workspaceId} with your actual workspace ID.

Authentication

All API requests require authentication using a Bearer token. See the Authentication guide for details on obtaining and using API keys.

API Resources

The Sharely.ai API is organized around these core resources:

Workspace Management

Manage workspace settings, RBAC status, and monitor background job processing.

• Workspace API Reference - Get workspace details, enable/disable RBAC, check background jobs

Knowledge Management

Manage your workspace's knowledge base - create, search, and organize knowledge items including files, URLs, and text content.

• Knowledge API Reference - Upload files, crawl websites, create text content, assign to roles

Roles (RBAC)

Define roles with unique identifiers and manage role-based access control for knowledge filtering.

• Roles API Reference - Create roles, find by customerRoleId, assign to knowledge/taxonomies

Taxonomies

Organize categories hierarchically with role and language assignments for multilingual knowledge filtering.

• Taxonomy API Reference - Create, publish, assign roles/languages, manage categories

Categories

Create hierarchical knowledge organization with parent-child relationships and metadata schemas.

• Categories API Reference - Create categories, build trees, assign knowledge, search

Spaces

Manage user spaces and ensure proper space provisioning for your users with role-based access.

• Spaces API Reference - Provision user spaces, activate with roles

Rate Limits

Rate limits are applied per API key. Contact support if you need higher rate limits for your use case.

Support

For API support, questions, or feedback:

• Email: support@sharely.ai
• Documentation: https://docs.sharely.ai (opens in a new tab)

Common Patterns

Workspace ID

Most API endpoints require a workspaceId in the URL path. You can find your workspace ID in your Sharely.ai dashboard settings.

Asynchronous Processing

Some operations (like knowledge creation, role management, taxonomy operations, and role/category assignments) are processed asynchronously using background workflows powered by Temporal. These operations:

• Return immediately with a workflowId
• Process in the background (typically completing within 5-10 seconds)
• Support eventual consistency patterns
• Are idempotent and automatically retry on failure

When an operation supports async mode, you can use the status: "BACKGROUND_START" parameter to queue the operation and receive an immediate response.

Checking Workflow Status

Use the Background Jobs endpoint to monitor async operation status:

POST /v1/workspaces/{workspaceId}/background-jobs
Content-Type: application/json
 
{
  "workflowIds": ["workflow-id-1", "workflow-id-2"]
}

Response:

{
  "jobs": [
    {
      "workflowId": "workflow-id-1",
      "status": "COMPLETED",
      "result": { ... },
      "startTime": "2025-11-14T10:30:00Z",
      "endTime": "2025-11-14T10:30:05Z"
    }
  ]
}

Status Values:

• RUNNING: Operation in progress
• COMPLETED: Operation finished successfully
• FAILED: Operation encountered an error
• CANCELLED: Operation was cancelled

Recommended Approach:

• Poll the background-jobs endpoint with exponential backoff
• Implement retry logic for failed operations
• Set appropriate timeouts (most operations complete within 5-10 seconds)
• Use the workflowId returned from async operations for tracking

Learn more: Background Jobs API

Response Format

All API responses are in JSON format. Successful responses typically return a 200 or 201 status code with the relevant data. Error responses include an appropriate HTTP status code and error details.

Getting Started

Quick Start Guide

1. Obtain your API key - Generate access token from API key
2. Enable RBAC (Optional) - Activate role-based access control
3. Create roles - Define user permission groups
4. Create taxonomies - Set up category organization
5. Create categories - Build hierarchical structure
6. Upload knowledge - Add content to your workspace
7. Assign roles to knowledge - Control access to content
8. Provision user spaces - Enable user interactions

Common Workflows

Workflow 1: Basic Knowledge Management (No RBAC)

1. Generate access token
2. Upload knowledge items (files, URLs, text)
3. Search knowledge
4. Provision user spaces

Workflow 2: Enterprise RBAC Setup

1. Generate access token
2. Enable RBAC on workspace
3. Create roles with customerRoleId
4. Create taxonomies
5. Assign languages to taxonomies
6. Create categories within taxonomies
7. Assign roles to taxonomies/categories
8. Upload knowledge and assign to roles
9. Publish taxonomies
10. Provision user spaces with role-bound tokens

Workflow 3: Multilingual Content Filtering

1. Create taxonomy
2. Assign multiple languages (en, es, pt)
3. Create categories
4. Upload knowledge in different languages
5. Assign language metadata to knowledge
6. Filter content by language and role

Error Handling

See the Error Reference for details on error codes and troubleshooting common issues.