# Sync Workspace API

 # Sync Workspace API
Workspace-specific services for content management, project organization, and file processing.
## Workspace Services
The Workspace APIs allow access to the resources contained within Workspaces and Dataspaces. Although Workspaces and Dataspaces are distinct, Dataspaces have no compute of their own, so operations on Dataspace resources must always be performed *through* a chosen workspace.
Workspaces are bundled, fully-managed computational services used to: - Upload, process, and manage content files - Search and retrieve content with advanced filtering - Query content using AI with library citations and web search integration - Run AI workflows on the content - Organize content into projects according to business workflows - Generate file derivatives (images, thumbnails) and extract metadata - Handle content indexing with automated categorization
## Content Processing
When files are uploaded, they undergo asynchronous processing which may include: - Virus scanning and security validation - File format conversion and derivative generation (TIFF, JPEG thumbnails) - Automated metadata extraction using AI - Content categorization and indexing according to dataspace ontology
Processing status can be tracked using the Workflow Execution API.
## Projects vs Content Organization
- **Content**: Individual files with metadata, organized by categories defined in the dataspace ontology - **Projects**: Business workflow containers that group disparate content items according to business rules (e.g., application packets, case files)
## Authentication
All endpoints require authentication using a bearer token. 

Version: 1.0.0
License: Commercial

## Servers

Production - Workspace Services
```
https://{workspaceId}.syncdocs.ai/api
```

Variables:
- `workspaceId`: Your workspace identifier
Default: "your-workspace"

Development server
```
/api
```

## Security

### bearerAuth

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Sync Workspace API](https://docs.syncdocs.ai/_bundle/api/workspace-openapi.yaml)

## Projects

Project management operations. Projects group content items according to business workflows and processes.

### Associate content with a project

 - [PUT /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/associatecontentwithproject.md)

### Dissociate content from a project

 - [DELETE /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/dissociatecontentfromproject.md)

### Get all content associated with a project

 - [GET /projects/{dataspaceId}/{projectId}/content](https://docs.syncdocs.ai/api/workspace-openapi/content/getprojectcontent.md)

### Create a new project

 - [POST /projects/{dataspaceId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/createproject.md)

### List all projects in a dataspace

 - [GET /projects/{dataspaceId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/listprojects.md)

### Get a project by ID

 - [GET /projects/{dataspaceId}/{projectId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/getprojectbyid.md)

### Update a project

 - [PUT /projects/{dataspaceId}/{projectId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/updateproject.md)

### Delete a project

 - [DELETE /projects/{dataspaceId}/{projectId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/deleteproject.md)

### Associate content with a project

 - [PUT /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/associatecontentwithproject.md)

### Dissociate content from a project

 - [DELETE /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/dissociatecontentfromproject.md)

### Get all content associated with a project

 - [GET /projects/{dataspaceId}/{projectId}/content](https://docs.syncdocs.ai/api/workspace-openapi/projects/getprojectcontent.md)

## Content

Content management operations. Handle file uploads, processing, metadata extraction, and content retrieval with advanced filtering capabilities.

### Associate content with a project

 - [PUT /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/associatecontentwithproject.md)

### Dissociate content from a project

 - [DELETE /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/dissociatecontentfromproject.md)

### Get all content associated with a project

 - [GET /projects/{dataspaceId}/{projectId}/content](https://docs.syncdocs.ai/api/workspace-openapi/content/getprojectcontent.md)

### Create new content

 - [POST /content/{dataspaceId}](https://docs.syncdocs.ai/api/workspace-openapi/content/createcontent.md): Upload files using multipart/form-data to directly upload files.
Comprehensive Validation System:
The content creation endpoint performs multiple layers of validation to ensure data integrity:
1. Schema Validation: - categoryId: Must be a valid UUID - metadata: Must be a valid JSON object (if provided) - fileFormat: Required string specifying the file's MIME type - fileName: Optional string for the file name
2. Business Logic Validation: - Category Existence: Validates that the specified categoryId exists in the dataspace's ontology - Metadata Query Binding: Ensures all provided metadata queries are bound to the specified category - Data Type Validation: Verifies that metadata values match the expected data types (STRING, SHORT_STRING, NUMBER, BOOLEAN, DATE)
3. Required Metadata Validation: - Default Behavior: validateRequiredMetadata defaults to true when not specified - When enabled (default): Enforces that all required metadata queries and unique index elements are provided - When disabled (validateRequiredMetadata=false): Allows content creation without required metadata queries
4. File Upload Validation: - File must be provided in the multipart form data - File format fallback: Uses detected MIME type if fileFormat not specified - File name fallback: Uses original filename if fileName not specified
Query Parameters: - validateRequiredMetadata: Optional boolean (defaults to true) - Set to "false" to skip required metadata validation - Set to "true" or omit to enforce required metadata validation
Error Scenarios: - 400 Bad Request: Invalid schema, category not found, unbound metadata queries, type mismatches, missing required metadata - 401 Unauthorized: Invalid or missing authentication - 404 Not Found: Dataspace not found

### Get content by ID

 - [GET /content/{dataspaceId}/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/getcontentbyid.md)

### Update content

 - [PUT /content/{dataspaceId}/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/updatecontent.md)

### Delete content

 - [DELETE /content/{dataspaceId}/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/content/deletecontent.md)

### Download content file

 - [GET /content/{dataspaceId}/{contentId}/download](https://docs.syncdocs.ai/api/workspace-openapi/content/downloadcontent.md): Download the actual file associated with the content item

### Count content items

 - [GET /content/{dataspaceId}/count](https://docs.syncdocs.ai/api/workspace-openapi/content/countcontent.md): Returns the total count of content items in a dataspace with optional filtering.
Filtering Options: - categoryId: Filter by specific category UUID - fileFormat: Filter by file format/MIME type - dateFrom: Filter by creation date from (ISO 8601 format) - dateTo: Filter by creation date to (ISO 8601 format)
Features: - Efficient counting using SQL COUNT queries - Multiple filter combinations supported - Date range filtering for temporal analysis - Category-specific content counting - File format filtering for content type analysis
Example Usage: - Count all content: GET /content/sds-12345678/count - Count by category: GET /content/sds-12345678/count?categoryId=123e4567-e89b-12d3-a456-426614174001 - Count PDFs: GET /content/sds-12345678/count?fileFormat=application/pdf - Count recent content: GET /content/sds-12345678/count?dateFrom=2024-01-01T00:00:00Z - Combined filters: GET /content/sds-12345678/count?categoryId=123e4567-e89b-12d3-a456-426614174001&fileFormat=application/pdf
Performance: - Optimized for large datasets using database indexes - Returns exact counts without loading content items into memory - Suitable for dashboard statistics and analytics

### Fetch content with advanced filtering, pagination, and version grouping

 - [POST /content/{dataspaceId}/fetch](https://docs.syncdocs.ai/api/workspace-openapi/content/fetchcontent.md): Retrieves a list of content items with comprehensive filtering capabilities and optional version grouping.
Top-level Field Filtering: - contentId, categoryId, fileName, fileFormat, createdAt, updatedAt
Metadata Field Filtering: - Filter on any metadata query using nested structure: metadata: { "keyName": value }
Advanced Operators: - eq, ne - Equality/inequality - gt, gte, lt, lte - Comparison (dates/numbers) - between - Range filtering: [min, max] - in, nin - Array membership - contains, startsWith, endsWith - String operations - exists - Field presence check
Version Grouping: - groupByVersion: When true, groups content by version strings and returns only the most recent item per version - Version strings are calculated from category name + metadata values where uniqueIndexElement is true - Format: "category_name_value1_value2" (lowercase, underscore-separated) - Returns relatedVersions array containing objects with id, filename, and created_at for other content items sharing the same version - When false or omitted, relatedVersions is null and all content is returned - Special case: When filtering by contentId AND groupByVersion is true, returns the specified content item with all its related versions attached
Logging Control: - disabledLogging: When true, disables query logging for this request (both console logs and database query logs) - When false or omitted, normal logging behavior is maintained - Useful for high-frequency operations or when logging is not desired
Features: - Cursor-based pagination with pageSize and cursor - Field selection with fields parameter - Mixed filtering (combine top-level and metadata filters) - Version grouping for content deduplication - Optional logging control for performance optimization - Backward compatible with empty filters
Example Request (with version grouping and disabled logging): json { "query": "annual report", "groupByVersion": true, "disabledLogging": false, "filters": { "fileFormat": { "in": ["application/pdf"] }, "createdAt": { "gte": "2025-01-01T00:00:00Z" }, "metadata": { "Status": { "ne": "Archived" }, "Business Type": { "in": ["Restaurant", "Retail"] } } } } 
Example Response (with version grouping): json { "contentItems": [ { "contentId": "123e4567-e89b-12d3-a456-426614174000", "categoryId": "456e7890-e89b-12d3-a456-426614174001", "fileName": "license_v2.pdf", "createdAt": "2025-01-15T10:30:00Z", "relatedVersions": [ { "id": "789e0123-e89b-12d3-a456-426614174002", "filename": "license_v1.pdf", "created_at": "2025-01-14T09:15:00Z" } ] } ] }

### Ingest content with a workflow

 - [POST /content/{dataspaceId}/{contentId}/ingest](https://docs.syncdocs.ai/api/workspace-openapi/content/ingestcontent.md): Triggers workflow execution for a specific content item and returns the complete workflow execution object. The system automatically selects the first available agent for the user's account.
Workflow Ingestion Process: 1. Validates that the content item exists 2. Validates that the specified workflow exists 3. Automatically selects the first available agent for the user's account 4. Creates a workflow execution record 5. Executes all tasks in the workflow sequentially in the background using the selected agent 6. Returns the complete workflow execution object immediately
Response Object: The endpoint returns a complete workflow execution object containing: - id: Unique identifier for this workflow execution - workflowId: ID of the workflow being executed - contentId: ID of the content being processed - dataspaceId: ID of the dataspace - status: Current status ('started', 'completed', or 'failed') - startedAt: Timestamp when execution began - completedAt: Timestamp when execution finished (null if still running) - errorMessage: Error details if execution failed (null if successful)
Features: - Asynchronous workflow execution - Comprehensive validation before execution - Automatic agent selection for the user's account - Detailed logging and error handling - Database tracking of workflow and task executions - Complete workflow execution object response
Example Usage: POST /api/content/sds-12345678/550e8400-e29b-41d4-a716-446655440000/ingest?workflowId=8a0667a8-a35e-4b0a-8a95-07b4fd5ac7de
The workflow will execute in the background, and you can monitor its progress using the returned workflow execution object.

### Query content using AI assistant with vector store access

 - [POST /content/{dataspaceId}/query](https://docs.syncdocs.ai/api/workspace-openapi/content/querycontent.md): Performs intelligent queries on content using OpenAI's assistant with vector store access.
Query Process: 1. Agent Selection: Uses the specified agent's instructions as the system prompt, or defaults to research assistant instructions 2. Content Filtering: Uses the provided filters to select relevant content items from the dataspace 3. Vector Store Access: Retrieves the dataspace's vector store containing document embeddings 4. AI Assistant Creation: Creates a temporary OpenAI assistant with access to the vector store 5. Query Execution: Processes the user's query against the filtered content using the AI assistant 6. Citation Parsing: Extracts file IDs from the AI response citations 7. Content Retrieval: Fetches full content objects for all cited documents
Agent System: - Optional Agent ID: Provide an agentId to use custom agent instructions as the system prompt - Default Behavior: Without an agent ID, uses built-in research assistant instructions - Agent Instructions: The agent's instructions field becomes the system prompt for the AI assistant - Research Agent: Look for an agent named "Research Assistant Agent" for the default research experience
Request Body: - filters: Advanced filtering options to select specific content (uses unified ContentFiltersSchema) - query: The question or query to ask about the filtered content - agentId: (Optional) UUID of the agent whose instructions to use as system prompt
Response Fields: - query: The original user query - response: AI assistant's response with citations in simplified format - analyzedDocumentCount: Number of documents that were analyzed and available for querying - citedContent: Array of full content objects that were actually cited in the AI response
Citation Format: The AI response includes citations in simplified format: 【0】, 【1】, etc., where numbers reference the citedContent array indices.
Performance Notes: - Creates and destroys a temporary OpenAI assistant for each query - Processes up to 9999 content items for analysis - Response time depends on query complexity and document count - Agent lookup adds minimal overhead when agent ID is provided

### Associate content with a project

 - [PUT /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/associatecontentwithproject.md)

### Dissociate content from a project

 - [DELETE /projects/{dataspaceId}/{projectId}/content/{contentId}](https://docs.syncdocs.ai/api/workspace-openapi/projects/dissociatecontentfromproject.md)

### Get all content associated with a project

 - [GET /projects/{dataspaceId}/{projectId}/content](https://docs.syncdocs.ai/api/workspace-openapi/projects/getprojectcontent.md)

## Workflow Executions

Workflow execution monitoring operations. Track the status and progress of AI workflow executions on content.

### List workflow executions

 - [GET /workflow-executions](https://docs.syncdocs.ai/api/workspace-openapi/workflow-executions/listworkflowexecutions.md): Returns a paginated list of workflow executions. Supports filtering by dataspace ID, status, workflow ID, and content ID. Since workflow executions are stored at the workspace level, dataspace filtering is optional.

### Get workflow execution by ID

 - [GET /workflow-executions/{workflowExecutionId}](https://docs.syncdocs.ai/api/workspace-openapi/workflow-executions/getworkflowexecutionbyid.md): Returns detailed information about a specific workflow execution, including all associated TaskExecution objects that represent the individual tasks that were executed as part of this workflow.

## Batch Workflow Executions

Batch workflow execution operations. Execute workflows on multiple content items based on filters across multiple dataspaces.

### Create and execute batch workflow

 - [POST /batch-workflow-executions](https://docs.syncdocs.ai/api/workspace-openapi/batch-workflow-executions/createbatchworkflowexecution.md): Creates a batch workflow execution that discovers content across multiple dataspaces using the provided filters, then executes the specified workflow on each matching content item. The system automatically selects the first available agent for the user's account to execute the workflow tasks. The workflow execution reuses the existing single-content workflow logic. Returns immediately with a batch execution record while processing continues in the background.
File Format Filters: The API supports both user-friendly file types and MIME types for filtering: - User-friendly: { "in": ["pdf", "docx", "xlsx"] } - MIME types: { "in": ["application/pdf", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"] }
Supported user-friendly file types: pdf, docx, xlsx, pptx, txt, doc, xls, ppt, json, xml, csv, html, css, js, jpg, jpeg, png, gif, bmp, svg, webp, tiff, mp4, avi, mov, wmv, flv, webm, mkv, mp3, wav, flac, aac, ogg, m4a, zip, rar, 7z, tar, gz, bz2.

### Get batch workflow execution status

 - [GET /batch-workflow-executions/{batchExecutionId}/status](https://docs.syncdocs.ai/api/workspace-openapi/batch-workflow-executions/getbatchworkflowexecutionstatus.md): Returns real-time status information about a batch workflow execution, including progress tracking of individual workflow executions. This provides a summary of how many executions are completed, failed, or still in progress, along with the overall batch status.

## Task Executions

Task execution monitoring operations. Track individual task executions within workflows and retrieve their outputs.

### Get a paginated list of task executions

 - [GET /task-executions](https://docs.syncdocs.ai/api/workspace-openapi/task-executions/listtaskexecutions.md): List task executions with optional filtering

### Retrieve a single task execution by its ID

 - [GET /task-executions/{taskExecutionId}](https://docs.syncdocs.ai/api/workspace-openapi/task-executions/gettaskexecutionbyid.md): Get task execution by ID

## Task Execution Outputs

Task execution output retrieval operations. Access the results and outputs generated by completed task executions.

### Retrieve the output data from a completed task execution

 - [GET /task-execution-outputs/{taskNameSlug}/{dataspaceId}/{taskExecutionId}](https://docs.syncdocs.ai/api/workspace-openapi/task-execution-outputs/gettaskexecutionoutput.md): Get task execution output by parameters

## Registered Workflows

Registered workflow operations. Access workflows cached from sync-apis for fast lookup during workflow execution.

### List registered workflows

 - [GET /register-workflows](https://docs.syncdocs.ai/api/workspace-openapi/registered-workflows/listregisteredworkflows.md): Returns a paginated list of registered workflows cached from sync-apis. Supports filtering by account ID and workflow name. These workflows are cached locally for fast access during workflow execution.

## Query Logs

Query logging and retrieval operations. Track and analyze API operations performed on resources with detailed audit trails.

### Get a single query log by ID

 - [GET /query-logs/{queryLogId}](https://docs.syncdocs.ai/api/workspace-openapi/query-logs/getquerylogbyid.md): Retrieves a specific query log record by its unique identifier. Useful for examining the details of a particular API operation that was logged.

### Get paginated list of query logs with filtering

 - [GET /query-logs](https://docs.syncdocs.ai/api/workspace-openapi/query-logs/getquerylogs.md): Retrieves a paginated list of query log records with optional filtering.
Key Features: - Cursor-based pagination with pageSize and cursor - Multiple filter options to narrow down results - Operation tracking - see all API operations performed on content - Audit trail - complete history of who did what and when
Common Use Cases: - Track content operations by a specific user - Monitor operations on a particular dataspace - Audit trail for compliance and debugging - Performance analysis of API usage
Filter Examples: - Get all CREATE operations: ?operationType=CREATE - Get operations by user: ?userId=scd-dev00001 - Get operations in date range: ?dateFrom=2025-06-10T00:00:00Z&dateTo=2025-06-10T23:59:59Z - Get operations on specific content: ?contentId=98765432-1abc-def0-1234-56789abcdef0

## Content Upload Sessions

Content upload session management operations. Handle reliable file uploads through chunked upload sessions with progress tracking.

### Create a new content upload session

 - [POST /content-upload-sessions](https://docs.syncdocs.ai/api/workspace-openapi/content-upload-sessions/createuploadsession.md): Initializes a new upload session for reliable file uploads.
Features: - Supports files up to 10GB - Optimized for large file transfers - Session expiration and cleanup - Progress tracking
Process: 1. Create upload session with file metadata 2. Upload file content using the session ID 3. System automatically processes the upload when complete 4. Returns content ID when finished
Upload Optimization: The system automatically optimizes the upload process for reliable transfer of large files with automatic retry and error handling.

### Upload file content

 - [POST /content-upload-sessions/{sessionId}/chunks](https://docs.syncdocs.ai/api/workspace-openapi/content-upload-sessions/uploadchunk.md): Uploads file content for an existing upload session.
Upload Process: - Upload content reliably with automatic error handling - System tracks progress automatically - Optional content integrity validation via checksum - Processes file when upload is complete - Creates content record upon completion
Upload Flow: 1. Upload content using multipart/form-data 2. System processes content reliably on server 3. When upload is complete, assembles into complete file 4. Stores complete file in secure storage 5. Creates content record in database 6. Cleans up temporary files
Error Handling: - Invalid content is rejected with detailed error messages - Failed processing triggers automatic cleanup - Session expiration prevents orphaned files

### Get upload session status

 - [GET /content-upload-sessions/{sessionId}](https://docs.syncdocs.ai/api/workspace-openapi/content-upload-sessions/getuploadsession.md): Retrieves the current status and progress of an upload session.
Session Statuses: - pending: Session created, awaiting content - uploading: Receiving content - assembling: Upload complete, processing file - completed: Upload successful, content created - failed: Upload failed, session invalid - expired: Session expired, cleanup scheduled
Progress Tracking: Use this endpoint to monitor upload progress by checking: - uploadedChunks vs totalChunks for progress percentage - status for current phase - contentId when upload completes