# Tenovos Content Intelligence Platform

Secure, scalable REST APIs for the Tenovos Content Intelligence Platform — enabling content discovery, metadata management, AI enrichment, governance, and distribution across enterprise systems.

Version: 3.0

## Servers

Default Server
```
https://api.tenovos.net
```

## Security

### bearerAuth

API Key authentication using Bearer token

Type: http
Scheme: bearer
Bearer Format: JWT

## Download OpenAPI description

[Tenovos Content Intelligence Platform](https://api.tenovos.com/_bundle/openapi/content-intelligence.yaml)

## Document Management

Documents are the primary data model in the Content Intelligence Platform. Each document is
a JSON object that holds metadata as flexible name/value pairs — there is no fixed schema
enforced at the storage layer, which allows content from diverse external systems (DAMs,
cloud storage, SharePoint, Box, etc.) to be ingested without transformation.

Documents exist within a graph-like structure where **nodes** (individual documents) and
**edges** (links between documents) form a highly relational content model. For example,
a `media` document can be linked to a `campaign` document, enabling hierarchical queries
and relationship traversal across the content graph.

**Document traits** define behavioral capabilities of a document type:

| Trait | Description |
|---|---|
| `SUMMARY` | Document has a displayable summary representation |
| `CHILDREN` | Document can contain child documents |
| `TILE` | Document can be displayed as a tile/card |
| `CONTENT` | Document is linked to binary content (files) |
| `PREVIEW` | Document can generate a visual preview |
| `INSIGHTS` | Document tracks engagement analytics |
| `TIMELINE` | Document has a temporal lifecycle (start/end dates) |
| `VERSION` | Document supports versioning |
| `SOURCE` | Document tracks its originating content channel |

**Endpoint reference:**

- `create` — create one or more documents of a given kind, with optional external ID for deduplication
- `retrieve` — fetch a document by ID with full metadata and linked content references
- `list` — paginated listing of documents, filtered by kind, status, or metadata values
- `query` — full-text and field-level search across the document graph
- `query-within` — scoped search within a specific document hierarchy (e.g., within a brand or campaign)
- `link / unlink` — create or remove typed edges between documents (e.g., link media to a campaign)
- `retrieve-links` — traverse outbound edges from a document to its related documents
- `update` — modify document metadata fields; uses partial update (only supplied fields change)
- `delete / undelete` — soft-delete with restore; deleted documents remain queryable with a filter
- `purge` — permanently remove a document and all its edges
- `reindex` — trigger re-indexing of a document into OpenSearch; use after bulk imports or schema changes

Documents reference binary content managed by the [Content Storage](#tag/Content-Storage) service
and are typed using [Document Types](#tag/Document-Types) with optional schema enforcement
via [Document Schemas](#tag/Document-Schemas).


### Create documents

 - [POST /api/v1/document/create](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.create.md): Creates one or more documents of a given kind, returning the IDs of newly created documents and any pre-existing duplicates.

Request:
documents     - List of documents to create. Each entry includes:
kind        - The Kind name this document belongs to.
doc         - The document body as an arbitrary JSON value.
externalId - Optional identifier from an external system for deduplication and cross-reference.

Response:
ids            - IDs of the newly created documents.
existingIds   - IDs of pre-existing documents that matched by externalId (not re-created).

### Get documents

 - [POST /api/v1/document/retrieve](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.retrieve.md): Retrieves one or more documents by internal ID or external ID, with optional field projection and soft-delete inclusion.

Request:
ids               - List of internal document IDs to retrieve.
externalIds      - List of external IDs to retrieve documents by.
fetches           - Optional field projection expression limiting which document fields are returned.
includeDeleted   - When true, includes soft-deleted documents in the results.

Response:
documents   - List of Document objects (id, kind, doc body, timestamps).

### List documents

 - [POST /api/v1/document/list](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.list.md): Lists documents filtered by one or more kind names, with optional field projection and cursor-based pagination.

Request:
kinds             - List of Kind names to filter by.
fetches           - Optional field projection expression limiting which document fields are returned.
includeDeleted   - When true, includes soft-deleted documents in the results.
pagination        - Optional Pagination cursor and page size.

Response:
documents     - List of Document objects matching the filter.
pageCursor   - Opaque cursor for the next page. Absent when there are no further results.

### Link documents

 - [POST /api/v1/document/link](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.link.md): Creates directional links from a source document to one or more destination documents at a specified property path.

Request:
sourceId         - ID of the document to link from.
destIds          - List of destination document IDs to link to.
propertyPath     - The field path on the source document that represents this relationship.
destProperties   - Optional per-destination properties. Each entry specifies destId and an
optional weight used for ordering or scoring the relationship.

Response:
destIds   - IDs of the destination documents that were successfully linked.

### Unlink documents

 - [POST /api/v1/document/unlink](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.unlink.md): Removes links from a source document to one or more destination documents at a specified property path.

Request:
sourceId       - ID of the document to remove links from.
destIds        - List of destination document IDs to unlink.
propertyPath   - The field path on the source document where the links reside.

Response:
destIds   - IDs of the destination documents that were successfully unlinked.

### Get document links

 - [POST /api/v1/document/retrieve-links](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.retrievelinks.md): Retrieves all outbound links for one or more source documents, returning destination IDs and property paths.

Request:
sourceIds   - List of source document IDs whose links to retrieve.

Response:
docLinks   - List of Links objects, one per source document. Each contains the sourceId
and a list of Link entries (destId and propertyPath) representing all
outbound relationships.

### Query documents

 - [POST /api/v1/document/query](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.query.md): Executes a structured query against all documents in the organization, returning matching results with full control over which fields and traits are returned, how results are filtered, and how pages are navigated.

---

## Query Language

Queries are expressed as a single string using a structured query language with up to four clauses:


fetch().orderBy(, asc|desc))]
from([, ...])
[match('')]
[filter()]


Only fetch and from are required. match and filter are optional and may appear in any order after from.

---

## fetch() — Field and Trait Selection

Specifies which fields or traits to return. Multiple items are comma-separated.

| Syntax | Description |
|---|---|
| fetch(/) | Return the entire root document |
| fetch(/field) | Return a single top-level field |
| fetch(/field/subfield) | Return a nested field |
| fetch($trait) | Return a trait result at the root |
| fetch(/path/$trait) | Return a trait scoped to a field path |
| fetch($trait$subtrait) | Return a trait with a sub-trait qualifier |
| fetch($trait(key=value)) | Return a trait with attribute parameters |
| fetch(/f1, $summary, /path/$preview) | Return multiple items |

Ordering — append .orderBy(, asc|desc) to fetch():

fetch(/).orderBy(/name, asc)
fetch($summary).orderBy(/createdAt, desc)


Pagination — append .limit() or .limit(, ) to fetch():

fetch(/).limit(25)
fetch(/).limit(25, nextPageToken)

The cursor value is the opaque pageCursor string returned in the previous response.

---

## from() — Document Kind Selection

Specifies one or more document kinds to query. Kind names must be lowercase letters and underscores only (3–62 characters).


from(brand)
from(asset, brand, region)


Default platform kinds: media, brand, campaign, category, toolkit, section, block. Custom kinds defined in your organization are also supported.

---

## match() — Full-Text Search

Performs a full-text keyword search across indexed document content. Keywords are provided as a single-quoted string. Results are ranked by relevance when orderBy is not specified.


match('acme global')
match('Q4 campaign hero')


---

## filter() — Field-Level Conditions

Applies field-level conditions to narrow results. Expressions can be simple or compound.

Comparison operators:

| Operator | Meaning |
|---|---|
| == | Equals |
| != | Not equals |
| ` | Greater than |
| >= | Greater than or equal |
| ... | Contains (substring match or array membership) |
| !.. | Does not contain |

Logical operators: && (AND), || (OR), (...) (grouping)

Literal value types:

| Type | Syntax | Examples |
|---|---|---|
| Null | null | null |
| Boolean | true / false | true |
| Number | integer or decimal | 42, 3.14, -10 |
| String | single-quoted | 'active', 'Acme Corp' |


filter(/status == 'active')
filter(/rating >= 4 && /region != null)
filter((/status == 'active' || /status == 'pending') && /owner != null)
filter(/tags ... 'featured')
filter(/$$id == 'assetAbc123')


Strings in filter conditions must be single-quoted. Supported escape sequences: \\, \', \n, \r, \t.

---

## Property Paths

Property paths reference fields within a document and always begin with /. Nested fields are separated by /.

| Path | Description |
|---|---|
| / | The root document |
| /name | Top-level field |
| /metadata/createdBy | Nested field |
| /tags | Array field |
| /$$id | Reserved system field (prefixed with $$) |

Range selectors on link properties — link fields (relationships to other documents) support a range selector [start..end] to limit which linked items are returned. Both bounds are zero-based; start is inclusive, end is exclusive.

| Syntax | Description |
|---|---|
| /items[0..5] | First 5 linked items |
| /items[3..] | All linked items from index 3 onward |
| /items[..10] | First 10 linked items |
| /items[2..8] | Items at indices 2 through 7 |

Ranges can appear at multiple levels of a path:

fetch(/sections[0..3]/media[..10]) from(toolkit)


---

## Traits

Traits define a standard contract for a set of fields a document kind can return. They are referenced in fetch() using the $ prefix.

| Trait | Parameters | Returned Fields |
|---|---|---|
| $summary | — | name, description |
| $tile | — | fgColor, bgColor, iconUrl |
| $children | limit (optional) | items (array), depth |
| $content | — | id, mimeType, contentType, size, filename, description, caption; plus type-specific: image (width, height), video (width, height, durationMs), document (width, height, pages) |
| $preview | w, h, representationType | id, url |
| $insights | — | Array of insight metrics (single value or timeseries) |
| $timeline | — | from, to (timestamps) |
| $version | — | number, isLatest |

Sub-traits apply a secondary trait to each item returned by the parent:

fetch($children$summary)           # fetch children, return $summary for each
fetch($children$summary(limit=5))  # limit to 5 children


---

## Complete Examples


# Fetch all fields from a single kind
fetch(/) from(brand)

# Fetch specific fields
fetch(/name, /status, /region) from(asset)

# Fetch a trait
fetch($summary) from(brand)

# Fetch multiple traits and fields
fetch($summary, $tile, /metadata) from(brand)

# Fetch a trait at a nested path
fetch(/heroImage/$preview(w=800, h=600)) from(campaign)

# Full-text search
fetch($summary) from(asset) match('product launch 2024')

# Filter by a field value
fetch(/) from(asset) filter(/status == 'approved')

# Filter with AND
fetch($summary) from(asset) filter(/status == 'active' && /owner != null)

# Filter with OR and grouping
fetch($summary) from(asset)
filter((/status == 'active' || /status == 'pending') && /region != null)

# Contains / not-contains
fetch(/) from(asset) filter(/tags ... 'featured')
fetch(/) from(brand) filter(/name !.. 'draft')

# Query multiple kinds
fetch($summary) from(brand, region, asset) filter(/status == 'active')

# Order and paginate
fetch($summary).orderBy(/name, asc).limit(20) from(brand)

# Continue from a cursor
fetch($summary).orderBy(/name, asc).limit(20, nextPageCursorToken) from(brand)

# Fetch linked items with a range
fetch(/items[0..5]) from(category)

# Nested ranges
fetch(/sections[0..3]/media[..10]) from(toolkit)

# Limit children with trait attribute
fetch($children(limit=5)) from(category)

# Combined: search, filter, order, paginate
fetch($summary, $preview(w=400, h=300)).orderBy(/name, asc).limit(10, abc123)
from(asset)
match('campaign hero')
filter(/status == 'active' && /region != null)


---

## Request Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | The query expression string |
| verbose | boolean | No | When true, includes per-phase execution timing in the response (info field) |

## Response

| Field | Description |
|---|---|
| documents | List of matching document objects |
| pageCursor | Opaque token to pass to the next request to retrieve the next page; absent when no further pages exist |
| info | Query timing breakdown by phase (match, filter, projection) — only present when verbose: true` |

### Search within a document

 - [POST /api/v1/document/query-within](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.querywithin.md): Performs a keyword search within the content of a specific document, returning a relevance-scored series of matching positions. This is distinct from the query endpoint, which searches across documents — query-within searches inside a single document's indexed content.

This is most useful for long-form content where you want to locate specific passages, pages, or moments, for example:

- Finding the page in a PDF where a keyword appears
- Locating the timestamp in a video where a term is spoken
- Searching within a large document's indexed text body

## Request Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | The ID of the document to search within |
| keywords | string | Yes | The keyword or phrase to search for within the document's content |
| minScore | number | No | Minimum relevance score threshold (0.0–1.0). Points scoring below this value are excluded from the response. Use to filter out low-confidence matches. |

## Response

| Field | Description |
|---|---|
| series | A scored series of matching positions within the document |

Each point in the series contains:

| Field | Type | Description |
|---|---|---|
| score | number | Relevance score for this match (higher is more relevant) |
| ref | integer or string | Position reference — an integer page index for paginated content (PDFs, slide decks), or a timecode string for time-based content (video, audio) |

## Example

To find all moments in a video where "product launch" is mentioned, with a minimum relevance score of 0.5:

json
{
  "id": "doc01abc123",
  "keywords": "product launch",
  "minScore": 0.5
}


The response series would contain entries like:
json
{
  "series": [
    { "score": 0.92, "ref": "00:01:34" },
    { "score": 0.71, "ref": "00:08:12" }
  ]
}


For a PDF, ref values would be zero-based page indices (0, 4, 11, etc.).

### Update documents

 - [POST /api/v1/document/update](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.update.md): Applies an ordered sequence of field-level patch operations to one or more existing documents. Patches are applied in the order supplied; if any patch in the sequence is invalid, the entire update for that document is rejected.

Request:
updates   - List of documents to update. Each entry includes:
id          - The document ID to target. Either id or externalId must be supplied.
externalId - The external system ID to target (alternative to id, useful when the document was created with an externalId for cross-system referencing).
patches     - Ordered list of patch operations. Field paths use forward-slash notation matching the document's field structure (e.g. /name or /metadata/status). Each patch is one of:
Add(path, value)     — sets a field that does not yet exist.
Remove(path)         — removes the field at the given path.
Replace(path, value) — overwrites an existing field's value.

Response:
ids   - IDs of the documents that were successfully updated.

### Delete documents

 - [POST /api/v1/document/delete](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.delete.md): Soft-deletes one or more documents; deleted documents remain retrievable when includeDeleted is set.

Request:
ids            - List of internal document IDs to soft-delete.
externalIds   - List of external IDs to soft-delete by (alternative to ids).

Response:
ids   - IDs of the documents that were successfully deleted.

### Restore deleted documents

 - [POST /api/v1/document/undelete](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.undelete.md): Restores one or more soft-deleted documents, making them active again.

Request:
ids            - List of internal document IDs to restore.
externalIds   - List of external IDs to restore by (alternative to ids).

Response:
ids   - IDs of the documents that were successfully restored.

### Permanently remove documents

 - [POST /api/v1/document/purge](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.purge.md): Permanently and irreversibly removes one or more documents, bypassing soft-delete.

Request:
ids            - List of internal document IDs to permanently delete.
externalIds   - List of external IDs to permanently delete by (alternative to ids).

Response:
ids   - IDs of the documents that were successfully purged.

### Reindex documents

 - [POST /api/v1/document/reindex](https://api.tenovos.com/openapi/content-intelligence/document-management/tenovos.document.documentservice.reindex.md): Triggers reindexing of all documents matching a given query expression, returning a cursor for paginated progress.

Request:
query   - Query expression identifying the documents to reindex.

Response:
pageCursor   - Cursor to pass in a subsequent request to continue reindexing the next page.
Absent when reindexing is complete.

## Document Types

Document Types (internally called **kinds**) define the categories of content that exist
in your organization — controlling how documents are classified, displayed, and processed
by downstream services. Every document must declare a kind at creation time.

Kinds have a **KindType** classification that describes their primary role:

| KindType | Description |
|---|---|
| `ASSET` | Represents a binary file or media asset (images, video, documents) |
| `REFERENCE` | Represents a business entity that other documents relate to (brands, campaigns) |
| `COLLECTION` | Groups related documents together (categories, playlists) |
| `LAYOUT` | Structures content for presentation (toolkits, sections, blocks) |
| `OTHER` | Custom or unclassified kind |

**Platform-provided default kinds:**

| Kind | KindType | Description |
|---|---|---|
| `media` | `ASSET` | Represents assets that originate from external channels (images, video, files). Linked to binary content, brands, campaigns, and source channel. |
| `brand` | `REFERENCE` | Organizational brand entity. Links to a logo and splash image. Fields: `name`, `description`, `fgColor`, `bgColor`. |
| `campaign` | `REFERENCE` | Marketing campaign. Links to brands and splash images. Fields: `title`, `description`, `brief`, `start`, `end`. |
| `category` | `COLLECTION` | Dynamically generated content groupings. Supports subcategory hierarchies. Fields: `name`, `label`, `description`, `versionNumber`, `depth`, `isLatest`, `keywords`. |
| `toolkit` | `LAYOUT` | Groups sections of content representing a brand identity. Links to sections and a parent brand. |
| `section` | `LAYOUT` | Page layout element holding multiple blocks. Links to a toolkit, parent section, and child blocks. |
| `block` | `LAYOUT` | Page element holding rich text and media. Links to media items. |

Kinds are organized into **groups** for display in the platform UI (e.g., "Media Assets",
"Creative Briefs"). Use `list-default-groups` to retrieve platform-defined groupings.
Custom kinds can be created to extend this model for organization-specific content structures.

Kinds work in conjunction with [Document Schemas](#tag/Document-Schemas), which define
the metadata field structure and validation rules applied to documents of a given kind.


### Get document types

 - [POST /api/v1/kind/retrieve-kind](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.retrievekind.md): Retrieves full Kind definitions for one or more kind names, including trait definitions and schema ID.

Request:
kinds   - List of Kind names to retrieve.

Response:
kinds   - List of Kind objects each containing kind name, KindType, trait definitions,
schemaId, optional description, and timestamps.

### Search document types

 - [POST /api/v1/kind/list-kind](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.listkind.md): Lists all Kind definitions as lightweight summaries with optional cursor-based pagination.

Request:
pagination   - Optional Pagination cursor and page size.

Response:
kinds         - List of KindSummary objects (kind name, type, schemaId, description, timestamps).
pageCursor   - Opaque cursor for the next page. Absent when there are no further results.

### Create a document type

 - [POST /api/v1/kind/create-kind](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.createkind.md): Creates one or more document type definitions. Each kind establishes a category of content in your organization and declares which capabilities (traits) documents of that type support.

Request:
kinds      - List of kind definitions to create. Each includes:
kind        - Unique kind name (lowercase letters and underscores, 3–62 characters).
type        - Classifies the kind's role: ASSET (binary files and media), REFERENCE (business entities such as brands or campaigns), COLLECTION (groupings of related documents), LAYOUT (presentation structures such as pages or sections), or OTHER.
traits      - Capabilities this kind supports. Available traits: SUMMARY (name and description), TILE (visual card display), CONTENT (linked binary file), PREVIEW (renderable thumbnail), CHILDREN (parent-child document hierarchy), INSIGHTS (engagement analytics), TIMELINE (start and end dates), VERSION (revision tracking), and SOURCE (originating content channel).
description - Optional human-readable description of the kind.
schema      - Optional inline metadata schema to attach at creation.
groupId   - Optional ID to associate the new kinds with a platform-defined template group.

Response:
kinds   - Summary of each created kind, including its assigned ID and configuration.

### Update a document type

 - [POST /api/v1/kind/update-kind](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.updatekind.md): Updates the trait definitions and/or description for one or more existing Kinds.

Request:
kinds      - List of update payloads. Each includes:
kind     - Name of the Kind to update.
traits   - Replacement list of TraitDefinition objects.
description - Optional new description.

Response:
kinds   - List of kind names that were successfully updated.

### Delete a document type

 - [POST /api/v1/kind/delete-kind](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.deletekind.md): Permanently deletes one or more Kind definitions by kind name.

Request:
kinds   - List of Kind names to delete.

Response:
kinds   - List of kind names that were successfully deleted.

### Get default groups for types

 - [POST /api/v1/kind/list-default-groups](https://api.tenovos.com/openapi/content-intelligence/document-types/tenovos.document.kindservice.listdefaultgroups.md): Returns the set of system-defined default Kind groups, each with their associated Kind summaries.

Request:
(no parameters)

Response:
groups   - List of Group objects, each containing a groupId and a list of KindSummary
objects belonging to that group. Used to seed default kinds when onboarding
a new organization.

## Document Schemas

Schemas define the metadata field structure for a Document Type — specifying which fields
should be present, their data types, display labels, and validation rules (required, allowed
values, min/max constraints). The platform stores metadata as schemaless name/value pairs
at the document layer, but schemas allow you to enforce structure when needed.

**Schema types:**

| SchemaType | Description |
|---|---|
| `ROOT` | Top-level schema attached directly to a Document Kind |
| `SUB` | Nested schema for structured sub-objects within a document |
| `TRAIT` | Schema associated with a behavioral trait (e.g., SUMMARY, TIMELINE) |

**Available field types:**

| Field Type | Description |
|---|---|
| `string` | Plain text value |
| `integer` | Whole number |
| `number` | Floating point number |
| `bool` | Boolean true/false |
| `date` | ISO 8601 date or datetime |
| `array` | List of values — element type can be `string`, `integer`, `number`, `bool`, or `date` |
| `object` | Nested JSON object (references a `SUB` schema) |
| `link` | Edge to another document; has a `cardinality` (`ONE_TO_ONE`, `ONE_TO_MANY`, `MANY_TO_ONE`, `MANY_TO_MANY`) |
| `ref` | Read-only reference to a field on a linked document |
| `computed` | Derived field calculated from other field values |

**Schema operations:**
- `create-schema` — define a new schema and attach it to a kind
- `update-schema` — revise field definitions; changes apply to subsequent document writes
- `retrieve-schema / list-schema` — inspect field definitions for a given kind
- `delete-schema` — remove a schema, returning the kind to free-form metadata mode


### Get a metadata schema

 - [POST /api/v1/schema/retrieve-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.retrieveschema.md): Retrieves full document schema definitions by their IDs.

Request:
ids       - List of schema IDs to retrieve.

Response:
schemas   - List of DocumentSchema objects with the full field definitions.

### Search document schemas

 - [POST /api/v1/schema/list-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.listschema.md): Lists all document schemas as lightweight summaries with optional cursor-based pagination.

Request:
pagination   - Optional Pagination cursor and page size.

Response:
schemas       - List of DocumentSchemaSummary objects.
pageCursor   - Opaque cursor for the next page. Absent when there are no further results.

### Create a metadata schema

 - [POST /api/v1/schema/create-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.createschema.md): Creates one or more new document schemas.

Request:
schemas   - List of CreateDocumentSchema definitions to create.

Response:
schemas   - List of DocumentSchemaSummary objects for the created schemas.

### Update a metadata schema

 - [POST /api/v1/schema/update-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.updateschema.md): Updates one or more existing document schemas by their IDs.

Request:
schemas   - List of UpdateDocumentSchema payloads, each identifying a schema by ID and
providing the replacement field definitions.

Response:
ids   - List of schema IDs that were successfully updated.

### Delete a metadata schema

 - [POST /api/v1/schema/delete-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.deleteschema.md): Permanently deletes one or more document schemas by their IDs.

Request:
ids   - List of schema IDs to permanently delete.

Response:
ids   - List of schema IDs that were successfully deleted.

## Document Rules

Document Rules are automated policies that govern how documents behave as they are created
or updated in the platform. Each rule defines **conditions** (when to fire) and
**actions** (what to do). Rules are evaluated asynchronously by the Action & Media Flows
service whenever a matching document event occurs.

**Condition matching:**

Rules evaluate conditions against document fields. The `matchType` controls how multiple
conditions combine:

| Match Type | Behavior |
|---|---|
| `MATCH_ALL` | All conditions must be true (AND logic) |
| `MATCH_ANY` | At least one condition must be true (OR logic) |
| `MATCH_NONE` | No conditions may be true (NOT logic) |

**Condition operators:**

| Operator | Description |
|---|---|
| `OP_EQ` | Field equals the specified value |
| `OP_NE` | Field does not equal the specified value |
| `OP_MATCHES` | Field matches a regular expression |
| `OP_NOT_MATCHES` | Field does not match a regular expression |
| `OP_IS_EMPTY` | Field is absent or null |
| `OP_IS_NOT_EMPTY` | Field is present and non-null |

**Condition sources** — what the condition evaluates against:

| Source | Description |
|---|---|
| `SOURCE_KIND` | The document kind (type) |
| `SOURCE_DOC_VALUE` | The current value of a document field |
| `SOURCE_PREV_DOC_VALUE` | The previous value of a field (before the triggering update) |

**Available actions:**

| Action | Description |
|---|---|
| `setProperty` | Write a metadata field value on the document |
| `setLink` | Create a link edge between the document and another document |
| `setPolicy` | Apply an access policy grant (`READ` or `MODIFY`) to the document |

**Rule lifecycle:**
- `create / update` — define or revise rule conditions and actions
- `enable / disable` — activate or pause a rule without deleting it
- `test` — evaluate a rule against a sample document payload before enabling in production
- `delete` — permanently remove a rule


### Search content rules

 - [POST /api/v1/rule/list-rules](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.listrules.md): Lists all rules as lightweight summaries including name, enabled state, and priority.

Request:
(no parameters)

Response:
rules   - List of RuleSummary objects for all rules in the organization.

### Get a content rule

 - [POST /api/v1/rule/retrieve-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.retrieverule.md): Retrieves a full rule definition by ID, including its conditions, actions, and priority.

Request:
id   - ID of the rule to retrieve.

Response:
rule   - The full Rule object including id, name, enabled state, conditions,
actions, priority, timestamps, and any validation error.

### Create a content rule

 - [POST /api/v1/rule/create-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.createrule.md): Creates a new rule defining conditions and actions to apply when documents change.

Request:
rule   - A CreateRule definition specifying name, conditions (DocumentRule.Conditions),
actions (DocumentRule.Actions), and priority.

Response:
rule   - The full Rule object that was created.

### Update a content rule

 - [POST /api/v1/rule/update-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.updaterule.md): Updates an existing rule's conditions, actions, or priority.

Request:
rule   - An UpdateRule payload identifying the rule by ID and providing the
replacement conditions, actions, and/or priority.

Response:
rule   - The full Rule object reflecting the applied updates.

### Delete a content rule

 - [POST /api/v1/rule/delete-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.deleterule.md): Permanently deletes a rule by ID.

Request:
id   - ID of the rule to permanently delete.

Response:
(empty)

### Enable a content rule

 - [POST /api/v1/rule/enable-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.enablerule.md): Activates a disabled rule so it is evaluated against document changes.

Request:
id   - ID of the rule to enable.

Response:
rule   - The updated Rule object with enabled set to true.

### Disable a content rule

 - [POST /api/v1/rule/disable-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.disablerule.md): Deactivates an active rule, preventing it from being evaluated, without deleting it.

Request:
id   - ID of the rule to disable.

Response:
rule   - The updated Rule object with enabled set to false.

### Test a content rule

 - [POST /api/v1/rule/test-rule](https://api.tenovos.com/openapi/content-intelligence/document-rules/tenovos.document.ruleservice.testrule.md): Tests a rule against a sample document to verify whether its conditions match and previews the resulting actions.

Request:
ruleId             - ID of the rule to test.
documentKind       - Kind name of the sample document being tested against.
sampleDocument     - Optional current state of the document as a JSON value.
previousDocument   - Optional previous state of the document for change-detection conditions.

Response:
matched   - Whether the rule's conditions matched the sample document.
actions   - List of ActionType values that would be triggered if the rule matched.
error     - Optional error message if the rule could not be evaluated.

## Content Storage

The Content Storage service manages references to binary content (files) through a
pluggable **adapter** model. Adapters represent different physical storage backends —
for example, AWS S3 (full read/write), CDN origins (Bunny, Bria), or external DAM
connectors. Callers never interact with storage directly; they work with **pre-signed
URLs** that the service generates on demand, allowing content to be streamed directly
from the storage provider without proxying through the platform.

The service supports **multiple adapters per organization with a priority ordering**,
so that suitable storage defaults are chosen automatically without callers needing to
specify where content lives. Different adapters can be configured for different storage
classes (hot, warm, cold), affecting retrieval latency and cost.

**Content lifecycle:**

| Endpoint | Description |
|---|---|
| `register` | Record that a piece of content exists at a known storage location (used during channel sync) |
| `retrieve-upload-url` | Get a pre-signed URL to upload a new file directly to the configured storage adapter |
| `stage` | Prepare content for CDN delivery by writing it to the CDN origin adapter |
| `retrieve-url` | Get a pre-signed download or streaming URL for a content item |
| `retrieve-info` | Fetch content metadata: size, MIME type, checksums, dimensions (for images) |
| `list-info` | Batch retrieval of content metadata for multiple items |
| `update` | Update mutable content metadata (alt text, tags, etc.) |
| `delete / undelete` | Soft-delete a content record with restore capability |
| `purge` | Permanently remove the content record (does not delete the underlying file from storage) |
| `deregister` | Remove the content reference without affecting the underlying stored file |

**Adapter management:**

| Endpoint | Description |
|---|---|
| `create-adapter` | Configure a new storage backend for the organization |
| `update-adapter` | Modify adapter settings (credentials, priority, storage class) |
| `retrieve-adapter / list-adapters` | Inspect configured adapters |
| `delete-adapter / undelete-adapter / purge-adapter` | Manage adapter lifecycle |


### Register content

 - [POST /api/v1/content/register](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.register.md): Registers one or more binary assets into the content service, creating tracking records linked to their storage location.

Request:
items                  - List of content items to register. Each item includes:
contentUri          - URI of the binary file in the storage adapter.
contentId           - Optional existing content ID to associate this representation with.
Auto-generated if omitted.
contentProperties   - Optional media properties (dimensions, mimeType, size, filename, caption).
externalId          - Optional identifier from an external system for cross-reference.
representationType  - Optional label distinguishing this rendition (e.g. "original", "preview").
extendedProperties  - Optional descriptive and technical metadata.

Response:
items   - List of registered items, each containing contentId, adapterId,
representationType, and externalId.

### Deregister content

 - [POST /api/v1/content/deregister](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.deregister.md): Permanently removes content registrations, deleting both the metadata record and the binary file from storage.

Request:
items                  - List of items to deregister. Each item includes:
contentId           - ID of the content to remove.
adapterId           - Optional adapter to target; removes across all adapters if omitted.
representationType  - Optional representation to target; removes all representations if omitted.

Response:
items   - List of deregistered items confirming contentId, adapterId, and representationType.

### Delete content

 - [POST /api/v1/content/delete](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.delete.md): Soft-deletes content representations, marking them as deleted while retaining data for potential recovery.

Request:
items                  - List of items to soft-delete. Each item includes:
contentId           - ID of the content to delete.
storageClass        - Optional storage class to target.
adapterId           - Optional adapter to target.
representationType  - Optional representation to target.

Response:
items   - List of deleted items confirming contentId, adapterId, and representationType.

### Restore deleted content

 - [POST /api/v1/content/undelete](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.undelete.md): Recovers soft-deleted content representations, restoring them to an active state.

Request:
items                  - List of items to restore. Each item includes:
contentId           - ID of the content to recover.
storageClass        - Optional storage class to target.
adapterId           - Optional adapter to target.
representationType  - Optional representation to target.

Response:
items   - List of restored items confirming contentId, adapterId, and representationType.

### Permanently remove content

 - [POST /api/v1/content/purge](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.purge.md): Permanently deletes content binary files from storage and removes their representation records.

Request:
items                  - List of items to purge. Each item includes:
contentId           - ID of the content to purge.
storageClass        - Optional storage class to target.
adapterId           - Optional adapter to target.
representationType  - Optional representation to target.
adapterType         - Optional adapter type to target.

Response:
items   - List of purged items confirming contentId, adapterId, and representationType.

### Get content download URL

 - [POST /api/v1/content/retrieve-url](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.retrieveurl.md): Generates presigned time-limited download URLs for one or more content items.

Request:
contentIds            - List of content IDs to generate URLs for.
representationType    - Optional rendition to retrieve (e.g. "original", "preview").
storageClass          - Optional storage class to target.
adapterId             - Optional specific adapter to source from.
adapterType           - Optional adapter type to source from.
retrieveProperties    - Optional width/height/aspectRatio hints for image resizing at the CDN.
useShortLinks        - When true, generates shortened URLs.
useDynamicLinks      - When true, generates CDN dynamic links.

Response:
items   - List of results, each containing the content ID, a presigned URL for direct download or streaming, and file properties including MIME type, dimensions, size, and filename.

### Get content info

 - [POST /api/v1/content/retrieve-info](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.retrieveinfo.md): Retrieves metadata for one or more content items without generating download URLs.

Request:
contentIds            - List of content IDs to look up.
representationType    - Optional rendition to retrieve.
storageClass          - Optional storage class to target.
adapterId             - Optional adapter to target.
adapterType           - Optional adapter type to target.
externalIds           - Optional external IDs to look up content by.
contentUris           - Optional raw URIs to look up content by.
requestProperties     - Flags controlling which optional fields to include
(description, extendedDescription, technical).

Response:
items   - List of results, one per requested content item. Each entry includes the content ID, storage URI, file properties (size, MIME type, dimensions, duration), optional external ID if one was supplied at registration, and a pending flag that is true if the file upload has not yet completed.

### Search content info

 - [POST /api/v1/content/list-info](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.listinfo.md): Lists all content representations stored within a specific adapter instance, with pagination.

Request:
adapterInstanceId   - ID of the adapter whose content to list.
pagination            - Optional Pagination cursor and page size.

Response:
items         - List of content items, each including the content ID, storage URI, file properties (MIME type, dimensions, size), optional external ID, optional extended descriptive metadata, and a pending flag that is true if the file upload has not yet completed.
pageCursor   - Opaque cursor for the next page. Absent when there are no further results.

### Get content upload URL

 - [POST /api/v1/content/retrieve-upload-url](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.retrieveuploadurl.md): Generates presigned upload URLs for new or replacement content, creating pending content records.

Request:
items                  - List of upload requests. Each item includes:
contentId           - Optional existing content ID to replace; auto-generated if omitted.
contentProperties   - Optional media properties for the file being uploaded.
externalId          - Optional external system identifier.
extendedProperties  - Optional descriptive metadata.
representationType    - Optional rendition label for the uploaded file.
storageClass          - Optional storage class for the upload destination.
adapterId             - Optional specific adapter to upload to.
adapterType           - Optional adapter type to upload to.

Response:
items   - List of results each containing contentId, optional externalId, and
the presigned upload URL. The client must PUT the file to this URL to
complete the upload; content remains in a pending state until then.

### Stage content for upload

 - [POST /api/v1/content/stage](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.stage.md): Copies content from one storage location to another, enabling distribution across adapters (e.g. primary to CDN cache).

Request:
contentIds              - List of content IDs to stage.
representationType      - Optional source rendition to copy from.
toDestination           - Destination specified as one of: storageClass, adapterId, or adapterType.
stageProperties         - Optional per-item configuration including contentId mapping and alias.
toRepresentationType   - Optional representationType to assign to the copy at the destination.

Response:
items   - List of staged results each containing contentId, the destination
representationType, and the destination adapterId.

### Create a storage adapter

 - [POST /api/v1/content/create-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.createadapter.md): Creates a new storage adapter instance, registering a storage backend for use by the content service.

Request:
name                - Display name for the adapter.
adapterType        - Backend type: AWS_S3, CHANNEL_MANAGER, CDN, or AWS_EFS.
storageClass       - Purpose classification: PRIMARY, CACHE, PREVIEW, TEMP, or ANALYZER.
retrievalPriority  - Priority order when selecting adapters for download (lower = higher priority).
uploadPriority     - Priority order when selecting adapters for upload (lower = higher priority).
config              - Type-specific configuration (bucket name, region, CDN pull zone, etc.).

Response:
The created adapter instance, including its assigned ID, display name, backend type, storage class, retrieval and upload priority values, type-specific configuration, and creation timestamp.

### Update a storage adapter

 - [POST /api/v1/content/update-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.updateadapter.md): Updates the configuration, priorities, or storage class of an existing adapter instance.

Request:
id                  - ID of the adapter to update.
name                - Optional new display name.
storageClass       - Optional new storage class.
retrievalPriority  - Optional new retrieval priority.
uploadPriority     - Optional new upload priority.
config              - Optional new type-specific configuration.

Response:
The updated adapter instance with all applied changes, including the current name, storage class, priority settings, and configuration.

### Get a storage adapter

 - [POST /api/v1/content/retrieve-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.retrieveadapter.md): Retrieves full details of a single adapter instance by its ID.

Request:
adapterId   - ID of the adapter to retrieve.

Response:
The adapter instance including its ID, backend type, storage class, retrieval and upload priority values, type-specific configuration, and timestamps.

### Search storage adapters

 - [POST /api/v1/content/list-adapters](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.listadapters.md): Lists adapter instances with optional filtering for deleted or default system adapters.

Request:
includeDeleted   - When true, includes soft-deleted adapters in the results.
includeDefault   - When true, includes system-managed default adapters.

Response:
items   - List of lightweight Adapter summaries: adapterId, name, adapterType, storageClass.

### Delete a storage adapter

 - [POST /api/v1/content/delete-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.deleteadapter.md): Soft-deletes an adapter instance, making it unavailable for new operations while retaining its records.

Request:
adapterId   - ID of the adapter to soft-delete.

Response:
adapterId   - ID of the adapter that was deleted.

### Restore a storage adapter

 - [POST /api/v1/content/undelete-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.undeleteadapter.md): Recovers a soft-deleted adapter instance, restoring it to active status.

Request:
adapterId   - ID of the adapter to restore.

Response:
adapterId   - ID of the adapter that was restored.

### Permanently remove an adapter

 - [POST /api/v1/content/purge-adapter](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.purgeadapter.md): Permanently deletes an adapter instance. The adapter must have no remaining content representations.

Request:
adapterId   - ID of the adapter to permanently delete. Fails if any content
representations still reference this adapter.

Response:
adapterId   - ID of the adapter that was purged.

### Update content metadata

 - [POST /api/v1/content/update](https://api.tenovos.com/openapi/content-intelligence/content-storage/tenovos.content.contentservice.update.md): Updates the metadata of one or more content items without modifying the underlying binary file.

Request:
items                      - List of updates. Each item includes:
contentId               - ID of the content to update.
caption                  - Optional new caption.
description              - Optional new short description text.
extendedDescription     - Optional new extended description text.
image/video/document     - Optional replacement media dimension/duration properties.

Response:
items   - List of updated content items reflecting the applied metadata changes.

## Authentication

These endpoints provide authorization primitives for verifying user permissions and
bootstrapping new user access within the Content Intelligence Platform.

The platform uses a role-based access control (RBAC) model managed by the Authorization
service. Roles carry named permissions, and users are assigned one or more roles either
explicitly or via [User Groups](#tag/User-Groups).

- `has-permission` — check whether the calling user holds a specific named permission;
  use this as a guard in custom integrations before performing sensitive operations
- `assign-default-role` — assign the platform default role to a user, typically called
  during user provisioning or invite acceptance flows

For fine-grained, resource-level access decisions (e.g., "can this user access this
specific document?"), see [Access Control](#tag/Access-Control).
For managing the roles themselves, see [Roles](#tag/Roles).


### Check user permission

 - [POST /api/v1/authz/has-permission](https://api.tenovos.com/openapi/content-intelligence/authentication/tenovos.authz.authzservice.haspermission.md): Checks whether the authenticated user holds all of the specified permission IDs.

Request:
permissionIds   - List of permission IDs that the user must possess. Returns true if
the user has all specified permissions, or if the list is empty.

Response:
hasPermission   - True if the user holds every permission in the request; false otherwise.

### Assign default role

 - [POST /api/v1/authz/assign-default-role](https://api.tenovos.com/openapi/content-intelligence/authentication/tenovos.authz.authzservice.assigndefaultrole.md): Assigns the appropriate default role to a newly onboarded user within the organization.

Request:
userId   - The ID of the user to assign a default role to. The first user in an org
receives the default admin role; subsequent users receive the standard org user role.

Response:
(empty)

## User Groups

User Groups organize users into named collections for streamlined access control
and administration. Instead of assigning roles and permissions user-by-user, you assign
them to a group and manage membership centrally.

Groups support a full lifecycle:
- **Create / Update / Retrieve / List** — manage group definitions
- **Add Member / Revoke Member** — control who belongs to the group
- **Activate / Disable** — enable or suspend a group without deleting it;
  disabled groups do not grant their members any access
- **Purge** — permanently remove a group and its membership records

Groups integrate with the [Roles](#tag/Roles) and [Access Control](#tag/Access-Control)
systems, and are a key building block for multi-tenant or brand-scoped permission models.


### Create a user group

 - [POST /api/v1/user-group/create-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.createusergroup.md): Creates a new user group with an optional parent group for hierarchical organization.

Request:
name              - Display name of the user group.
description       - Description of the group's purpose or membership criteria.
parentGroupId   - Optional ID of an existing group to nest this group under.

Response:
userGroup        - The created UserGroupItem containing the assigned id, name,
description, and parentGroupId.

### Search user groups

 - [POST /api/v1/user-group/list-user-groups](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.listusergroups.md): Lists user groups within the organization, with optional filtering by parent or status.

Request:
includeDisabled    - When true, includes disabled groups in the results.
parentGroupId     - Optional parent group ID to return only direct child groups.

Response:
userGroups         - List of UserGroupItem objects matching the filter criteria.

### Disable a user group

 - [POST /api/v1/user-group/disable-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.disableusergroup.md): Soft-disables one or more user groups, cascading to all child groups recursively.

Request:
ids   - List of user group IDs to disable. All descendant groups are also disabled.

Response:
ids   - List of IDs of the groups that were successfully disabled.

### Permanently remove a group

 - [POST /api/v1/user-group/purge-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.purgeusergroup.md): Permanently deletes one or more user groups along with their memberships.

Request:
ids   - List of user group IDs to permanently delete.

Response:
ids   - List of IDs of the groups that were successfully purged.

### Update a user group

 - [POST /api/v1/user-group/update-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.updateusergroup.md): Updates the name and description of an existing user group.

Request:
id            - ID of the user group to update.
name          - New display name for the group.
description   - New description for the group.

Response:
id            - ID of the updated group.
name          - Updated display name.
description   - Updated description.

### Add member to group

 - [POST /api/v1/user-group/user-group-add-member](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.usergroupaddmember.md): Adds one or more users to a user group. Idempotent — adding an existing member succeeds silently.

Request:
groupId    - ID of the user group to add members to.
userIds    - List of user IDs to add to the group.

Response:
userIds    - List of user IDs that were successfully added.

### Remove member from group

 - [POST /api/v1/user-group/user-group-revoke-member](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.usergrouprevokemember.md): Removes one or more users from a user group. Idempotent — removing a non-member succeeds silently.

Request:
groupId    - ID of the user group to remove members from.
userIds    - List of user IDs to remove from the group.

Response:
userIds    - List of user IDs that were successfully removed.

### Get a user group

 - [POST /api/v1/user-group/retrieve-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.retrieveusergroup.md): Retrieves user group details by their IDs.

Request:
ids           - List of user group IDs to retrieve.

Response:
userGroups   - List of UserGroupItem objects matching the requested IDs.

### Activate a user group

 - [POST /api/v1/user-group/activate-user-group](https://api.tenovos.com/openapi/content-intelligence/user-groups/tenovos.authz.usergroupservice.activateusergroup.md): Re-enables one or more previously disabled user groups.

Request:
ids   - List of user group IDs to activate.

Response:
ids   - List of IDs of the groups that were successfully activated.

## Roles

Roles are named collections of [Permissions](#tag/Permissions) that define what actions
a user can perform across the platform. The platform uses a hierarchical RBAC model where
users are assigned roles (directly or via [User Groups](#tag/User-Groups)), and those roles
carry the permissions that gate access to API operations and content resources.

Role operations:
- **Create / Update** — define a role and specify which permissions it grants
- **Retrieve / List** — inspect role definitions across the organization
- **Activate / Disable** — toggle a role without deleting it; disabling a role
  immediately removes its permissions from all assigned users
- **Purge** — permanently delete a role

Roles are evaluated alongside fine-grained resource policies managed by
[Access Control](#tag/Access-Control) to produce the final authorization decision
for any given user and resource combination.


### Create a role

 - [POST /api/v1/role/create-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.createrole.md): Creates a new role of the given type with an initial set of permissions.

Request:
name              - Display name for the role.
roleType         - Whether this is a USER_ROLE (assigned to individual users) or a
GROUP_ROLE (assigned to user groups).
description       - Description of what this role grants.
permissionIds    - Non-empty list of permission IDs to associate with the role.

Response:
id                - Assigned role ID.
name              - Role display name.
roleType         - The role type.
description       - Role description.
permissionIds    - List of permission IDs associated with the role.

### Search roles

 - [POST /api/v1/role/list-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.listroles.md): Lists roles within the organization, with optional filtering by type or disabled status.

Request:
includeDisabled  - When true, includes disabled roles in the results.
roleType         - Optional filter to return only USER_ROLE or GROUP_ROLE roles.

Response:
roles             - List of RoleItem objects including id, name, type, description,
permissionIds, and whether the role is a system role.

### Get a role

 - [POST /api/v1/role/retrieve-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.retrieverole.md): Retrieves full role details by their IDs.

Request:
roleIds   - List of role IDs to retrieve.

Response:
roles      - List of RoleItem objects matching the requested IDs.

### Update a role

 - [POST /api/v1/role/update-role](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.updaterole.md): Updates the name, description, and permission set of an existing role.

Request:
id                - ID of the role to update.
name              - New display name.
description       - New description.
permissionIds    - Replacement list of permission IDs. Must be non-empty.

Response:
id                - ID of the updated role.
name              - Updated display name.
roleType         - Role type (unchanged).
description       - Updated description.
permissionIds    - Updated list of permission IDs.

### Disable roles

 - [POST /api/v1/role/disable-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.disableroles.md): Soft-disables one or more roles, making them inactive without permanent deletion.

Request:
ids   - List of role IDs to disable.

Response:
ids   - List of IDs of the roles that were successfully disabled.

### Permanently remove roles

 - [POST /api/v1/role/purge-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.purgeroles.md): Permanently deletes one or more roles and their associated permission records.

Request:
ids   - List of role IDs to permanently delete.

Response:
ids   - List of IDs of the roles that were successfully purged.

### Activate roles

 - [POST /api/v1/role/activate-roles](https://api.tenovos.com/openapi/content-intelligence/roles/tenovos.authz.roleservice.activateroles.md): Re-enables one or more previously disabled roles.

Request:
ids   - List of role IDs to activate.

Response:
ids   - List of IDs of the roles that were successfully activated.

## Users

Manage user accounts within an organization — from initial invitation through
ongoing profile management and access lifecycle.

- `create-invite` — send an email invitation to a new user; the invited user completes
  signup via the platform authentication flow (powered by Clerk)
- `retrieve / list-users` — inspect user profiles and organization membership
- `update-user` — modify user profile attributes
- `assign-user-role` — directly assign a [Role](#tag/Roles) to a specific user
- `disable-user` — suspend access without deleting the account
- `delete-user` — remove a user from the organization

User identity and authentication (login, SSO, MFA) are handled externally by Clerk.
These endpoints manage the platform-side user record, role assignments, and access state.


### Assign role to user

 - [POST /api/v1/user/user-assign-user-role](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.userassignuserrole.md): Assigns a role to a user, establishing their base permission set within the organization.

Request:
userId   - ID of the user to assign the role to.
roleId   - ID of the role to assign. The role must be of type USER_ROLE.

Response:
userId   - ID of the user the role was assigned to.
roleId   - ID of the role that was assigned.

### Get a user

 - [POST /api/v1/user/retrieve-user](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.retrieveuser.md): Retrieves full user profiles by their IDs, including auth provider data.

Request:
userIds   - List of user IDs to retrieve.

Response:
users      - List of User objects including email, name, role, group memberships,
last login time, profile picture URL, and enabled/invited status.

### Search users

 - [POST /api/v1/user/list-users](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.listusers.md): Lists users in the organization with optional search, role, and group filtering, supporting pagination.

Request:
searchQuery   - Free-text query to filter users by email or name.
roleId        - Optional role ID to return only users with that role.
groupId       - Optional group ID to return only users in that group.
pagination     - Optional Pagination cursor and page size for iterating large result sets.

Response:
users          - List of User objects matching the filter criteria.
pageCursor    - Opaque cursor for the next page. Absent when there are no further results.

### Delete a user

 - [POST /api/v1/user/delete-user](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.deleteuser.md): Permanently removes a user from the organization, including all group memberships and role assignments.

Request:
id   - ID of the user to permanently delete. This operation cannot be undone.

Response:
(empty)

### Disable a user

 - [POST /api/v1/user/disable-user](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.disableuser.md): Soft-disables one or more users, marking them as inactive while preserving their records.

Request:
userIds   - List of user IDs to disable. Disabled users have isEnabled set to false.

Response:
userIds   - List of user IDs that were successfully disabled.

### Update a user

 - [POST /api/v1/user/update-user](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.updateuser.md): Updates profile fields and group/role assignments for a user. All fields are optional.

Request:
userId      - ID of the user to update.
firstName   - Optional replacement first name.
lastName    - Optional replacement last name.
roleId      - Optional replacement role ID.
groupIds    - Optional replacement list of group memberships.
username     - Optional replacement username.

Response:
userId      - ID of the updated user.

### Invite a user

 - [POST /api/v1/user/create-invite](https://api.tenovos.com/openapi/content-intelligence/users/tenovos.authz.userservice.createinvite.md): Sends invitations to new users and creates their accounts with a pre-assigned role and groups.

Request:
emails                - List of email addresses to invite.
roleId               - Role to assign to all invited users.
groupIds             - List of group IDs to add all invited users to.
defaultSiteDomain   - The site domain context used for the invitation link.

Response:
userIds              - List of IDs of the newly created user accounts.

## Permissions

Permissions are the atomic units of access control — named capabilities that define
what a user or role is allowed to do (e.g., `document:create`, `content:delete`,
`channel:manage`). Permissions are grouped into [Roles](#tag/Roles), which are then
assigned to users or [User Groups](#tag/User-Groups).

- `list-permissions` — enumerate all permissions defined in the platform; use this to
  understand what capabilities are available when designing custom roles
- `create-permission` — define a new named permission, typically used when extending
  the platform with custom action types or integration-specific access gates


### Search permissions

 - [POST /api/v1/permission/list-permissions](https://api.tenovos.com/openapi/content-intelligence/permissions/tenovos.authz.permissionservice.listpermissions.md): Lists all permissions defined in the system, with optional filtering by role.

Request:
roleId       - Optional role ID to return only permissions associated with that role.

Response:
permissions   - List of PermissionItem objects (id, name, description).

### Create a permission

 - [POST /api/v1/permission/create-permission](https://api.tenovos.com/openapi/content-intelligence/permissions/tenovos.authz.permissionservice.createpermission.md): Creates a new named permission that can be assigned to roles.

Request:
id            - Unique identifier for the permission (caller-supplied, not auto-generated).
name          - Human-readable display name.
description   - Optional description of what this permission grants.

Response:
permission    - The created PermissionItem.

## Access Control

Access Control provides fine-grained, resource-level authorization on top of the
role-based model. Where [Roles](#tag/Roles) and [Permissions](#tag/Permissions) define
what a user can do in general, Access Control governs what a user can do to a
specific resource (e.g., a particular document, channel, or brand).

Document-level access supports two grant types:

| Grant | Description |
|---|---|
| `READ` | User can view and retrieve the resource |
| `MODIFY` | User can update or delete the resource |

- `has-access` — evaluate whether the calling user has access to a specific resource;
  the primary authorization check for content-level operations
- `retrieve-resource-groups` — list the logical resource groups a user has access to,
  used for scoping queries and UI navigation
- `grant-access` — explicitly grant a user or group access to a specific resource
- `revoke-access` — remove a previously granted resource-level access


### Check content access

 - [POST /api/v1/access-control/has-access](https://api.tenovos.com/openapi/content-intelligence/access-control/tenovos.authz.accesscontrolservice.hasaccess.md): Checks whether the authenticated user holds specific permissions on one or more resources. Evaluates both role-based and fine-grained resource access grants to produce the final result.

Request:
resourceIds      - List of resource IDs to evaluate access for.
permissionsIds   - List of permission IDs to check against each resource.

Response:
accessResult     - List of results, one per resource-permission combination. Each entry contains the resourceId, permissionId, and a hasAccess boolean indicating whether access is granted.

### Get resource groups

 - [POST /api/v1/access-control/retrieve-resource-groups](https://api.tenovos.com/openapi/content-intelligence/access-control/tenovos.authz.accesscontrolservice.retrieveresourcegroups.md): Returns the resource group IDs that define the scope of the authenticated user's fine-grained access. Resource groups categorize access by source — use these IDs to scope content queries and permission checks to only what the user can see.

Request:
No parameters required.

Response:
resourceGroupIds      - Groups assigned directly to this user.
contextGroupsIds      - Groups derived from the user's current site or organization context.
permissionGroupsIds   - Groups inherited through the user's membership in one or more user groups.

### Grant content access

 - [POST /api/v1/access-control/grant-access](https://api.tenovos.com/openapi/content-intelligence/access-control/tenovos.authz.accesscontrolservice.grantaccess.md): Grants resource-level access on one or more content entities to specified users or groups. Each grant specifies an access level of READ (view and retrieve) or MODIFY (update and delete).

Request:
entityIds              - List of content entity IDs to grant access on.
principalPermissions   - List of grants, each specifying a user or group ID and the permission level to grant (READ or MODIFY).

Response:
entityIds              - List of entity IDs on which access was successfully granted.
principalPermissions   - The list of grants that were applied.

### Revoke content access

 - [POST /api/v1/access-control/revoke-access](https://api.tenovos.com/openapi/content-intelligence/access-control/tenovos.authz.accesscontrolservice.revokeaccess.md): Revokes all fine-grained access grants for a principal on one or more entities.

Request:
entityIds              - List of entity IDs to revoke access on.
principalResourceId   - The resource ID of the user or group whose access is being revoked.

Response:
entityIds   - List of entity IDs for which access was successfully revoked.

## API Keys

API Keys enable programmatic, non-interactive access to the platform — suitable
for server-to-server integrations, CI/CD pipelines, and automated content workflows
that cannot use user-delegated OAuth tokens.

Each API key is scoped to the organization of the user who creates it and carries
that user's permissions. Keys should be stored securely and rotated regularly.

- `create-api-key` — generate a new API key; the raw key value is only returned once at creation
- `list-api-keys` — enumerate existing keys (key values are not re-exposed)
- `revoke-api-key` — permanently invalidate a key; any integrations using it will lose access immediately


### Create an API key

 - [POST /api/v1/api-key/create-api-key](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.createapikey.md): Creates a new API key for programmatic access, assigning it a role that defines its permissions.

Request:
name          - Human-readable label for the API key.
expiresAt    - Optional expiry timestamp. If omitted the key does not expire.
roleId       - Role to assign to the API key's associated service account, determining
what operations the key is authorized to perform.

Response:
id            - Assigned API key ID.
name          - Key display name.
keyHint      - Last 4 characters of the key, for identification purposes.
expiresAt    - Expiry timestamp if one was set.
key           - The full plaintext API key. This is the only time the full key is returned;
it is stored hashed and cannot be retrieved again.

### Search API keys

 - [POST /api/v1/api-key/list-api-keys](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.listapikeys.md): Lists API keys in the organization with optional filtering for revoked or expired keys.

Request:
pageCursor       - Optional cursor for paginating through results.
maxSize          - Optional maximum number of results to return per page.
includeRevoked   - When true, includes revoked keys in the results.
includeExpired   - When true, includes expired keys in the results.

Response:
apiKeys      - List of ApiKey objects (id, name, keyHint, timestamps). Full key values
are never returned.
pagination    - Pagination object containing the cursor for the next page.

### Revoke an API key

 - [POST /api/v1/api-key/revoke-api-key](https://api.tenovos.com/openapi/content-intelligence/api-keys/tenovos.authz.apikeyservice.revokeapikey.md): Revokes an API key, permanently deactivating it so it can no longer be used for authentication.

Request:
id         - ID of the API key to revoke. Revocation cannot be undone.

Response:
apiKey    - The ApiKey record with the revokedAt timestamp populated.

## Channels

Channels are the integration layer for connecting to external content systems —
cloud storage, DAM platforms, social media, enterprise file systems, and others. Each
Channel is a configured, authenticated connection to one of these external sources that
the platform monitors, indexes, and keeps in sync.

The Channel Manager authenticates against external systems, scans for new and modified
content, manages webhook subscriptions for real-time change notifications, and makes
raw content available for retrieval — without managing the binary files directly.
Binary retrieval is handled via pre-signed URLs delegated to [Content Storage](#tag/Content-Storage).

**Channel categories:**

| Category | Description |
|---|---|
| `ORIGIN` | External content source to pull from (Box, Google Drive, SharePoint, S3, DAMs, etc.) |
| `OBSERVATION` | External system to observe for engagement events (Instagram, Facebook, Website, etc.) |
| `DELIVERY` | Destination to push content to |

**Currently available channel types:**

*Origin (content pull):*
| Channel | Group | Auth |
|---|---|---|
| Box | Cloud File Storage | OAuth |
| Google Drive | Cloud File Storage | OAuth |
| AWS S3 | Object Store | Service Credentials |
| Tenovos DAM | DAM | OAuth |
| Adobe AEM | DAM | Service Credentials |
| Sitecore | DAM | OAuth |
| Bynder | DAM | OAuth |
| Brand Folder | DAM | OAuth |
| Azure Blob | Object Store | OAuth |
| Google Cloud Storage | Object Store | OAuth |
| SharePoint | Cloud File Storage | OAuth |

*Observation (engagement events):*
| Channel | Group |
|---|---|
| Instagram | Social |
| Facebook | Social |
| Website | Content Management and Sites |

**Authentication methods:**

| Auth Type | Description |
|---|---|
| `OAUTH` | User-delegated OAuth 2.0 flow; use `retrieve-oauth-url` then `update-auth` |
| `API_KEY` | Static API key submitted during channel creation |
| `BASIC_AUTH` | Username and password credentials |
| `SERVICE_CREDENTIALS` | Service account JSON or IAM role credentials (used by Adobe AEM, AWS S3) |

**Channel status lifecycle:**

| Status | Description |
|---|---|
| `DRAFT` | Channel created but not yet authenticated |
| `AUTHENTICATED` | Credentials stored; not yet scanning |
| `ENABLED` | Actively scanning and webhook-registered |
| `DISABLED` | Paused; configuration and credentials retained |

**Channel lifecycle endpoints:**
- `list-channel-types / retrieve-channel-types` — discover available integrations and their configuration requirements
- `create-channel` — configure a new connection (name, settings, auth)
- `update-channel` — modify an existing channel's settings
- `enable-channel` — activate scanning and webhook registration; channel begins syncing content
- `disable-channel` — pause sync without deleting configuration; webhooks are torn down
- `delete-channel / purge-channels` — remove channel(s) and all associated webhooks and scan state
- `validate-channel-config` — test credentials and connectivity before enabling; returns `OK`, `AUTH_FAILURE`, or `CONFIG_FAILURE`

**Authentication flow endpoints:**
- `retrieve-oauth-url` — get the OAuth authorization URL to redirect a user through
- `update-auth` — exchange an OAuth authorization code or service credentials for stored tokens

**Content discovery endpoints:**
- `retrieve-folders` — browse the folder, site, or library tree of a connected source
- `get-config-description` — fetch the dynamic field schema for configuring a channel type; field types are `TREE`, `DROPDOWN`, or `TEXT`
- `get-config-details` — retrieve selectable items (sites, folders, document libraries) for a specific channel instance
- `scan-content` — manually trigger or resume a paginated content scan
- `retrieve-content` — generate pre-signed download URLs for specific content items from the source
- `retrieve-content-metadata` — fetch metadata for a specific item directly from the external source
- `retrieve-content-data` — stream raw file content from the external source
- `retrieve-channel-account` — return the authenticated account info (user profile, tenant ID, etc.) for a connected channel

**Sync and operations:**
- `resolve-webhook-payload` — parse an inbound push notification from an external system into a normalized platform event (used internally)
- `channel-stats` — retrieve scan statistics and sync state (`ACTIVE`, `INACTIVE`, `SYNCING`, or `ERROR`) for a channel

**Scan behavior:**
Enabled channels run on an automatic schedule. Initial scans perform a full content crawl;
subsequent delta scans (default interval: 10 minutes) retrieve only changes since the last
successful scan using source-native change detection (e.g., Graph delta queries for SharePoint,
change tokens for Box). Failed scans retry up to 5 times with a 30-minute cooldown between attempts.


### Browse channel types

 - [POST /api/v1/channel/list-channel-types](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.listchanneltypes.md): Lists the available channel type templates with optional filtering. Use this to discover which integrations are available and what authentication and configuration each requires before creating a channel.

Request:
query.category       - Filter by channel category: ORIGIN (content source systems such as Box, SharePoint, or S3), OBSERVATION (systems monitored for engagement events such as Instagram or a website), or DELIVERY (destination systems to push content to).
query.enabled        - When true, returns only types that are currently available for use. When false, returns only types that are not yet enabled.
query.hasInstance   - When true, returns only types for which the organization already has at least one configured channel.
pagination           - Optional pagination cursor and page size.

Response:
channelTypes   - List of channel types, each including its name, description, authentication method, logo, category, and whether it supports real-time webhook sync.
pageCursor     - Opaque cursor for the next page. Absent when no further results exist.

### Get channel types

 - [POST /api/v1/channel/retrieve-channel-types](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievechanneltypes.md): Retrieves full channel type definitions by their IDs.

Request:
ids             - List of channel type IDs to retrieve.

Response:
channelTypes   - List of ChannelType objects including authentication requirements and
auth description detailing credential fields.

### Search channels

 - [POST /api/v1/channel/list-channels](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.listchannels.md): Lists channel instances owned by the organization, with optional filtering and pagination.

Request:
category           - Optional category filter (ORIGIN, OBSERVATION, DELIVERY).
pagination         - Optional Pagination cursor and page size.
includeDeleted    - When true, includes soft-deleted channels in the results.

Response:
channelInstances  - List of ChannelInstance objects including id, name, status, settings,
scan state, and timestamps.
pageCursor        - Opaque cursor for the next page. Absent when there are no further results.

### Get channels

 - [POST /api/v1/channel/retrieve-channels](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievechannels.md): Retrieves full channel instance details by their IDs.

Request:
ids                - List of channel instance IDs to retrieve.

Response:
channelInstances  - List of ChannelInstance objects with complete configuration and status.

### Create a channel

 - [POST /api/v1/channel/create-channel](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.createchannel.md): Creates a new channel instance connecting the organization to an external system.

Request:
channelInstance   - The channel to create, including channelTypeId, name, optional
description, and type-specific settings.
authDetails       - Authentication credentials for the external system (OAuth code,
API key, basic auth, or service credentials).

Response:
channelInstance   - The created ChannelInstance in DRAFT status with its assigned ID.

### Update a channel

 - [POST /api/v1/channel/update-channel](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.updatechannel.md): Updates the name, description, and configuration settings of an existing channel instance.

Request:
channelInstance   - Update payload containing the channel id, new name, optional
description, and updated settings. Authentication credentials are
not changed by this call; use UpdateAuth for that.

Response:
updated            - Number of records updated (1 on success).

### Enable a channel

 - [POST /api/v1/channel/enable-channel](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.enablechannel.md): Activates a channel, registering webhooks with the external system and starting content synchronization.

Request:
channelId   - ID of the channel to enable. The channel must be in AUTHENTICATED or DISABLED status.

Response:
enabled      - True if the channel was successfully enabled.

### Disable a channel

 - [POST /api/v1/channel/disable-channel](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.disablechannel.md): Deactivates a channel, deregistering webhooks and suspending content synchronization.

Request:
channelId   - ID of the channel to disable.

Response:
disabled     - True if the channel was successfully disabled.

### Validate channel config

 - [POST /api/v1/channel/validate-channel-config](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.validatechannelconfig.md): Tests a channel's configuration and credentials against the external system, returning a validation report.

Request:
channelId   - ID of the channel to validate.

Response:
report       - ValidationReport containing a status (OK, AUTH_FAILURE, CONFIG_FAILURE, FAILED)
and a list of error messages describing any failures found.

### Delete a channel

 - [POST /api/v1/channel/delete-channel](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.deletechannel.md): Soft-deletes a channel instance, disabling it and retaining historical records for audit purposes.

Request:
channelId   - ID of the channel to delete.

Response:
deleted      - Number of records deleted (1 on success).

### Get channel OAuth URL

 - [POST /api/v1/channel/retrieve-oauth-url](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrieveoauthurl.md): Generates an OAuth authorization URL for initiating the OAuth flow for a given channel type.

Request:
channelTypeId        - ID of the channel type to generate an OAuth URL for.
customRedirectUri    - Optional override for the OAuth redirect URI.

Response:
url   - The OAuth authorization URL to redirect the user to.

### Update channel auth

 - [POST /api/v1/channel/update-auth](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.updateauth.md): Updates or rotates the authentication credentials for an existing channel without changing other settings.

Request:
channelId     - ID of the channel whose credentials are being updated.
authDetails   - New credentials (OAuth code, API key, basic auth, or service credentials).
Credentials are encrypted before storage.

Response:
(empty)

### Get channel folders

 - [POST /api/v1/channel/retrieve-folders](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievefolders.md): Enumerates the folder or directory hierarchy available in the external system connected by the channel.

Request:
channelId    - ID of the channel to browse.
parentId     - ID of the folder to list children of. Use the root ID to start at the top level.
pagination    - Optional Pagination cursor and page size for large folder listings.

Response:
folders       - List of Folders objects with id, name, isLeaf, and type
(FOLDER, SAVED_SEARCH, or VOCAB).
pageCursor   - Opaque cursor for the next page.

### Get channel account

 - [POST /api/v1/channel/retrieve-channel-account](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievechannelaccount.md): Retrieves account information (name, email, avatar) from the external system the channel is connected to.

Request:
channelId   - ID of the channel to retrieve account information for.

Response:
account      - ChannelAccount containing the name, email, and avatarUrl of the connected account.

### Get channel content

 - [POST /api/v1/channel/retrieve-content](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievecontent.md): Generates download or streaming URLs for one or more content items in an external system.

Request:
query   - List of ContentRetrievalQuery entries, each specifying a channelId and a
contentUri identifying the item to retrieve.

Response:
urls    - List of ContentRetrievalResponse entries, each containing a URL, the auth
mechanism required (bearer token, basic auth, or headers), and whether the
content must be accessed via streaming only.

### Get channel content metadata

 - [POST /api/v1/channel/retrieve-content-metadata](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievecontentmetadata.md): Fetches file metadata for a single content item identified by its URI.

Request:
contentUri   - URI of the content item to retrieve metadata for.

Response:
metadata      - ScanContent.Metadata containing content properties (dimensions, duration,
page count, file size, MIME type) and any custom metadata from the external system.

### Get channel content data

 - [POST /api/v1/channel/retrieve-content-data](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.retrievecontentdata.md): Streams the raw binary data of a content item in chunks (server-streaming RPC).

Request:
contentUri       - URI of the content item to stream.

Response (stream):
ResponseChunk.data   - Successive byte chunks of the content. The stream ends when all
data has been delivered.

### Scan channel content

 - [POST /api/v1/channel/scan-content](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.scancontent.md): Scans a channel to discover all available content items, returning paginated metadata for each.

Request:
channelId    - ID of the channel to scan.
pagination    - Optional Pagination cursor and page size.

Response:
content       - List of ScannedContent entries, each containing a URI and Metadata
(content properties and custom data from the external system).
pageCursor   - Opaque cursor for the next page. Absent when scan is complete.

### Retrieve channel type configuration schema

 - [POST /api/v1/channel/get-config-description](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.getconfigdescription.md): Returns the configuration schema for a channel type — the set of parameters a user must supply when setting up a channel of that type. Use this to dynamically render a configuration form before calling create-channel or update-channel.

Request:
channelTypeId   - ID of the channel type to retrieve the configuration schema for.

Response:
configuration     - List of configuration parameters, each including an id, display label, input type, whether it is required, and whether it supports multiple selections. Input types are TREE (hierarchical picker, e.g. folder or site selection), DROPDOWN (single or multi-select list), or TEXT (free-form text input).

### Retrieve selectable options for a channel configuration parameter

 - [POST /api/v1/channel/get-config-details](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.getconfigdetails.md): Retrieves the selectable options for one or more configuration parameters of an authenticated channel — for example, the list of SharePoint sites, Box folders, or S3 buckets available under the connected account. Use this to populate pickers in your configuration UI after the channel has been authenticated.

Request:
channelId    - ID of the authenticated channel to retrieve options for.
configId     - List of configuration parameter IDs to retrieve options for (as returned by get-config-description).
parentId     - For hierarchical parameters, the ID of the parent item whose children to retrieve (e.g., a SharePoint site ID when listing its document libraries).
pagination    - Optional pagination cursor and page size.

Response:
values        - Selectable options for each requested parameter, keyed by configId.
pageCursor   - Opaque cursor for the next page. Absent when no further results exist.

### Map a webhook notification to affected content

 - [POST /api/v1/channel/resolve-webhook-payload](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.resolvewebhookpayload.md): Translates an inbound webhook notification from an external system into the platform's internal content identifiers for the affected items. When an external system (such as Box or SharePoint) sends a change notification, use this endpoint to determine which content records in the platform correspond to the changed resource before triggering a sync or update.

Request:
externalSourceId   - The resource identifier from the external system's webhook payload (e.g., a file ID, node ID, or object key).
channelId           - ID of the channel that received the webhook.

Response:
channelContentIds  - Platform content IDs for the items affected by the external change event.

### Get channel statistics

 - [POST /api/v1/channel/channel-stats](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.channelstats.md): Retrieves synchronization statistics and health state for one or more channels over an optional time period.

Request:
ids      - List of channel IDs to retrieve statistics for.
period   - Optional time range (from/to timestamps) for period-based metrics.
If omitted, all-time totals are returned.

Response:
stats    - List of Stats objects, one per channel, each containing:
periodStats  - Asset created/updated/deleted counts, error count, and recent errors.
channelState - Last sync time, next scheduled scan, and current scan state
(ACTIVE, INACTIVE, SYNCING, or ERROR).

### Permanently remove channels

 - [POST /api/v1/channel/purge-channels](https://api.tenovos.com/openapi/content-intelligence/channels/tenovos.channel.channelmanagerservice.purgechannels.md): Permanently deletes channel instances that have never successfully ingested content.

Request:
ids   - List of channel IDs to permanently delete. Channels that have already synced content
are excluded to preserve data integrity.

Response:
ids   - List of IDs of the channels that were successfully purged.

## Workflows

Workflows (internally "flows") are the orchestration mechanism for longer-running,
multi-step content operations. Where individual API calls handle atomic short-lived
operations, Workflows wire multiple service calls together into a **composite action** —
for example: ingest content from a Channel → extract metadata → apply Document Rules →
publish to a destination.

The platform's services are designed around short-lived RPC calls. Workflows bridge them
into durable, sequenced processes managed by the Action & Media Flows service, with each
step tracked as a [Job](#tag/Jobs).

- **Create / Update** — define a workflow, its steps, and step configuration
- **Retrieve / List** — inspect workflow definitions; `list-default-groups` returns
  platform-provided workflow templates as a starting point
- **Enable / Disable** — activate or pause a workflow without deleting it
- **Purge** — permanently remove a workflow definition

Running instances of a workflow are tracked as [Jobs](#tag/Jobs). Use the Jobs API
to monitor progress, handle failures, and restart or cancel executions.


### Create a workflow

 - [POST /api/v1/flow/create](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.create.md): Creates one or more flows, each defined by a name, optional description, and a hierarchical task tree.

Request:
items      - List of flow definitions to create. Each item includes a name, optional description,
and a taskTree defining the root action and any child/reference tasks. All flows
are created in DRAFT status.
groupId   - Optional ID of a workflow template group. When provided, the platform also provisions any standard flows defined for that group, giving the organization a pre-configured starting set of workflows.

Response:
items      - The fully hydrated Flow objects that were created, including their assigned IDs
and complete task tree structures.

### Get a workflow

 - [POST /api/v1/flow/retrieve](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.retrieve.md): Retrieves one or more flows by their IDs, returning full flow definitions including task trees.

Request:
ids        - List of flow IDs to retrieve.

Response:
items      - The fully hydrated Flow objects, each including the complete task tree with
nested children, conditions, mappings, and configurations.

### Search workflows

 - [POST /api/v1/flow/list](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.list.md): Lists available flows as lightweight summaries, with optional filtering and pagination.

Request:
includeDisabled - When true, includes flows with DISABLED status in the results.
Defaults to false (only DRAFT and ENABLED flows are returned).
pagination       - Optional Pagination cursor and page size for iterating large result sets.

Response:
items            - List of FlowSummary objects (id, name, description, status, timestamps)
ordered by name. Does not include full task tree details.
pageCursor      - Opaque cursor to pass in a subsequent request to retrieve the next page.
Absent when there are no further results.

### Update a workflow

 - [POST /api/v1/flow/update](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.update.md): Updates the name, description, and task tree of one or more existing flows.

Request:
updates    - List of flow updates. Each update must include the flow ID and the full
replacement name and task tree. Flows with active running jobs cannot be updated.

Response:
items      - The fully hydrated Flow objects reflecting the applied updates.

### Permanently remove a workflow

 - [POST /api/v1/flow/purge](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.purge.md): Permanently deletes one or more flows. Only flows that are not in ENABLED status can be purged.

Request:
ids        - List of flow IDs to permanently delete. Enabled flows are excluded from deletion.

Response:
ids        - List of IDs of the flows that were successfully deleted.

### Enable a workflow

 - [POST /api/v1/flow/enable](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.enable.md): Activates one or more flows, allowing them to be triggered by events and create jobs.

Request:
ids        - List of flow IDs to enable. Each flow transitions from DRAFT or DISABLED to ENABLED.
Enabling registers the flow's root task as a trigger on the appropriate event subject,
including any conditional trigger expressions.

Response:
ids        - List of IDs of the flows that were successfully enabled.

### Disable a workflow

 - [POST /api/v1/flow/disable](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.disable.md): Deactivates one or more flows, preventing them from creating new jobs.

Request:
ids        - List of flow IDs to disable. Flows with active running jobs cannot be disabled.
Disabling removes the associated event triggers so no new jobs will be created.

Response:
ids        - List of IDs of the flows that were successfully disabled.

### Get default workflow groups

 - [POST /api/v1/flow/list-default-groups](https://api.tenovos.com/openapi/content-intelligence/workflows/tenovos.action.flowservice.listdefaultgroups.md): Returns the set of system-defined default flow groups, each containing their associated flows.

Request:
(no parameters)

Response:
groups     - List of Group objects, each containing a groupId and a list of FlowSummary
objects belonging to that group. Only system-level (non-org-specific) flows
are included. Used to seed default workflows when onboarding a new organization.

## Actions

Actions are the individual, atomic operations that can be composed into
[Workflows](#tag/Workflows). Each action represents a discrete capability of the
platform — for example, "ingest document from channel", "run media transform",
"apply metadata schema", "send notification", or "publish to destination".

These endpoints are read-only discovery endpoints:
- `list` — enumerate all available actions in the platform; filter by category or type
  to find actions relevant to a specific workflow step
- `retrieve` — fetch the full definition of a specific action, including its input
  parameters, output shape, and configuration requirements

Use the Actions API to programmatically build or validate workflow definitions without
relying on hardcoded action identifiers.


### List available actions

 - [POST /api/v1/action/list](https://api.tenovos.com/openapi/content-intelligence/actions/tenovos.action.actionservice.list.md): Lists the available action definitions that can be used as steps within a workflow. Use this to discover which operations are available and what inputs each requires before building or validating a workflow.

Request:
type             - Optional filter by action role: ACTION (a standard executable step), TRIGGER (an event that starts a workflow), or CONDITION_ACTION (a conditional branch step).
inputEntities   - Optional filter by the data types the action consumes (e.g. ASSET, DOCUMENT, CONTENT). When provided, only actions compatible with all specified types are returned.

Response:
items            - List of available actions including each action's ID, name, group, description, role type, and the input and output entity types it works with. Full parameter schemas are available via the retrieve endpoint.

### Get an action

 - [POST /api/v1/action/retrieve](https://api.tenovos.com/openapi/content-intelligence/actions/tenovos.action.actionservice.retrieve.md): Retrieves full action definitions by their IDs, including complete input and output schemas.

Request:
ids        - List of action IDs to retrieve.

Response:
items      - The fully hydrated Action objects, each including the complete inputSchema,
outputSchema, configurationSchema, type, group, description, and entity mappings.

## Jobs

Jobs represent individual executions of [Workflow](#tag/Workflows) steps or standalone
async operations (such as a media transform). The Job system provides visibility into
the progress, status, and output of long-running background tasks managed by the
Action & Media Flows service.

Each job moves through a lifecycle: queued → running → succeeded / failed. Jobs run
in isolated per-organization priority queues, ensuring one organization's workload does
not block another's.

- `list` — query jobs by workflow, status, date range, or content reference
- `retrieve` — fetch the full status, logs, and output of a specific job
- `restart` — re-queue a failed job; useful for transient failures such as network
  timeouts or temporary service unavailability
- `cancel` — terminate a running or queued job; the job will not be retried


### Search jobs

 - [POST /api/v1/job/list](https://api.tenovos.com/openapi/content-intelligence/jobs/tenovos.action.jobservice.list.md): Lists job execution records with optional filtering by status or flow, supporting pagination.

Request:
jobStatus   - Optional JobStatus filter (CREATED, RUNNING, COMPLETE, FAILED, SUSPENDED, CANCELED).
flowId      - Optional flow ID to return only jobs triggered by that specific flow.
pagination   - Optional Pagination cursor and page size for iterating large result sets.

Response:
jobs         - List of Job objects ordered by event date descending, including current status,
current task ID, payload, and execution timestamps.
pageCursor  - Opaque cursor to pass in a subsequent request to retrieve the next page.
Absent when there are no further results.

### Get job details

 - [POST /api/v1/job/retrieve](https://api.tenovos.com/openapi/content-intelligence/jobs/tenovos.action.jobservice.retrieve.md): Retrieves detailed job information by ID, including the full audit trail of task executions.

Request:
ids        - List of job IDs to retrieve.

Response:
jobs       - The fully hydrated Job objects, each including the auditTrail with per-task
execution history (task ID, status, message, details, timestamp), the triggering
payload, the current task ID, and who started the job and when.

### Restart a job

 - [POST /api/v1/job/restart](https://api.tenovos.com/openapi/content-intelligence/jobs/tenovos.action.jobservice.restart.md): Restarts one or more jobs that are in a terminal state (FAILED, COMPLETE, or CANCELED).

Request:
ids        - List of job IDs to restart. Only jobs in a terminal state (FAILED, COMPLETE, or CANCELED) are eligible. The original jobs are not modified — a new job is created for each, preserving the original workflow and input payload.

Response:
ids        - IDs of the newly created jobs. Use these to track the restarted executions via the retrieve or list endpoints.

### Cancel a job

 - [POST /api/v1/job/cancel](https://api.tenovos.com/openapi/content-intelligence/jobs/tenovos.action.jobservice.cancel.md): Cancels one or more in-progress jobs, stopping further task execution.

Request:
ids        - List of job IDs to cancel. Only jobs not already in a terminal state
(FAILED, COMPLETE, or CANCELED) can be canceled. Jobs in RUNNING or
SUSPENDED states are eligible.

Response:
ids        - List of IDs of the jobs that were successfully canceled.

## Share Authentication

Share Authentication handles identity verification for **external recipients** —
people outside the organization who have received a share link but do not have
a platform account.

The platform uses a one-time passcode (OTP) flow for external share access:
1. The recipient visits a share link and enters their email address
2. `generate-otp` sends a time-limited OTP to that address
3. The recipient submits the OTP via `exchange-otp`, which returns a short-lived
   access token scoped to the specific share

This token is then used to call the [Shared Content](#tag/Shared-Content) endpoints.
It grants access only to what was explicitly included in the share — no other
platform data is accessible.


### Generate share access code

 - [POST /api/v1/share-auth/generate-otp](https://api.tenovos.com/openapi/content-intelligence/share-authentication/tenovos.sharing.shareauthservice.generateotp.md): Generates and sends a one-time passcode (OTP) to the recipient of a share, initiating passwordless authentication.

Request:
shareAccessId      - The share access ID identifying which share the OTP is for.
expiresInSeconds   - Lifetime of the generated OTP in seconds.

Response:
(empty) - The OTP is delivered out-of-band (e.g. via email) to the share recipient.

### Exchange code for token

 - [POST /api/v1/share-auth/exchange-otp](https://api.tenovos.com/openapi/content-intelligence/share-authentication/tenovos.sharing.shareauthservice.exchangeotp.md): Exchanges a valid OTP for a short-lived access token that grants access to the share.

Request:
shareAccessId   - The share access ID the OTP was generated for.
otp               - The one-time passcode provided by the share recipient.

Response:
token          - A short-lived bearer token granting access to the associated share.
expiresIn     - Lifetime of the token in seconds.

## Sharing

The Sharing API lets platform users distribute content to external recipients — people
without a platform account — in a controlled, auditable way. Shares are scoped to
specific documents or collections and can be time-limited, password-protected,
or restricted to specific recipient email addresses.

- `create` — create a new share, specifying documents, recipients, expiry, and access level
- `update` — modify share settings (expiry date, recipient list, permissions)
- `retrieve / list` — inspect share details and enumerate active shares in the organization
- `update-access` — adjust what a specific recipient can do (view-only, download, etc.)
- `revoke` — immediately invalidate a share; recipients lose access on their next request

External recipients authenticate into a share using [Share Authentication](#tag/Share-Authentication)
and then access content via [Shared Content](#tag/Shared-Content).


### Create a share

 - [POST /api/v1/share/create](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.create.md): Creates a new share granting one or more external users access to a set of documents until an expiry time.

Request:
users            - List of User entries specifying each recipient's email and access level
(VIEW or VIEW_DOWNLOAD).
documentIds     - List of document IDs to include in the share.
expiryTime      - Timestamp at which the share will automatically expire.
siteId          - ID of the site through which recipients will access the share.

Response:
shareItem   - The created ShareItem including its assigned id, users, documentIds,
expiryTime, siteId, createdAt, and initial status (ACTIVE).

### Update a share

 - [POST /api/v1/share/update](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.update.md): Updates the document list and/or expiry time of an existing share.

Request:
id               - ID of the share to update.
documentIds     - Replacement list of document IDs for the share.
expiryTime      - New expiry timestamp for the share.

Response:
shareItem   - The updated ShareItem reflecting the applied changes.

### Get a share

 - [POST /api/v1/share/retrieve](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.retrieve.md): Retrieves a share by its ID.

Request:
id   - ID of the share to retrieve.

Response:
shareItem   - The ShareItem including users, documentIds, expiryTime, status, and timestamps.

### Search shares

 - [POST /api/v1/share/list](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.list.md): Lists shares created by the authenticated user, with optional inclusion of revoked shares and pagination.

Request:
includeRevoked    - When true, includes shares with REVOKED status in the results.
pagination         - Optional Pagination cursor and page size.

Response:
shareItems        - List of ShareItem objects matching the filter.
nextPageCursor   - Opaque cursor for the next page. Absent when there are no further results.

### Update share access

 - [POST /api/v1/share/update-access](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.updateaccess.md): Updates the access level for one or more recipients of an existing share.

Request:
id             - ID of the share to update access for.
emails         - List of recipient email addresses whose access level is being changed.
accessLevel   - The new access level to assign (VIEW or VIEW_DOWNLOAD).

Response:
id      - ID of the updated share.
users   - Updated list of User entries reflecting the new access levels.

### Revoke a share

 - [POST /api/v1/share/revoke](https://api.tenovos.com/openapi/content-intelligence/sharing/tenovos.sharing.shareservice.revoke.md): Revokes a share, immediately preventing all recipients from accessing it.

Request:
id   - ID of the share to revoke. The share status is set to REVOKED.

Response:
id   - ID of the share that was revoked.

## Shared Content

These endpoints are called by **external share recipients** after authenticating via
[Share Authentication](#tag/Share-Authentication). They provide a read-only, scoped
view of the content included in a specific share — no other platform data is accessible.

- `retrieve-shared-documents` — list the documents included in the share, with metadata
- `retrieve-content` — get a pre-signed download URL for a specific shared content item
- `retrieve-branding-content` — fetch branding assets (logo, colors, fonts) associated
  with the share, used to render the share portal with the sender's organization branding


### Get shared documents

 - [POST /api/v1/share-retrieval/retrieve-shared-documents](https://api.tenovos.com/openapi/content-intelligence/shared-content/tenovos.sharing.shareretrievalservice.retrieveshareddocuments.md): Returns the documents included in the share associated with the authenticated share token.

Request:
(no parameters) - The share is identified from the caller's bearer token issued by ExchangeOtp.

Response:
documents      - List of ShareDocument entries, each containing an id and optionally the
full Document object.
expiryTime    - When the share expires.
accessLevel   - The caller's access level for this share (VIEW or VIEW_DOWNLOAD).

### Get shared content

 - [POST /api/v1/share-retrieval/retrieve-content](https://api.tenovos.com/openapi/content-intelligence/shared-content/tenovos.sharing.shareretrievalservice.retrievecontent.md): Generates download URLs for specific content items within the scope of the authenticated share.

Request:
contentIds          - List of content IDs to retrieve URLs for.
representationType  - The content representation to retrieve (e.g. "original", "preview").

Response:
content   - A RetrieveUrl.Response containing presigned download URLs and content properties
for each requested content ID.

### Get branding assets

 - [POST /api/v1/share-retrieval/retrieve-branding-content](https://api.tenovos.com/openapi/content-intelligence/shared-content/tenovos.sharing.shareretrievalservice.retrievebrandingcontent.md): Returns download URLs for the branding content (logo, background, etc.) associated with the share's site.

Request:
(no parameters) - Branding is resolved from the share's site configuration.

Response:
content   - A RetrieveUrl.Response containing presigned download URLs for the site's branding assets.

## Media Processing

The Media Processing API exposes the Transform service — a managed job queue for
converting, resizing, transcoding, and analyzing media files. Each organization has its
own isolated priority queue, ensuring processing workloads remain independent across tenants.

Workers execute in Docker containers on AWS Lambda (migrating to Spot Fargate) and
support a wide range of operations:

| Operation | Examples |
|---|---|
| **Image processing** | Resize, crop, format conversion (JPEG, PNG, WebP, AVIF), resolution scaling, thumbnail generation |
| **Video transcoding** | Format conversion, bitrate adjustment, preview clip generation |
| **Document conversion** | Office/PDF to image preview, page extraction |
| **AI enrichment** | Image hash generation, visual feature extraction, content classification, captioning (via AWS Bedrock) |

**Job operations:**
- `submit` — enqueue a new transform job, specifying the input content reference,
  operation type, and output parameters; returns a job ID for status tracking
- `status` — poll the current state of a job (`queued`, `running`, `completed`, `failed`)
  and retrieve the output content location when complete
- `cancel` — remove a queued job before execution begins; jobs already running cannot
  be cancelled mid-execution


### Submit transform job

 - [POST /api/v1/transform/submit](https://api.tenovos.com/openapi/content-intelligence/media-processing/tenovos.transform.transformservice.submit.md): Submits one or more media transformation jobs for asynchronous processing.

Request:
jobs   - List of Job definitions to submit. Each Job includes:
contentSource   - The input media, specified as either a url or a contentId.
name             - Human-readable name for the job.
tasks            - Ordered list of Task operations to execute. Each Task specifies:
inputContentLabel  - Optional label to chain output from a prior task as input.
outputContentLabel - Optional label to reference this task's output in later tasks.
details              - Specifies the operation to perform. One of:
Delivery         - Defines where to store the transformed output (platform content storage or an external S3 location). Include one Delivery task as the final step of every job.
ImageTransform   - Resize, crop, change format (JPEG, PNG, WebP, AVIF), or convert the color space of an image.
VideoTranscoding - Transcode video to a different codec, bitrate, or resolution. Optionally generate a poster image, extract a transcription, or produce a keyframe montage.
DocumentTransform - Extract a poster image or text content from a document (PDF, Office formats).
notification     - Optional webhook URL to notify when the job completes.
correlationId   - Optional caller-supplied ID for correlating jobs with external systems.

Response:
jobs   - List of JobStatusResponse objects, one per submitted job, each containing
the assigned job id and initial status (QUEUED or PENDING).

### Get transform status

 - [POST /api/v1/transform/status](https://api.tenovos.com/openapi/content-intelligence/media-processing/tenovos.transform.transformservice.status.md): Retrieves the current status and results of one or more transform jobs by their IDs.

Request:
ids   - List of job IDs to check status for.

Response:
jobs   - List of JobStatusResponse objects, each containing:
id             - Job ID.
status         - Current status (QUEUED, PENDING, INPROGRESS, COMPLETED_OK,
COMPLETED_ERROR, or COMPLETED_CANCELLED).
message        - Optional status or error message.
correlationId - The caller-supplied correlation ID, if provided at submission.
results        - List of output files produced by the job, each including the filename, download URL, MIME type, size, and type-specific properties (dimensions for images, duration for video, page count for documents).

### Cancel transform job

 - [POST /api/v1/transform/cancel](https://api.tenovos.com/openapi/content-intelligence/media-processing/tenovos.transform.transformservice.cancel.md): Cancels one or more in-progress or queued transform jobs.

Request:
ids   - List of job IDs to cancel.

Response:
(empty)