Content Objects

The /objects endpoint allows you to manage your Content Objects.

Upload URL

Endpoint: /objects/upload-url

Method: POST

Requirements: User must have content:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
name	`string`	(Required) The name of the file to upload.
id	`string`	The ID of the file to upload. If not provided, a random ID will be generated.
mime_type	`string`	The MIME type of the file to upload. If not provided, the MIME type will be inferred from the file extension.
ttl	`number`	The time-to-live (TTL) of the upload URL in seconds. If not provided, the default TTL will be used.

Example Request

{
    "name": "my-file.pdf",
    "mime_type": "application/pdf"
}

Example Response

{
    "url": "https://storage.googleapis.com/....",
    "id": "<OBJECT_ID>",
    "mime_type": "application/pdf"
}

Code Example

Get Upload URL

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects/upload-url' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "my-file.pdf",
    "mime_type": "application/pdf"
}'

Download URL

Endpoint: /objects/download-url

Method: POST

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
file	`string`	(Required) The URI of the file to download. The URI can be retrieved from the object's content.source property.

Example Request

{
    "file": "gs://<YOUR_BUCKET>/<OBJECT_ID>"
}

Example Response

{
    "url": "https://storage.googleapis.com/....?Expires=....&Signature=...."
}

Code Example

Get Download URL

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects/download-url' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "file": "gs://<YOUR_BUCKET>/<OBJECT_ID>"
}'

Create

Endpoint: /objects

Method: POST

Requirements: User must have content:write permission.

Headers

Header	Value	Description
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`	Required authentication header
`x-collection-id`	`string`	Optional collection ID
`x-processing-priority`	`normal` or `low`	Optional processing priority. Use `low` for bulk ingestion

Query Parameters

The following query parameters can be used as an alternative to the corresponding headers

Parameter	Description
collection_id	Optional collection ID
processing_priority	Optional processing priority: normal, low. Use `low` for bulk ingestion

Input Parameters

Parameter	Data Type	Description
id	`string`	An optional existing object ID to be replaced by the new one.
name	`string`	The name of the object.
description	`string`	A description of the object.
tags	`string[]`	A list of tags to associate with the object.
type	`string`	The ID of the object type.
content	`ContentSource`	The content source URL and type.
external_id	`string`	An external ID to associate with the object.
properties	`Record<string, any>`	A JSON object that describes the object.
metadata	`VideoMetadata \| AudioMetadata \| ImageMetadata \| DocumentMetadata`	Metadata about the object.
tokens	`{ count: number; encoding: string; etag: string; }`	The number of tokens in the text.
run	`string`	The ID of the interaction run that created the object.

Example Request

{
    "name": "My File",
    "description": "This is my file.",
    "type": "<OBJECT_TYPE_ID>",
    "content": {
        "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
        "type": "application/pdf",
        "name": "my-file.pdf"
    },
    "properties": {
        "title": "My File Title",
        "author": "John Doe"
    }
}

Example Response

{
  "id": "<OBJECT_ID>",
  "name": "My File",
  "description": "This is my file.",
  "tags": [],
  "updated_by": "user:<USER_ID>",
  "created_by": "user:<USER_ID>",
  "created_at": "2023-11-15T12:34:56.789Z",
  "updated_at": "2023-11-15T12:34:56.789Z",
  "root": "<OBJECT_ID>",
  "parent": "<OBJECT_ID>",
  "location": "/",
  "status": "created",
  "type": {
    "id": "<OBJECT_TYPE_ID>",
    "name": "Document"
  },
  "content": {
    "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
    "type": "application/pdf",
    "name": "my-file.pdf"
  },
  "external_id": null,
  "properties": {
    "title": "My File Title",
    "author": "John Doe"
  },
  "metadata": {
    "type": "document"
  },
  "tokens": null,
  "run": null
}

Code Example

Create Object

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-collection-id: <COLLECTION_ID>' \
  --header 'x-processing-priority: normal' \
  --data-raw '{
    "name": "My File",
    "description": "This is my file.",
    "type": "<OBJECT_TYPE_ID>",
    "content": {
        "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
        "type": "application/pdf",
        "name": "my-file.pdf"
    },
    "properties": {
        "title": "My File Title",
        "author": "John Doe"
    }
}'

Retrieve

Endpoint: /objects/:objectId

Method: GET

Requirements: User must have content:read permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to retrieve.

Query Parameters

Parameter	Description
select	A string of space separated field names. Prefix a field name with "-" to exclude it from the result.

Example Request

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
  "id": "<OBJECT_ID>",
  "name": "My File",
  "description": "This is my file.",
  "tags": [],
  "updated_by": "user:<USER_ID>",
  "created_by": "user:<USER_ID>",
  "created_at": "2023-11-15T12:34:56.789Z",
  "updated_at": "2023-11-15T12:34:56.789Z",
  "root": "<OBJECT_ID>",
  "parent": "<OBJECT_ID>",
  "location": "/",
  "status": "created",
  "type": {
    "id": "<OBJECT_TYPE_ID>",
    "name": "Document"
  },
  "content": {
    "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
    "type": "application/pdf",
    "name": "my-file.pdf"
  },
  "external_id": null,
  "properties": {
    "title": "My File Title",
    "author": "John Doe"
  },
  "metadata": {
    "type": "document"
  },
  "tokens": null,
  "run": null,
  "user_permissions": {
    "can_write": true,
    "can_delete": true
  }
}

user_permissions

The user_permissions field is computed per-request and indicates the current user's effective permissions on the object. It is included in all object responses (retrieve, create, update, find, search).

Field	Data Type	Description
can_write	`boolean`	Whether the current user can modify this object.
can_delete	`boolean`	Whether the current user can delete this object.

When the object has no security restrictions, both fields are true. When per-object security is configured, the permissions are computed based on the user's identity and project-level roles.

Code Example

Retrieve Object

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update

Update an object an optionally create a revision

Endpoint: /objects/:objectId

Method: PUT

Requirements: User must have content:write permission on the object.

Headers

Header	Value	Description
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`	Required authentication header
`x-create-revision`	`boolean`	Set to `true` to create a new revision
`x-revision-label`	`string`	Optional label for the new revision

Query Parameters

The following query parameters can be used as an alternative to the corresponding headers

Parameter	Description
create_revision	Optional set to `true` to create a new revision
revision_label	Optional label for the new revision

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to update.

Input Parameters

Parameter	Data Type	Description
name	`string`	The name of the object.
description	`string`	A description of the object.
tags	`string[]`	A list of tags to associate with the object.
type	`string`	The ID of the object type.
content	`ContentSource`	The content source URL and type.
external_id	`string`	An external ID to associate with the object.
properties	`Record<string, any>`	A JSON object that describes the object.
metadata	`VideoMetadata \| AudioMetadata \| ImageMetadata \| DocumentMetadata`	Metadata about the object.
tokens	`{ count: number; encoding: string; etag: string; }`	The number of tokens in the text.
run	`string`	The ID of the interaction run that created the object.

Example Request

{
    "name": "My Updated File",
    "description": "This is my updated file.",
    "properties": {
        "title": "My Updated File Title",
        "author": "Jane Doe"
    }
}

Example Response

{
  "id": "<OBJECT_ID>",
  "name": "My Updated File",
  "description": "This is my updated file.",
  "tags": [],
  "updated_by": "user:<USER_ID>",
  "created_by": "user:<USER_ID>",
  "created_at": "2023-11-15T12:34:56.789Z",
  "updated_at": "2023-11-15T12:34:56.789Z",
  "root": "<OBJECT_ID>",
  "parent": "<OBJECT_ID>",
  "location": "/",
  "status": "created",
  "type": {
    "id": "<OBJECT_TYPE_ID>",
    "name": "Document"
  },
  "content": {
    "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
    "type": "application/pdf",
    "name": "my-file.pdf"
  },
  "external_id": null,
  "properties": {
    "title": "My Updated File Title",
    "author": "Jane Doe"
  },
  "metadata": {
    "type": "document"
  },
  "tokens": null,
  "run": null
}

Code Example

Update Object

curl --location --request PUT \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --header 'x-create-revision: true' \
  --header 'x-revision-label: v2.0' \
  --data-raw '{
    "name": "My Updated File",
    "description": "This is my updated file.",
    "properties": {
        "title": "My Updated File Title",
        "author": "Jane Doe"
    }
}'

Delete

Endpoint: /objects/:objectId

Method: DELETE

Requirements: User must have content:delete permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to delete.

Example Request

curl --location --request DELETE \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "id": "<OBJECT_ID>"
}

Code Example

Delete Object

curl --location --request DELETE \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List

Endpoint: /objects

Method: GET

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
location	`string`	The path of the parent object.
status	`string`	The status of the object.
type	`string`	The ID of the object type.
parent	`string`	The ID of the parent object.
similarTo	`string`	The ID of an object to find similar objects.
embeddingType	`SupportedEmbeddingTypes`	The type of embedding to use for similarity search.
name	`string`	The name of the object.
limit	`number`	The maximum number of objects to return.
offset	`number`	The number of objects to skip.

Example Request

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects?limit=10&offset=0' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

[
  {
    "id": "<OBJECT_ID>",
    "name": "My File",
    "description": "This is my file.",
    "tags": [],
    "updated_by": "user:<USER_ID>",
    "created_by": "user:<USER_ID>",
    "created_at": "2023-11-15T12:34:56.789Z",
    "updated_at": "2023-11-15T12:34:56.789Z",
    "location": "/",
    "status": "created",
    "type": {
      "id": "<OBJECT_TYPE_ID>",
      "name": "Document"
    },
    "content": {
      "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
      "type": "application/pdf",
      "name": "my-file.pdf"
    },
    "external_id": null,
    "properties": {
      "title": "My File Title",
      "author": "John Doe"
    },
    "metadata": {
      "type": "document"
    },
    "tokens": null,
    "run": null,
    "parent": {
      "id": "<OBJECT_ID>",
      "name": "Undefined"
    },
    "score": 0
  }
]

Code Example

List Objects

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects?limit=10&offset=0' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Search

Endpoint: /objects/search

Method: POST

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
query	`ComplexSearchQuery`	(Required) The search query. See below for detailed field documentation.
limit	`number`	The maximum number of objects to return. Set to `0` to return only aggregation/facet results without documents.
offset	`number`	The number of objects to skip.
sort	`SortOption[]`	Sort criteria. Multiple entries enable multi-field sorting (first entry is primary). See SortOption structure below.
facets	`FacetSpec[]`	Request faceted counts for specific fields. Supported fields: `type`, `status`, `location`. When Elasticsearch indexing is enabled, any field can be used.
limit_facets	`boolean`	If true, facets are limited to the current page of results. Default is `false`.
aggs	`Record<string, object>`	Arbitrary Elasticsearch aggregation definitions (e.g. terms, avg, date_histogram). Requires Elasticsearch indexing to be enabled — returns 400 otherwise. See Aggregations section below.
select	`string`	Projection of fields to return.
all_revisions	`boolean`	Include all revisions of objects.
from_root	`string`	Filter objects from a specific root.

SortOption Structure

Field	Data Type	Description
field	`string`	(Required) Field path to sort by (e.g. `updated_at`, `status`, `properties.title`).
order	`'asc' \| 'desc'`	Sort direction. Default is `desc`.

Sorting behavior:

When Elasticsearch indexing is enabled, any keyword, numeric, or date field can be used for sorting. Text fields are not sortable.
Without Elasticsearch, only these fields are accepted: created_at, updated_at, name, status, and paths under properties.* or metadata.*. Invalid fields return a 400 error.
When no sort is specified, filter-only searches default to updated_at descending. Full-text and vector searches use relevance scoring by default.

ComplexSearchQuery Fields

The ComplexSearchQuery object supports multiple search criteria that can be combined:

Basic Object Filters

Field	Data Type	Description
id	`string`	Filter by object ID.
ids	`string[]`	Filter by multiple object IDs.
name	`string`	Filter by object name.
status	`string \| string[]`	Filter by object status.
location	`string`	Filter by object location path.
parent	`string`	Filter by parent object ID.
type	`string`	Filter by object type ID.
types	`string[]`	Filter by multiple object type IDs.

Date Range Filters

Field	Data Type	Description
createdFrom	`string`	Filter objects created after this date (ISO 8601 format).
createdTo	`string`	Filter objects created before this date (ISO 8601 format).
updatedFrom	`string`	Filter objects updated after this date (ISO 8601 format).
updatedTo	`string`	Filter objects updated before this date (ISO 8601 format).

Advanced Search

Field	Data Type	Description
full_text	`string`	Perform a full-text search across object content.
vector	`VectorSearchQuery`	Perform a vector similarity search using embeddings. See VectorSearchQuery structure below.
match	`Record<string, any>`	Match objects by custom property values.

Score Aggregation Options

Field	Data Type	Description
weights	`Record<SearchTypes, number>`	Custom weights for different search types: `text`, `image`, `properties`, `full_text`.
score_aggregation	`'rrf' \| 'rsf' \| 'smart'`	Score aggregation method: `rrf` (Reciprocal Rank Fusion), `rsf` (Reciprocal Score Fusion), or `smart` (recommended, default).
dynamic_scaling	`'on' \| 'off'`	Dynamically rescale weights when a search type is not present in results. Default is `on`. Ignored when `score_aggregation` is `smart`.

VectorSearchQuery Structure

Field	Data Type	Description
objectId	`string`	ID of an object to use its embeddings for similarity search.
values	`number[]`	Custom embedding vector values.
text	`string`	Text to generate embeddings for similarity search.
image	`string`	Image URL or path to generate embeddings for similarity search.
config	`Record<'text' \| 'image' \| 'properties', boolean>`	Enable/disable specific embedding types for the search.

Aggregations (Requires Elasticsearch Indexing)

The aggs field accepts arbitrary Elasticsearch aggregation definitions. Aggregation results are returned in the aggregations field of the response. Returns 400 if Elasticsearch indexing is not enabled for the project.

Supported aggregation types: All standard Elasticsearch aggregation types except global, scripted_metric, bucket_script, bucket_selector, and top_hits (blocked for security reasons).

Aggregation names must not collide with facet names when both aggs and facets are used together.

Set limit: 0 to perform aggregation-only requests without returning documents.

Example Request

{
  "query": {
    "name": "My File",
    "type": "<OBJECT_TYPE_ID>",
    "status": "processed",
    "createdFrom": "2023-01-01T00:00:00Z",
    "createdTo": "2023-12-31T23:59:59Z",
    "full_text": "important document",
    "vector": {
      "objectId": "<OBJECT_ID>",
      "config": {
        "text": true,
        "properties": true
      }
    },
    "weights": {
      "text": 5,
      "properties": 3,
      "full_text": 2
    },
    "score_aggregation": "smart",
    "dynamic_scaling": "on",
    "match": {
      "author": "John Doe",
      "department": "Engineering"
    }
  },
  "sort": [
    { "field": "updated_at", "order": "desc" }
  ],
  "limit": 10,
  "offset": 0
}

Example Response

{
  "results": [
    {
      "id": "<OBJECT_ID>",
      "name": "My File",
      "description": "This is my file.",
      "tags": [],
      "updated_by": "user:<USER_ID>",
      "created_by": "user:<USER_ID>",
      "created_at": "2023-11-15T12:34:56.789Z",
      "updated_at": "2023-11-15T12:34:56.789Z",
      "location": "/",
      "status": "created",
      "type": {
        "id": "<OBJECT_TYPE_ID>",
        "name": "Document"
      },
      "content": {
        "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
        "type": "application/pdf",
        "name": "my-file.pdf"
      },
      "external_id": null,
      "properties": {
        "title": "My File Title",
        "author": "John Doe"
      },
      "metadata": {
        "type": "document"
      },
      "tokens": null,
      "run": null,
      "parent": {
        "id": "<OBJECT_ID>",
        "name": "Undefined"
      },
      "score": 0.987654321
    }
  ],
  "facets": {
    "type": [{ "_id": "Document", "count": 42 }],
    "status": [{ "_id": "processed", "count": 42 }]
  }
}

Aggregation Example Response

{
  "results": [],
  "facets": {},
  "aggregations": {
    "by_status": {
      "buckets": [
        { "key": "processed", "doc_count": 42 },
        { "key": "created", "doc_count": 15 }
      ]
    },
    "avg_tokens": {
      "value": 1523.7
    }
  }
}

Code Example

Search Objects

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects/search' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "query": {
    "type": "<OBJECT_TYPE_ID>",
    "status": "processed"
  },
  "sort": [
    { "field": "updated_at", "order": "desc" }
  ],
  "limit": 10,
  "offset": 0
}'

Find

Endpoint: /objects/find

Method: POST

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
query	`Record<string, any>`	(Required) The search query.
limit	`number`	The maximum number of objects to return.
select	`string`	A string of space separated field names. Prefix a field name with "-" to exclude it from the result.

Example Request

{
    "query": {
        "name": "My File"
    },
    "limit": 10,
    "select": "name description"
}

Example Response

[
  {
    "id": "<OBJECT_ID>",
    "name": "My File",
    "description": "This is my file."
  }
]

Code Example

Find Objects

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects/find' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": {
        "name": "My File"
    },
    "limit": 10,
    "select": "name description"
}'

Export Properties

Endpoint: /objects/export

Method: POST

Requirements: User must have content:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
objectIds	`string[]`	(Required) The IDs of the objects to export.
type	`string`	(Required) The export type. Currently, only `JSON` and `CSV` are supported.
layout	`string`	The ID of the type layout to use for the export.

Example Request

{
    "objectIds": [
        "<OBJECT_ID_1>",
        "<OBJECT_ID_2>"
    ],
    "type": "CSV",
    "layout": "<TYPE_LAYOUT_ID>"
}

Example Response

{
  "type": "text/csv",
  "name": "My Project_2023-11-16T12:34:56.789Z.csv",
  "data": "id,name,description\n<OBJECT_ID_1>,My File 1,This is my file 1.\n<OBJECT_ID_2>,My File 2,This is my file 2.\n"
}

Code Example

Export Properties

curl --location --request POST \
  'https://api.vertesia.io/api/v1/objects/export' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "objectIds": [
        "<OBJECT_ID_1>",
        "<OBJECT_ID_2>"
    ],
    "type": "CSV",
    "layout": "<TYPE_LAYOUT_ID>"
}'

Get Text

Endpoint: /objects/:objectId/text

Method: GET

Requirements: User must have content:read permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to retrieve the text from.

Example Request

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/text' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "text": "This is the text content of the object."
}

Code Example

Get Object Text

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/text' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Content Source

Endpoint: /objects/:objectId/content-source

Method: GET

Requirements: User must have content:read permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to retrieve the content source from.

Example Request

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/content-source' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
    "type": "application/pdf",
    "name": "my-file.pdf",
    "etag": "...."
}

Code Example

Get Content Source

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/content-source' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Renditions

Endpoint: /objects/:objectId/renditions

Method: GET

Requirements: User must have content:read permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to retrieve the renditions from.

Example Request

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/renditions' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

[
  {
    "id": "<OBJECT_ID>",
    "name": "my-file.png",
    "description": null,
    "tags": [],
    "updated_by": "user:<USER_ID>",
    "created_by": "user:<USER_ID>",
    "created_at": "2023-11-15T12:34:56.789Z",
    "updated_at": "2023-11-15T12:34:56.789Z",
    "location": "/",
    "status": "created",
    "type": {
      "id": "<OBJECT_TYPE_ID>",
      "name": "Image"
    },
    "content": {
      "source": "gs://<YOUR_BUCKET>/<OBJECT_ID>",
      "type": "image/png",
      "name": "my-file.png"
    },
    "external_id": null,
    "properties": {},
    "metadata": {
      "type": "image"
    },
    "tokens": null,
    "run": null,
    "parent": {
      "id": "<OBJECT_ID>",
      "name": "Undefined"
    },
    "score": 0
  }
]

Code Example

Get Object Renditions

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/renditions' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Revisions

Endpoint: /objects/:objectId/revisions

Method: GET

Requirements: User must have content:read permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to get revisions for.

Example Response

[
    {
        "id": "<REVISION_ID>",
        "name": "My File",
        "created_at": "2024-04-10T12:34:56.789Z",
        "created_by": "user:123",
        "revision": {
            "label": "v1.0",
            "parent": "<PARENT_OBJECT_ID>"
        },
        "properties": {
            "version_label": "Initial version"
        }
    }
]

Code Examples

Get Object Revisions

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>/revisions' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create Revision

When updating an object, you can create a new revision by setting either:

Query parameter create_revision=true
Header x-create-revision: true

Endpoint: /objects/:objectId

Method: PUT

Requirements: User must have content:write permission on the object.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`x-create-revision`	`true` (Optional - alternative to query parameter)
`x-revision-label`	`v2.0` (Optional - specify revision label)

Path Parameters

Parameter	Description
objectId	(Required) The ID of the object to update.

Query Parameters

Parameter	Description
create_revision	Set to `true` to create a new revision (alternative to header)
revision_label	Optional label for the new revision (alternative to header)

Example Request

{
    "properties": {
        "title": "Updated Title",
        "version": "2.0"
    }
}

Example Response

{
    "id": "<NEW_REVISION_ID>",
    "name": "My File",
    "created_at": "2024-04-10T12:34:56.789Z",
    "created_by": "user:123",
    "revision": {
        "label": "v2.0",
        "parent": "<PARENT_OBJECT_ID>"
    },
    "properties": {
        "title": "Updated Title",
        "version": "2.0"
    }
}

Code Examples

Create Object Revision

curl --location --request PUT \
  'https://api.vertesia.io/api/v1/objects/<OBJECT_ID>?create_revision=true&revision_label=v2.0' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "properties": {
        "title": "Updated Title",
        "version": "2.0"
    }
}'

Compare Revisions

Endpoint: /objects/:objectId/compare/:targetId

Method: GET

Requirements: User must have content:read permission on the objects.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
objectId	(Required) The ID of the source object version.
targetId	(Required) The ID of the target object version to compare with.

Example Response

{
    "properties": {
        "added": {
            "newField": "new value"
        },
        "removed": {
            "oldField": "old value"
        },
        "modified": {
            "title": {
                "from": "Old Title",
                "to": "Updated Title"
            }
        }
    },
    "content": {
        "diff": [
            {
                "value": "Unchanged text\n",
                "count": 1
            },
            {
                "removed": true,
                "value": "Removed text\n",
                "count": 1
            },
            {
                "added": true,
                "value": "Added text\n",
                "count": 1
            }
        ]
    }
}

Code Examples

Compare Object Revisions

curl --location --request GET \
  'https://api.vertesia.io/api/v1/objects/<SOURCE_ID>/compare/<TARGET_ID>' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Bulk Create

Create multiple content objects in a single request. Uses the operations endpoint for efficient bulk insertion.

Endpoint: /operations

Method: POST

Requirements: User must have content:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
name	`string`	(Required) Must be `"create"`
ids	`string[]`	(Required) Must be an empty array `[]`
params.objects	`CreateContentObjectPayload[]`	(Required) Array of objects to create (max 10,000). Each must have `name` and `type`.
params.collection_id	`string`	Optional collection ID to add all created objects to
params.skip_workflows	`boolean`	Optional flag to skip workflow rule matching (useful for seed/import scripts)

Each object in the params.objects array supports an optional external_id field for caller-side correlation.

Example Request

{
    "name": "create",
    "ids": [],
    "params": {
        "objects": [
            {
                "name": "Document 1",
                "type": "my_type_id",
                "properties": { "key": "value1" }
            },
            {
                "name": "Document 2",
                "type": "my_type_id",
                "external_id": "ext-123",
                "properties": { "key": "value2" }
            }
        ],
        "collection_id": "optional_collection_id",
        "skip_workflows": true
    }
}

Example Response

{
    "status": "completed",
    "created": 2,
    "objects": [
        { "id": "6501a1b2c3d4e5f6a7b8c9d0" },
        { "id": "6501a1b2c3d4e5f6a7b8c9d1", "external_id": "ext-123" }
    ],
    "failed": []
}

Code Example

Bulk Create Objects

curl --location --request POST \
  'https://api.vertesia.io/api/v1/operations' \
  --header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "create",
    "ids": [],
    "params": {
        "objects": [
            { "name": "Doc 1", "type": "<TYPE_ID>", "properties": {} },
            { "name": "Doc 2", "type": "<TYPE_ID>", "properties": {} }
        ],
        "skip_workflows": true
    }
}'

Bulk Upload URLs

Get presigned upload URLs for multiple files in a single request. Useful for two-phase file-backed object creation: first get upload URLs and PUT files to cloud storage, then bulk create objects with content source references.

Endpoint: /files/bulk-upload-urls

Method: POST

Requirements: User must have content:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
files	`Array<{ name, mime_type?, id? }>`	(Required) Array of file descriptors (max 10,000). Each must have a `name`.

Example Request

{
    "files": [
        { "name": "document1.pdf", "mime_type": "application/pdf" },
        { "name": "document2.pdf" }
    ]
}

Example Response

{
    "files": [
        { "url": "https://storage.googleapis.com/...", "id": "gs://bucket/uuid1", "mime_type": "application/pdf", "path": "uuid1" },
        { "url": "https://storage.googleapis.com/...", "id": "gs://bucket/uuid2", "mime_type": "application/pdf", "path": "uuid2" }
    ]
}

Code Example

Bulk Upload URLs

import { VertesiaClient } from '@vertesia/client';

const client = new VertesiaClient({
  serverUrl: 'https://studio.vertesia.io',
  storeUrl: 'https://api.vertesia.io',
  apikey: '<YOUR_API_KEY>',
});

// Get presigned URLs for multiple files
const { files } = await client.files.bulkGetUploadUrls({
  files: [
    { name: 'doc1.pdf', mime_type: 'application/pdf' },
    { name: 'doc2.pdf', mime_type: 'application/pdf' },
  ]
});

// Upload files directly to cloud storage
await Promise.all(files.map((f, i) =>
  fetch(f.url, { method: 'PUT', body: fileContents[i], headers: { 'Content-Type': f.mime_type! } })
));

// Then bulk create objects with content source references
const result = await client.objects.bulkCreate(
  files.map((f, i) => ({
    name: `doc${i + 1}.pdf`,
    type: '<TYPE_ID>',
    content: { source: f.id, type: f.mime_type, name: `doc${i + 1}.pdf` },
  }))
);