Skip to content
API Reference/
/Metadata Queries

SyncDocs Admin API (1.0.0)

SyncDocs Admin API

Complete enterprise content management system (ECM) core APIs for accessing ECM functionality programmatically.

Architecture Overview

When you start with Sync, you are assigned an Account with a unique ID. Each account can have:

  • Dataspaces: Fully isolated data segments within an account, similar to separate databases. Each dataspace is used to isolate different business use cases within a single enterprise. - Workspaces: Virtual computing resources for storing, retrieving and manipulating content (managed separately via Workspace APIs) - Libraries: External content sources that can be scraped and indexed for use as citation sources in AI queries - Users and Agents: Can interact with Dataspaces/Workspaces with assigned roles - Ontologies: Define how content is organized within dataspaces

Dataspace Resources

Each Dataspace contains: - A unique Ontology that defines the business-purpose categorization and metadata structure - Categories: Represent the grouping or classification of content (taxonomy) - Metadata Queries: Specific metadata fields that can be associated with content and bound to categories - A collection of Content and Projects (managed via Workspace APIs)

Metadata Query Binding

Metadata Queries can be bound to Categories to indicate required attributes for content in that category. When binding, you can specify: - Whether the attribute is required/mandatory for every Content item in that category - Whether the attribute should be part of the Unique Index (content with same unique index values are considered versions of the same content)

Authentication

All endpoints require authentication using a bearer token and a valid account ID.

Download OpenAPI description
sync-cloud-openapi.json
sync-cloud-openapi.yaml
Overview
License
Proprietary
Languages
Servers
Mock server
https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/
Production - Sync Cloud Admin Services
https://cloud.syncdocs.ai/api/
Development server
https://docs.syncdocs.ai/api/

Accounts

Account management operations. Each account represents a unique enterprise customer with isolated resources.

Operations

Dataspaces

Dataspace management operations. Dataspaces are fully isolated data segments within an account, similar to separate databases for different business use cases.

Operations

Workspaces

Workspace management operations. Workspaces are virtual computing resources that provide stateless computational services for content processing.

Operations

Ontologies

Ontology management operations. Ontologies define the categorization, indexing and metadata tagging structure for content within dataspaces.

Operations

Categories

Category management operations. Categories represent the grouping or classification of content within a dataspace (taxonomy).

Operations

Metadata Queries

Metadata key management operations. Metadata keys define specific metadata fields that can be associated with content and bound to categories.

Operations

Create a new metadata query

Request

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

Example: 123e4567-e89b-12d3-a456-426614174001
Bodyapplication/json
namestringnon-emptyrequired

Name of the metadata query

Example: "Author Name"
descriptionstring

Description of the metadata query

Example: "The name of the document author"
dataTypestringrequired

Data type of the metadata query

Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringnon-emptyrequired

Instructions for how to execute the metadata query

Example: "Extract the full name of the primary author from the document header or byline"
curl -i -X POST \
  https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/123e4567-e89b-12d3-a456-426614174001/metadata-queries \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Author Name",
    "description": "The name of the document author",
    "dataType": "STRING",
    "instructions": "Extract the full name of the primary author from the document header or byline"
  }'

Responses

Metadata key created successfully

Bodyapplication/json
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174001"
namestringrequired
Example: "Author Name"
descriptionstring or nullrequired
Example: "The name of the document author"
dataTypestringrequired
Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringrequired
Example: "Extract the full name of the primary author from the document header or byline"
ontologyIdstring(uuid)required
Example: "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b"
createdAtstring(date-time)required
Example: "2024-01-15T10:30:00Z"
updatedAtstring or null(date-time)required
Example: "2024-01-15T14:30:00Z"
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "name": "Author Name",
  "description": "The name of the document author",
  "dataType": "STRING",
  "instructions": "Extract the full name of the primary author from the document header or byline",
  "ontologyId": "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

List all metadata queries in an ontology

Request

Returns all metadata queries with their category bindings including binding properties (required, uniqueIndexElement)

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

Example: 123e4567-e89b-12d3-a456-426614174001
curl -i -X GET \
  https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/123e4567-e89b-12d3-a456-426614174001/metadata-queries \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

List of metadata queries with category bindings

Bodyapplication/jsonArray [
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174001"
namestringrequired
Example: "Author Name"
descriptionstring or nullrequired
Example: "The name of the document author"
dataTypestringrequired
Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringrequired
Example: "Extract the full name of the primary author from the document header or byline"
ontologyIdstring(uuid)required
Example: "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b"
createdAtstring(date-time)required
Example: "2024-01-15T10:30:00Z"
updatedAtstring or null(date-time)required
Example: "2024-01-15T14:30:00Z"
categoryBindingsArray of objectsrequired

List of categories this metadata query is bound to with binding properties

categoryBindings[].​categoryIdstring(uuid)required

The ID of the category this metadata query is bound to

Example: "123e4567-e89b-12d3-a456-426614174002"
categoryBindings[].​categoryNamestringrequired

The name of the category this metadata query is bound to

Example: "Research Papers"
categoryBindings[].​requiredbooleanrequired

Whether this metadata query is required for this category

Example: true
categoryBindings[].​uniqueIndexElementbooleanrequired

Whether this metadata query is part of the unique index for this category

Example: false
]
Response
application/json
[
  {
    "id": "e81bb521-4b01-45ca-a74e-c52c52363181",
    "name": "Permit Number",
    "description": "The official permit number assigned by the city",
    "dataType": "SHORT_STRING",
    "instructions": "Extract the permit number from the document header or official stamp",
    "ontologyId": "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": null,
    "categoryBindings": [ … ]
  },
  {
    "id": "6bbda475-2aa6-4e36-966c-40f161cce13d",
    "name": "Inspector Name",
    "description": "Name of the assigned inspector",
    "dataType": "STRING",
    "instructions": "Please extract the full name of the inspector from this document.",
    "ontologyId": "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b",
    "createdAt": "2025-01-15T10:32:00Z",
    "updatedAt": "2025-01-16T14:20:00Z",
    "categoryBindings": [ … ]
  }
]

Get a metadata query by ID

Request

Returns a single metadata query with its category bindings including binding properties (required, uniqueIndexElement)

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

metadataQueryIdstring(uuid)required

The ID of the metadata query

curl -i -X GET \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Metadata key details with category bindings

Bodyapplication/json
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174001"
namestringrequired
Example: "Author Name"
descriptionstring or nullrequired
Example: "The name of the document author"
dataTypestringrequired
Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringrequired
Example: "Extract the full name of the primary author from the document header or byline"
ontologyIdstring(uuid)required
Example: "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b"
createdAtstring(date-time)required
Example: "2024-01-15T10:30:00Z"
updatedAtstring or null(date-time)required
Example: "2024-01-15T14:30:00Z"
categoryBindingsArray of objectsrequired

List of categories this metadata query is bound to with binding properties

categoryBindings[].​categoryIdstring(uuid)required

The ID of the category this metadata query is bound to

Example: "123e4567-e89b-12d3-a456-426614174002"
categoryBindings[].​categoryNamestringrequired

The name of the category this metadata query is bound to

Example: "Research Papers"
categoryBindings[].​requiredbooleanrequired

Whether this metadata query is required for this category

Example: true
categoryBindings[].​uniqueIndexElementbooleanrequired

Whether this metadata query is part of the unique index for this category

Example: false
Response
application/json
{
  "id": "e81bb521-4b01-45ca-a74e-c52c52363181",
  "name": "Permit Number",
  "description": "The official permit number assigned by the city",
  "dataType": "SHORT_STRING",
  "instructions": "Extract the permit number from the document header or official stamp",
  "ontologyId": "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": null,
  "categoryBindings": [
    { … },
    { … }
  ]
}

Update a metadata query

Request

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

metadataQueryIdstring(uuid)required

The ID of the metadata query

Bodyapplication/json
namestringnon-empty

Name of the metadata query

Example: "Updated Author Name"
descriptionstring

Description of the metadata query

Example: "Updated description of the author field"
dataTypestring

Data type of the metadata query

Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringnon-empty

Instructions for how to execute the metadata query

Example: "Extract the full name of the primary author from the document header or byline"
curl -i -X PUT \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Author Name",
    "description": "Updated description of the author field",
    "dataType": "STRING",
    "instructions": "Extract the full name of the primary author from the document header or byline"
  }'

Responses

Metadata key updated successfully

Bodyapplication/json
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174001"
namestringrequired
Example: "Author Name"
descriptionstring or nullrequired
Example: "The name of the document author"
dataTypestringrequired
Enum"STRING""SHORT_STRING""NUMBER""BOOLEAN""DATE"
Example: "STRING"
instructionsstringrequired
Example: "Extract the full name of the primary author from the document header or byline"
ontologyIdstring(uuid)required
Example: "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b"
createdAtstring(date-time)required
Example: "2024-01-15T10:30:00Z"
updatedAtstring or null(date-time)required
Example: "2024-01-15T14:30:00Z"
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "name": "Author Name",
  "description": "The name of the document author",
  "dataType": "STRING",
  "instructions": "Extract the full name of the primary author from the document header or byline",
  "ontologyId": "987fcdeb-51a2-43d1-9c4e-5f6e7d8c9a0b",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

Delete a metadata query

Request

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

metadataQueryIdstring(uuid)required

The ID of the metadata query

curl -i -X DELETE \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Metadata key deleted successfully

Bind metadata query to a category

Request

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

categoryIdstring(uuid)required

The ID of the category

metadataQueryIdstring(uuid)required

The ID of the metadata query

Bodyapplication/json
uniqueIndexElementboolean

Whether this metadata query is part of the unique index

Example: false
requiredboolean

Whether this metadata query is required

Default false
Example: true
curl -i -X PUT \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/categories/{categoryId}/bindings/{metadataQueryId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "uniqueIndexElement": false,
    "required": true
  }'

Responses

Metadata key bound to category successfully

Bodyapplication/json
idstring(uuid)required
Example: "123e4567-e89b-12d3-a456-426614174001"
namestringrequired
Example: "Research Papers"
descriptionstring or nullrequired
Example: "Academic research papers and publications"
metadataQueryBindingsArray of strings(uuid)required
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "name": "Research Papers",
  "description": "Academic research papers and publications",
  "metadataQueryBindings": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ]
}

Unbind metadata query from a category

Request

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

categoryIdstring(uuid)required

The ID of the category

metadataQueryIdstring(uuid)required

The ID of the metadata query

curl -i -X DELETE \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/categories/{categoryId}/bindings/{metadataQueryId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Metadata key unbound from category successfully

Get metadata query usage count

Request

Returns the number of categories that currently use this metadata query. Features: - Efficient counting using SQL COUNT queries with JOIN - Returns exact count of categories bound to the metadata query - Useful for impact analysis before metadata query changes - Supports ontology change management workflows Use Cases: - Determine impact before deleting a metadata query - Analyze metadata query usage across categories - Support ontology change management decisions - Dashboard statistics for metadata query utilization Example Usage: - GET /accounts/acc-12345678/ontologies/ont-87654321/metadata-queries/123e4567-e89b-12d3-a456-426614174000/usage-count Response: Returns a simple count object indicating how many categories are currently bound to this metadata query. Performance: - Optimized for large ontologies using database indexes - Uses SQL COUNT with JOIN for efficient counting - Returns exact counts without loading category data into memory

Security
bearerAuth
Path
accountIdstring^scd-[a-z0-9]{8}$required

Short account ID with scd- prefix

Example: scd-k2j8n4m1
ontologyIdstring(uuid)required

The ID of the ontology

metadataQueryIdstring(uuid)required

The ID of the metadata query

curl -i -X GET \
  'https://docs.syncdocs.ai/_mock/api/sync-cloud-openapi/accounts/scd-k2j8n4m1/ontologies/{ontologyId}/metadata-queries/{metadataQueryId}/usage-count' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Metadata key usage count retrieved successfully

Bodyapplication/json
countinteger>= 0required

Number of categories that use this metadata query

Example: 3
Response
application/json
{
  "count": 3
}

Users

User management operations. Users can interact with dataspaces and workspaces with assigned roles and permissions.

Operations

Libraries

Library management operations. Libraries are external content sources that can be scraped and indexed for use as citation sources in AI queries.

Operations

Library Bindings

Library binding operations. Bind libraries to workspaces to enable access to library content for AI queries.

Operations

Agents

Agent management operations. Agents are automated entities that can perform operations on behalf of users.

Operations

Workflows

Workflow management operations. Workflows define automated processes for content handling and business logic.

Operations

Task Definitions

Task definition management operations

Operations

Helpers

Helper utility operations

Operations