Content Objects

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

Upload URL

Endpoint: /objects/upload-url

Method: POST

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 -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/upload-url \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name": "my-file.pdf",
    "mime_type": "application/pdf"
}'

Download URL

Endpoint: /objects/download-url

Method: POST

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 -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/download-url \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "file": "gs://<YOUR_BUCKET>/<OBJECT_ID>"
}'

Create

Endpoint: /objects

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
id	`string`	An optional existing object ID to be replaced by the new one.
name	`string`	(Required) 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 -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "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

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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID> \\
  -H '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
}

Code Example

Retrieve Object

curl -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID> \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update

Endpoint: /objects/:objectId

Method: PUT

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

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 -X PUT \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID> \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "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

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

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

Example Request

curl -X DELETE \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID> \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "id": "<OBJECT_ID>"
}

Code Example

Delete Object

curl -X DELETE \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID> \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List

Endpoint: /objects

Method: GET

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 -X GET \\
  'https://zeno-server-production.api.vertesia.io/api/v1/objects?limit=10&offset=0' \\
  -H '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 -X GET \\
  'https://zeno-server-production.api.vertesia.io/api/v1/objects?limit=10&offset=0' \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Search

Endpoint: /objects/search

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
query	`ComplexSearchQuery`	(Required) The search query.
limit	`number`	The maximum number of objects to return.
offset	`number`	The number of objects to skip.

Example Request

{
  "query": {
    "name": "My File",
    "vector": {
      "objectId": "<OBJECT_ID>",
      "type": "text"
    }
  },
  "limit": 10,
  "offset": 0
}

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.987654321
  }
]

Code Example

Search Objects

curl -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/search \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "query": {
    "name": "My File",
    "vector": {
      "objectId": "<OBJECT_ID>",
      "type": "text"
    }
  },
  "limit": 10,
  "offset": 0
}'

Find

Endpoint: /objects/find

Method: POST

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 -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/find \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "query": {
        "name": "My File"
    },
    "limit": 10,
    "select": "name description"
}'

Export Properties

Endpoint: /objects/export

Method: POST

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 -X POST \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/export \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "objectIds": [
        "<OBJECT_ID_1>",
        "<OBJECT_ID_2>"
    ],
    "type": "CSV",
    "layout": "<TYPE_LAYOUT_ID>"
}'

Get Text

Endpoint: /objects/:objectId/text

Method: GET

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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/text \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

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

Code Example

Get Object Text

curl -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/text \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Content Source

Endpoint: /objects/:objectId/content-source

Method: GET

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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/content-source \\
  -H '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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/content-source \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Renditions

Endpoint: /objects/:objectId/renditions

Method: GET

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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/renditions \\
  -H '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 -X GET \\
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/renditions \\
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Get Revisions

Endpoint: /objects/:objectId/revisions

Method: GET

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 -X GET \
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>/revisions \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create Revision

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

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

Endpoint: /objects/:objectId

Method: PUT

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
rev	Set to `true` to create a new revision (alternative to header)
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 -X PUT \
  'https://zeno-server-production.api.vertesia.io/api/v1/objects/<OBJECT_ID>?rev=true&label=v2.0' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "properties": {
        "title": "Updated Title",
        "version": "2.0"
    }
}'

Compare Revisions

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

Method: GET

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 -X GET \
  https://zeno-server-production.api.vertesia.io/api/v1/objects/<SOURCE_ID>/compare/<TARGET_ID> \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'