Execute Prompt
POST
/
v1
/
execute-prompt

Executes a deployed Prompt and returns the result.

Request
This endpoint expects an object.
inputs
list of unions
Show 3 variants
prompt_deployment_id
optional string

The ID of the Prompt Deployment. Must provide either this or prompt_deployment_name.

prompt_deployment_name
optional string

The name of the Prompt Deployment. Must provide either this or prompt_deployment_id.

release_tag
optional string

Optionally specify a release tag if you want to pin to a specific release of the Prompt Deployment

external_id
optional string
Response
This endpoint returns a union.
ERROR
Show 3 properties
OR
JSON
Show 3 properties
OR
STRING
Show 3 properties
Execute Workflow Stream
POST
/
v1
/
execute-workflow-stream

Executes a deployed Workflow and streams back its results.

Request
This endpoint expects an object.
workflow_deployment_id
optional string

The ID of the Workflow Deployment. Must provide either this or workflow_deployment_name.

workflow_deployment_name
optional string

The name of the Workflow Deployment. Must provide either this or workflow_deployment_id.

release_tag
optional string

Optionally specify a release tag if you want to pin to a specific release of the Workflow Deployment

inputs
list of unions

The list of inputs defined in the Workflow's deployment with their corresponding values.

Show 3 variants
external_id
optional string

Optionally include a unique identifier for tracking purposes.

event_types
optional list of enums

Optionally specify which events you want to receive. Defaults to only WORKFLOW events. Note that the schema of non-WORKFLOW events is unstable and should be used with caution.

Show 2 enum values
GenerateGA
POST
/
v1
/
generate

Generate a completion using a previously defined deployment.

Note: Uses a base url of https://predict.vellum.ai.

Request
This endpoint expects an object.
deployment_id
optional string

The ID of the deployment. Must provide either this or deployment_name.

deployment_name
optional string

The name of the deployment. Must provide either this or deployment_id.

requests
list of objects

The generation request to make. Bulk requests are no longer supported, this field must be an array of length 1.

Show 3 properties
options
optional object

Additional configuration that can be used to control what's included in the response.

Show property
Response
This endpoint returns an object.
results
list of objects

The results of each generation request.

Show 2 properties
Generate StreamGA
POST
/
v1
/
generate-stream

Generate a stream of completions using a previously defined deployment.

Note: Uses a base url of https://predict.vellum.ai.

Request
This endpoint expects an object.
deployment_id
optional string

The ID of the deployment. Must provide either this or deployment_name.

deployment_name
optional string

The name of the deployment. Must provide either this or deployment_id.

requests
list of objects

The generation request to make. Bulk requests are no longer supported, this field must be an array of length 1.

Show 3 properties
options
optional object

Additional configuration that can be used to control what's included in the response.

Show property
SearchGA
POST
/
v1
/
search

Perform a search against a document index.

Note: Uses a base url of https://predict.vellum.ai.

Request
This endpoint expects an object.
index_id
optional string

The ID of the index to search against. Must provide either this or index_name.

index_name
optional string

The name of the index to search against. Must provide either this or index_id.

query
string

The query to search for.

options
optional object

Configuration options for the search.

Show 4 properties
Response
This endpoint returns an object.
results
list of objects

The results of the search. Each result represents a chunk that matches the search query.

Show 4 properties
Submit Completion ActualsGA
POST
/
v1
/
submit-completion-actuals

Used to submit feedback regarding the quality of previously generated completions.

Note: Uses a base url of https://predict.vellum.ai.

Request
This endpoint expects an object.
deployment_id
optional string

The ID of the deployment. Must provide either this or deployment_name.

deployment_name
optional string

The name of the deployment. Must provide either this or deployment_id.

actuals
list of objects

Feedback regarding the quality of previously generated completions

Show 5 properties
Submit Workflow Execution ActualsGA
POST
/
v1
/
submit-workflow-execution-actuals
Used to submit feedback regarding the quality of previous workflow execution and its outputs. **Note:** Uses a base url of `https://predict.vellum.ai`.
Request
This endpoint expects an object.
actuals
list of unions

Feedback regarding the quality of an output on a previously executed workflow.

Show 3 variants
execution_id
optional string

The Vellum-generated ID of a previously executed workflow. Must provide either this or external_id.

external_id
optional string

The external ID that was originally provided by when executing the workflow, if applicable, that you'd now like to submit actuals for. Must provide either this or execution_id.

Deployments
RetrieveBeta
GET
/
v1
/
deployments
/
:id

Used to retrieve a deployment given its ID or name.

Path parameters
id
string

Either the Deployment's ID or its unique name

Response
This endpoint returns an object.
id
string
created
datetime
label
string

A human-readable label for the deployment

name
string

A name that uniquely identifies this deployment within its workspace

status
optional enum

The current status of the deployment

  • ACTIVE - Active
  • INACTIVE - Inactive
  • ARCHIVED - Archived
Show 3 enum values
environment
optional enum

The environment this deployment is used in

  • DEVELOPMENT - Development
  • STAGING - Staging
  • PRODUCTION - Production
Show 3 enum values
active_model_version_ids
list of strings
last_deployed_on
datetime
input_variables
list of objects
Show 3 properties
Document Indexes
CreateBeta
POST
/
v1
/
document-indexes

Creates a new document index.

Request
This endpoint expects an object.
label
string

A human-readable label for the document index

name
string

A name that uniquely identifies this index within its workspace

status
optional enum

The current status of the document index

  • ACTIVE - Active
  • ARCHIVED - Archived
Show 2 enum values
environment
optional enum

The environment this document index is used in

  • DEVELOPMENT - Development
  • STAGING - Staging
  • PRODUCTION - Production
Show 3 enum values
indexing_config
map from strings to any

Configuration representing how documents should be indexed

copy_documents_from_index_id
optional string

Optionally specify the id of a document index from which you'd like to copy and re-index its documents into this newly created index

Response
This endpoint returns an object.
id
string
created
datetime
label
string

A human-readable label for the document index

name
string

A name that uniquely identifies this index within its workspace

status
optional enum

The current status of the document index

  • ACTIVE - Active
  • ARCHIVED - Archived
Show 2 enum values
environment
optional enum

The environment this document index is used in

  • DEVELOPMENT - Development
  • STAGING - Staging
  • PRODUCTION - Production
Show 3 enum values
indexing_config
map from strings to any

Configuration representing how documents should be indexed

Document Indexes
RetrieveBeta
GET
/
v1
/
document-indexes
/
:id

Used to retrieve a Document Index given its ID or name.

Path parameters
id
string

Either the Document Index's ID or its unique name

Response
This endpoint returns an object.
id
string
created
datetime
label
string

A human-readable label for the document index

name
string

A name that uniquely identifies this index within its workspace

status
optional enum

The current status of the document index

  • ACTIVE - Active
  • ARCHIVED - Archived
Show 2 enum values
environment
optional enum

The environment this document index is used in

  • DEVELOPMENT - Development
  • STAGING - Staging
  • PRODUCTION - Production
Show 3 enum values
indexing_config
map from strings to any

Configuration representing how documents should be indexed

Documents
ListGA
GET
/
v1
/
documents

Used to list documents. Optionally filter on supported fields.

Query parameters
document_index_id
optional string

Filter down to only those documents that are included in the specified index. You may provide either the Vellum-generated ID or the unique name of the index specified upon initial creation.

limit
optional integer

Number of results to return per page.

offset
optional integer

The initial index from which to return the results.

ordering
optional string

Which field to use when ordering the results.

Response
This endpoint returns an object.
count
optional integer
next
optional string
previous
optional string
results
optional list of objects
Show 10 properties
Documents
Destroy
DEL
/
v1
/
documents
/
:id
Path parameters
id
string

A UUID string identifying this document.

Documents
Partial UpdateBeta
PATCH
/
v1
/
documents
/
:id

Update a Document, keying off of its Vellum-generated ID. Particularly useful for updating its metadata.

Path parameters
id
string

A UUID string identifying this document.

Request
This endpoint expects an object.
label
optional string

A human-readable label for the document. Defaults to the originally uploaded file's file name.

status
optional "ACTIVE"

The current status of the document

  • ACTIVE - Active
metadata
optional map from strings to any

A JSON object containing any metadata associated with the document that you'd like to filter upon later.

Response
This endpoint returns an object.
id
string
external_id
optional string

The unique id of this document as it exists in the user's system.

last_uploaded_at
datetime
label
string

A human-readable label for the document. Defaults to the originally uploaded file's file name.

processing_state
optional enum

The current processing state of the document

  • QUEUED - Queued
  • PROCESSING - Processing
  • PROCESSED - Processed
  • FAILED - Failed
Show 4 enum values
status
optional "ACTIVE"

The current status of the document

  • ACTIVE - Active
original_file_url
optional string
processed_file_url
optional string
document_to_document_indexes
list of objects
Show 3 properties
metadata
optional map from strings to any

A previously supplied JSON object containing metadata that can be filtered on when searching.

Documents
UploadGA
POST
/
v1
/
upload-document

Upload a document to be indexed and used for search.

Note: Uses a base url of https://documents.vellum.ai.

Request
This endpoint expects a file.
Response
This endpoint returns an object.
document_id
string

The ID of the newly created document.

Model Versions
RetrieveBeta
GET
/
v1
/
model-versions
/
:id

Used to retrieve a model version given its ID.

Path parameters
id
string

A UUID string identifying this model version.

Response
This endpoint returns an object.
id
string

Vellum-generated ID that uniquely identifies this model version.

created
datetime

Timestamp of when this model version was created.

label
string

Human-friendly name for this model version.

provider
enum

Which LLM provider this model version is associated with.

  • ANTHROPIC - Anthropic
  • AWS_BEDROCK - AWS Bedrock
  • AZURE_OPENAI - Azure OpenAI
  • COHERE - Cohere
  • GOOGLE - Google
  • HOSTED - Hosted
  • MOSAICML - MosaicML
  • OPENAI - OpenAI
  • HUGGINGFACE - HuggingFace
  • MYSTIC - Mystic
  • PYQ - Pyq
  • REPLICATE - Replicate
Show 12 enum values
external_id
string

The unique id of this model version as it exists in the above provider's system.

build_config
object

Configuration used to build this model version.

Show 3 properties
exec_config
object

Configuration used to execute this model version.

Show 5 properties
status
optional enum
Show 4 enum values
Registered Prompts
Register PromptBeta
POST
/
v1
/
registered-prompts
/
register

Registers a prompt within Vellum and creates associated Vellum entities. Intended to be used by integration partners, not directly by Vellum users.

Under the hood, this endpoint creates a new sandbox, a new model version, and a new deployment.

Request
This endpoint expects an object.
label
string

A human-friendly label for corresponding entities created in Vellum.

name
string

A uniquely-identifying name for corresponding entities created in Vellum.

prompt
object

Information about how to execute the prompt template.

Show 2 properties
provider
optional enum

The initial LLM provider to use for this prompt

  • ANTHROPIC - Anthropic
  • AWS_BEDROCK - AWS Bedrock
  • AZURE_OPENAI - Azure OpenAI
  • COHERE - Cohere
  • GOOGLE - Google
  • HOSTED - Hosted
  • MOSAICML - MosaicML
  • OPENAI - OpenAI
  • HUGGINGFACE - HuggingFace
  • MYSTIC - Mystic
  • PYQ - Pyq
  • REPLICATE - Replicate
Show 12 enum values
model
string

The initial model to use for this prompt

parameters
object

The initial model parameters to use for this prompt

Show 8 properties
meta
optional map from strings to any

Optionally include additional metadata to store along with the prompt.

Response
This endpoint returns an object.
prompt
object

Information about the generated prompt

Show 2 properties
sandbox_snapshot
object

Information about the generated sandbox snapshot

Show property
sandbox
object

Information about the generated sandbox

Show 2 properties
model_version
object

Information about the generated model version

Show 2 properties
prompt_version_id
string

The ID of the generated prompt version

deployment
object

Information about the generated deployment

Show 3 properties
Sandboxes
Upsert Sandbox ScenarioBeta
POST
/
v1
/
sandboxes
/
:id
/
scenarios

Upserts a new scenario for a sandbox, keying off of the optionally provided scenario id.

If an id is provided and has a match, the scenario will be updated. If no id is provided or no match is found, a new scenario will be appended to the end.

Note that a full replacement of the scenario is performed, so any fields not provided will be removed or overwritten with default values.

Path parameters
id
string

A UUID string identifying this sandbox.

Request
This endpoint expects an object.
label
optional string
inputs
list of objects

The inputs for the scenario

Show 4 properties
scenario_id
optional string

The id of the scenario to update. If none is provided, an id will be generated and a new scenario will be appended.

metric_input_params
optional object
Show property
Response
This endpoint returns an object.
label
optional string
inputs
list of objects

The inputs for the scenario

Show 4 properties
id
string

The id of the scenario

metric_input_params
object
Show property
Sandboxes
Delete Sandbox ScenarioBeta
DEL
/
v1
/
sandboxes
/
:id
/
scenarios
/
:scenario_id

Deletes an existing scenario from a sandbox, keying off of the provided scenario id.

Path parameters
id
string

A UUID string identifying this sandbox.

scenario_id
string

An id identifying the scenario that you'd like to delete

Test Suites
Upsert Test Suite Test CaseBeta
POST
/
v1
/
test-suites
/
:id
/
test-cases

Upserts a new test case for a test suite, keying off of the optionally provided test case id.

If an id is provided and has a match, the test case will be updated. If no id is provided or no match is found, a new test case will be appended to the end.

Note that a full replacement of the test case is performed, so any fields not provided will be removed or overwritten with default values.

Path parameters
id
string

A UUID string identifying this test suite.

Request
This endpoint expects an object.
id
optional string
label
optional string
input_values
list of unions
Show 6 variants
evaluation_values
list of unions
Show 6 variants
Response
This endpoint returns an object.
id
optional string
label
optional string
input_values
list of unions
Show 6 variants
evaluation_values
list of unions
Show 6 variants
Test Suites
Delete Test Suite Test CaseBeta
DEL
/
v1
/
test-suites
/
:id
/
test-cases
/
:test_case_id

Deletes an existing test case for a test suite, keying off of the test case id.

Path parameters
id
string

A UUID string identifying this test suite.

test_case_id
string

An id identifying the test case that you'd like to delete

Getting started
Generate