# 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)