Prompt Templates

The /prompts endpoint allows you to manage your Prompt Templates.

Retrieve a Prompt Template

Endpoint: /prompts/<PT_ID>

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to retrieve.

Example Request

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

Example Response

{
    "id": "<PT_ID>",
    "name": "My Prompt Template",
    "role": "user",
    "status": "draft",
    "version": 1,
    "description": "This is my prompt template.",
    "content_type": "text",
    "content": "This is the content of my prompt template.",
    "test_data": {
        "foo": "bar"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "project": "<PROJECT_ID>",
    "tags": [
        "tag1",
        "tag2"
    ],
    "created_by": "user:64684c71c12e5a2a3a123456",
    "updated_by": "user:64684c71c12e5a2a3a123456",
    "created_at": "2023-05-24T14:24:01.729Z",
    "updated_at": "2023-05-24T14:24:01.729Z"
}

Code Examples

Retrieve a Prompt Template

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

List Prompt Templates

Requirements: User must have interaction:read permission.

Endpoint: /prompts

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Prompt Template to filter by.
`role`	`string`	The role of the Prompt Template to filter by.

Example Request

curl --location --request GET 'https://api.vertesia.io/api/v1/prompts?name=My%20Prompt%20Template&role=user' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

[
    {
        "id": "<PT_ID>",
        "name": "My Prompt Template",
        "description": "This is my prompt template.",
        "role": "user",
        "status": "draft",
        "created_at": "2023-05-24T14:24:01.729Z",
        "updated_at": "2023-05-24T14:24:01.729Z",
        "interactions": [
            {
                "id": "646e644ec12e5a2a3a875b8c",
                "name": "My Interaction",
                "versions": [
                    {
                        "versions": 1
                    }
                ]
            }
        ],
        "version": 1
    }
]

Code Examples

List Prompt Templates

curl --location --request GET 'https://api.vertesia.io/api/v1/prompts?name=My%20Prompt%20Template&role=user' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create a Prompt Template

Endpoint: /prompts

Method: POST

Requirements: User must have interaction:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
`name`	`string`	(Required) The name of the Prompt Template.
`role`	`string`	(Required) The role of the Prompt Template.
`description`	`string`	The description of the Prompt Template.
`content_type`	`string`	(Required) The content type of the Prompt Template.
`content`	`string`	(Required) The content of the Prompt Template.
`test_data`	`object`	The test data for the Prompt Template.
`inputSchema`	`object`	The input schema for the Prompt Template.
`tags`	`string[]`	The tags for the Prompt Template.

Example Request

{
    "name": "My Prompt Template",
    "role": "user",
    "description": "This is my prompt template.",
    "content_type": "text",
    "content": "This is the content of my prompt template.",
    "test_data": {
        "foo": "bar"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "tags": [
        "tag1",
        "tag2"
    ]
}

Example Response

{
    "id": "<PT_ID>",
    "name": "My Prompt Template",
    "role": "user",
    "status": "draft",
    "version": 1,
    "description": "This is my prompt template.",
    "content_type": "text",
    "content": "This is the content of my prompt template.",
    "test_data": {
        "foo": "bar"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "project": "<PROJECT_ID>",
    "tags": [
        "tag1",
        "tag2"
    ],
    "created_by": "user:64684c71c12e5a2a3a123456",
    "updated_by": "user:64684c71c12e5a2a3a123456",
    "created_at": "2023-05-24T14:24:01.729Z",
    "updated_at": "2023-05-24T14:24:01.729Z"
}

Code Examples

Create a Prompt Template

curl --location --request POST 'https://api.vertesia.io/api/v1/prompts' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My Prompt Template",
    "role": "user",
    "description": "This is my prompt template.",
    "content_type": "text",
    "content": "This is the content of my prompt template.",
    "test_data": {
        "foo": "bar"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "tags": [
        "tag1",
        "tag2"
    ]
}'

Update a Prompt Template

Endpoint: /prompts/<PT_ID>

Method: PUT

Requirements: User must have interaction:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to update.

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Prompt Template.
`role`	`string`	The role of the Prompt Template.
`description`	`string`	The description of the Prompt Template.
`content_type`	`string`	The content type of the Prompt Template.
`content`	`string`	The content of the Prompt Template.
`test_data`	`object`	The test data for the Prompt Template.
`inputSchema`	`object`	The input schema for the Prompt Template.
`tags`	`string[]`	The tags for the Prompt Template.

Example Request

{
    "name": "My Updated Prompt Template",
    "role": "assistant",
    "description": "This is my updated prompt template.",
    "content_type": "text",
    "content": "This is the updated content of my prompt template.",
    "test_data": {
        "foo": "baz"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "tags": [
        "tag3",
        "tag4"
    ]
}

Example Response

{
    "id": "<PT_ID>",
    "name": "My Updated Prompt Template",
    "role": "assistant",
    "status": "draft",
    "version": 2,
    "description": "This is my updated prompt template.",
    "content_type": "text",
    "content": "This is the updated content of my prompt template.",
    "test_data": {
        "foo": "baz"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "project": "<PROJECT_ID>",
    "tags": [
        "tag3",
        "tag4"
    ],
    "created_by": "user:64684c71c12e5a2a3a123456",
    "updated_by": "user:64684c71c12e5a2a3a123456",
    "created_at": "2023-05-24T14:24:01.729Z",
    "updated_at": "2023-05-24T14:28:17.341Z"
}

Code Examples

Update a Prompt Template

curl --location --request PUT 'https://api.vertesia.io/api/v1/prompts/<PT_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My Updated Prompt Template",
    "role": "assistant",
    "description": "This is my updated prompt template.",
    "content_type": "text",
    "content": "This is the updated content of my prompt template.",
    "test_data": {
        "foo": "baz"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "tags": [
        "tag3",
        "tag4"
    ]
}'

Delete a Prompt Template

Endpoint: /prompts/<PT_ID>

Method: DELETE

Requirements: User must have interaction:delete permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to delete.

Example Request

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

Example Response

{
    "id": "<PT_ID>"
}

Code Examples

Delete a Prompt Template

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

Fork a Prompt Template

Endpoint: /prompts/<PT_ID>/fork

Method: POST

Requirements: User must have interaction:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to fork.

Input Parameters

Parameter	Data Type	Description
`keepTags`	`boolean`	Whether to keep the tags from the original Prompt Template.
`targetProject`	`string`	The ID of the project to fork the Prompt Template to.

Example Request

{
    "keepTags": true,
    "targetProject": "<PROJECT_ID>"
}

Example Response

{
    "id": "<PT_ID>",
    "name": "My Prompt Template (fork)",
    "role": "user",
    "status": "draft",
    "version": 1,
    "description": "This is my prompt template.",
    "content_type": "text",
    "content": "This is the content of my prompt template.",
    "test_data": {
        "foo": "bar"
    },
    "inputSchema": {
        "type": "object",
        "properties": {
            "foo": {
                "type": "string"
            }
        },
        "required": [
            "foo"
        ]
    },
    "project": "<PROJECT_ID>",
    "tags": [
        "tag1",
        "tag2"
    ],
    "parent": "<PT_ID>",
    "created_by": "user:64684c71c12e5a2a3a123456",
    "updated_by": "user:64684c71c12e5a2a3a123456",
    "created_at": "2023-05-24T14:34:16.908Z",
    "updated_at": "2023-05-24T14:34:16.908Z"
}

Code Examples

Fork a Prompt Template

curl --location --request POST 'https://api.vertesia.io/api/v1/prompts/<PT_ID>/fork' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "keepTags": true,
    "targetProject": "<PROJECT_ID>"
}'

List Prompt Template Versions

Endpoint: /prompts/<PT_ID>/versions

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to list versions for.

Example Request

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

Example Response

[
    {
        "id": "<PT_ID>",
        "name": "My Prompt Template",
        "description": "This is my prompt template.",
        "status": "published",
        "version": 1,
        "latest": false,
        "created_at": "2023-05-24T14:24:01.730Z",
        "updated_at": "2023-05-24T14:24:01.730Z"
    }
]

Code Examples

List Prompt Template Versions

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

List Prompt Template Forks

Endpoint: /prompts/<PT_ID>/forks

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to list forks for.

Example Request

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

Example Response

[
    {
        "name": "My Prompt Template (fork)",
        "description": "This is my prompt template.",
        "status": "draft",
        "version": 1,
        "latest": true,
        "created_at": "2023-05-24T14:34:16.908Z",
        "updated_at": "2023-05-24T14:34:16.908Z",
        "id": "<PT_ID>"
    }
]

Code Examples

List Prompt Template Forks

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

Endpoint: /prompts/facets

Method: POST

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Input Parameters

Parameter	Data Type	Description
`facets`	`FacetSpec[]`	(Required) The facets to compute.
`query`	`PromptSearchQuery`	The query to filter the facets by.

Example Request

{
    "facets": [
        {
            "name": "role",
            "field": "role"
        }
    ],
    "query": {
        "name": "My Prompt Template"
    }
}

Example Response

{
    "role": [
        {
            "_id": "user",
            "count": 1
        }
    ],
    "total": 1
}

Code Examples

Compute Prompt Template Facets

curl --location --request POST 'https://api.vertesia.io/api/v1/prompts/facets' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "facets": [
        {
            "name": "role",
            "field": "role"
        }
    ],
    "query": {
        "name": "My Prompt Template"
    }
}'

List Prompt Template Interactions

Endpoint: /prompts/<PT_ID>/interactions

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`PT_ID`	`string`	(Required) The ID of the Prompt Template to list interactions for.

Example Request

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

Example Response

{
    "prompt": "<PT_ID>",
    "interactions": [
        {
            "id": "<INTERACTION_ID>",
            "name": "My Interaction",
            "versions": [
                {
                    "versions": 1
                }
            ]
        }
    ]
}

Code Examples

List Prompt Template Interactions

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