Skip to main content
Represents the API client for interacting with the Literal service. This class handles API requests, authentication, and provides methods for various operations supported by the Literal API. To use this API, you need to initialize a LiteralClient and access the API through it: 
const literalAiClient = new LiteralClient({apiKey: process.env["LITERAL_API_KEY"]});
const api = literalAiClient.api;
Then you can use the api object to make calls to the Literal service.

​
Methods

​
getProjectId()

getProjectId(): Promise<string>
Get the project id associated with the API key. Returns Promise<string> the project id

​
sendSteps()

sendSteps(steps): Promise<any>
Sends a collection of steps to the GraphQL endpoint. This method constructs a GraphQL query using the provided steps, then executes the query. Parameters
ParameterTypeDescription
stepsStep[]An array of Step objects to be sent.
Returns
typedescription
Promise<any>The response from the GraphQL call

​
getSteps()

getSteps(variables): Promise<PaginatedResponse<Step>>
Retrieves a paginated list of steps (runs) based on the provided criteria. Parameters
ParameterTypeDescription
variablesobjectThe parameters to filter and paginate the steps.
variables.first?Maybe<number>The number of steps to retrieve after the cursor. (Optional)
variables.after?Maybe<string>The cursor to start retrieving steps after. (Optional)
variables.before?Maybe<string>The cursor to start retrieving steps before. (Optional)
variables.filters?StepsFilter[]The filters to apply on the steps retrieval. (Optional)
variables.orderBy?StepsOrderByThe order in which to retrieve the steps. (Optional)
Returns
typedescription
Promise<PaginatedResponse<Step>>A promise that resolves to a paginated response of steps

​
getStep()

getStep(id): Promise<Maybe<Step>>
Retrieves a step by its ID. This method constructs a GraphQL query to fetch a step by its unique identifier. It then executes the query and returns the step if found. Parameters
ParameterTypeDescription
idstringThe unique identifier of the step to retrieve.
Returns
typedescription
Promise<Maybe<Step>>A Promise that resolves to the step if found, or null if not found

​
deleteStep()

deleteStep(id): Promise<string>
Deletes a Step from the platform by its unique identifier. This method constructs a GraphQL mutation to delete a step by its unique identifier. It then executes the mutation and returns the ID of the deleted step. Parameters
ParameterTypeDescription
idstringThe unique identifier of the step to delete.
Returns
typedescription
Promise<string>A Promise that resolves to the ID of the deleted step

​
uploadFile()

uploadFile(params) 
uploadFile(params): Promise<object>
Uploads a file to a specified thread. This method supports uploading either through direct content or via a file path. It first signs the upload through a pre-configured endpoint and then proceeds to upload the file using the signed URL. Parameters
ParameterTypeDescription
paramsUploadFileParamsWithContentThe parameters for uploading a file, including:
Returns
typedescription
Promise<object>An object containing the objectKey of the uploaded file and the signed url, or null values if the upload fails
Throws Throws an error if neither content nor path is provided, or if the server response is invalid. uploadFile(params) 
uploadFile(params): Promise<object>
Parameters
ParameterType
paramsUploadFileParamsWithPath
Returns Promise<object>

​
createAttachment()

createAttachment(params) 
createAttachment(params): Promise<Attachment>
Uploads a file to a specified thread and creates an attachment object. If called inside a context, the attachment will be added to the current step and thread. Parameters
ParameterTypeDescription
paramsUploadFileBaseParams & object & CreateAttachmentParamsThe parameters for uploading a file, including:
Returns
typedescription
Promise<Attachment>An object containing the objectKey of the uploaded file and the signed url, or null values if the upload fails
Throws Throws an error if neither content nor path is provided, or if the server response is invalid. createAttachment(params) 
createAttachment(params): Promise<Attachment>
Parameters
ParameterType
paramsUploadFileBaseParams & object & CreateAttachmentParams
Returns Promise<Attachment>

​
getGenerations()

getGenerations(variables): Promise<PaginatedResponse<PersistedGeneration>>
Retrieves a paginated list of Generations based on the provided filters and sorting order. Parameters
ParameterTypeDescription
variablesobjectThe variables to filter and sort the Generations. It includes:
- first: The number of items to return.
- after: The cursor to fetch items after.
- before: The cursor to fetch items before.
- filters: The filters applied to the Generations.
- orderBy: The order in which the Generations are sorted.
variables.first?Maybe<number>-
variables.after?Maybe<string>-
variables.before?Maybe<string>-
variables.filters?GenerationsFilter[]-
variables.orderBy?GenerationsOrderBy-
Returns
typedescription
Promise<PaginatedResponse<PersistedGeneration>>A Promise that resolves to a PaginatedResponse<Generation> object containing the filtered and sorted Generations

​
createGeneration()

createGeneration(generation): Promise<PersistedGeneration>
Creates a new generation entity and sends it to the platform. Parameters
ParameterTypeDescription
generationGenerationThe Generation object to be created and sent to the platform.
Returns
typedescription
Promise<PersistedGeneration>A Promise resolving to the newly created Generation object

​
upsertThread()

upsertThread(options) 
upsertThread(options): Promise<CleanThreadFields>
Upserts a Thread with new information. Parameters
ParameterTypeDescription
optionsobjectThe parameters to upsert a thread.
options.threadIdstringThe unique identifier of the thread. (Required)
options.name?Maybe<string>The name of the thread. (Optional)
options.metadata?Maybe<Record<string, any>>Additional metadata for the thread as a key-value pair object. (Optional)
options.participantId?Maybe<string>The unique identifier of the participant. (Optional)
options.tags?Maybe<string[]>An array of tags associated with the thread. (Optional)
Returns
typedescription
Promise<CleanThreadFields>The upserted thread object
upsertThread(threadId, name, metadata, participantId, tags) 
upsertThread(
   threadId, 
   name?, 
   metadata?, 
   participantId?, 
tags?): Promise<CleanThreadFields>
Upserts a Thread with new information. Parameters
ParameterTypeDescription
threadIdstringThe unique identifier of the thread. (Required)
name?Maybe<string>The name of the thread. (Optional)
metadata?Maybe<Record<string, any>>Additional metadata for the thread as a key-value pair object. (Optional)
participantId?Maybe<string>The unique identifier of the participant. (Optional)
tags?Maybe<string[]>An array of tags associated with the thread. (Optional)
Returns
typedescription
Promise<CleanThreadFields>The upserted thread object
Deprecated Use one single object attribute instead of multiple parameters.

​
getThreads()

getThreads(variables): Promise<PaginatedResponse<Thread>>
Retrieves a paginated list of threads (conversations) based on the provided criteria. Parameters
ParameterTypeDescription
variablesobjectThe parameters to filter and paginate the threads.
variables.first?Maybe<number>The number of threads to retrieve after the cursor. (Optional)
variables.after?Maybe<string>The cursor to start retrieving threads after. (Optional)
variables.before?Maybe<string>The cursor to start retrieving threads before. (Optional)
variables.filters?ThreadsFilter[]The filters to apply on the threads retrieval. (Optional)
variables.orderBy?ThreadsOrderByThe order in which to retrieve the threads. (Optional)
variables.stepTypesToKeep?StepType[]-
Returns
typedescription
Promise<PaginatedResponse<Thread>>A promise that resolves to a paginated response of threads

​
getThread()

getThread(id): Promise<Maybe<Thread>>
Retrieves information from a single Thread. Parameters
ParameterTypeDescription
idstringThe unique identifier of the thread. This parameter is required.
Returns
typedescription
Promise<Maybe<Thread>>The detailed information of the specified thread

​
deleteThread()

deleteThread(id): Promise<string>
Deletes a single Thread by its unique identifier. Parameters
ParameterTypeDescription
idstringThe unique identifier of the thread to be deleted. This parameter is required.
Returns
typedescription
Promise<string>The ID of the deleted thread

​
getUsers()

getUsers(variables): Promise<PaginatedResponse<OmitUtils<User>>>
Retrieves a list of users with optional filters. Parameters
ParameterTypeDescription
variablesobjectThe parameters used to filter and paginate the user list.
variables.first?Maybe<number>Optional. The number of items to return.
variables.after?Maybe<string>Optional. The cursor after which to start fetching data.
variables.before?Maybe<string>Optional. The cursor before which to start fetching data.
variables.filters?ParticipantsFilter[]Optional. Array of filters to apply to the user query.
Returns
typedescription
Promise<PaginatedResponse<OmitUtils<User>>>A PaginatedResponse containing a list of users without utility types

​
createUser()

createUser(identifier, metadata?): Promise<User>
Creates a new user and sends it to the platform. Parameters
ParameterTypeDescription
identifierstringThe unique identifier for the user. This parameter is required.
metadata?Maybe<Record<string, any>>Optional metadata for the user. This parameter is optional.
Returns
typedescription
Promise<User>A promise that resolves with the newly created User object

​
updateUser()

updateUser(
   id, 
   identifier?, 
metadata?): Promise<User>
Updates an existing user’s details in the platform. Parameters
ParameterTypeDescription
idstringThe unique identifier of the user to update. This parameter is required.
identifier?stringA new identifier for the user. This parameter is optional.
metadata?Maybe<Record<string, any>>Additional metadata for the user. This parameter is optional.
Returns
typedescription
Promise<User>A promise that resolves with the updated User object

​
getOrCreateUser()

getOrCreateUser(identifier, metadata?): Promise<string>
Retrieves an existing user by their identifier or creates a new one if they do not exist. Parameters
ParameterTypeDescription
identifierstringThe unique identifier for the user. This parameter is required.
metadata?Maybe<Record<string, any>>Additional metadata for the user. This parameter is optional.
Returns
typedescription
Promise<string>The ID of the existing or newly created user

​
getUser()

getUser(identifier): Promise<Maybe<User>>
Retrieves a user by their unique identifier. Parameters
ParameterTypeDescription
identifierstringThe unique identifier for the user. This parameter is required.
Returns
typedescription
Promise<Maybe<User>>A Promise that resolves to a User object if found, otherwise undefined

​
deleteUser()

deleteUser(id): Promise<string>
Deletes a single user by their unique identifier. Parameters
ParameterTypeDescription
idstringThe unique identifier of the user to be deleted. This parameter is required.
Returns
typedescription
Promise<string>A Promise that resolves to the ID of the deleted user

​
getScores()

getScores(variables): Promise<PaginatedResponse<OmitUtils<Score>>>
Get all scores connected to the platform. Parameters
ParameterTypeDescription
variablesobjectThe parameters for querying scores.
variables.first?Maybe<number>Optional. The number of scores to retrieve.
variables.after?Maybe<string>Optional. The cursor after which to start fetching scores.
variables.before?Maybe<string>Optional. The cursor before which to start fetching scores.
variables.filters?ScoresFilter[]Optional. Filters to apply to the score query.
variables.orderBy?ScoresOrderByOptional. The order in which to sort the scores.
Returns
typedescription
Promise<PaginatedResponse<OmitUtils<Score>>>A Promise that resolves to a paginated response of scores, excluding certain utility fields

​
createScores()

createScores(scores): Promise<Score[]>
Creates multiple scores in the database using the provided array of scores. Each score in the array is transformed into a GraphQL mutation call. Parameters
ParameterTypeDescription
scoresScore[]An array of Score objects to be created.
Returns
typedescription
Promise<Score[]>A promise that resolves to an array of Score instances populated with the created scores’ data

​
createScore()

createScore(variables): Promise<Score>
Creates a new score in the database using the provided parameters. Parameters
ParameterTypeDescription
variablesOmitUtils<Score>The score details to be used in the creation process. This includes:
Returns
typedescription
Promise<Score>A new Score instance populated with the created score’s data

​
updateScore()

updateScore(id, updateParams): Promise<Score>
Updates an existing score in the database. Parameters
ParameterTypeDescription
idstringThe unique identifier of the score to update. (required)
updateParamsobjectThe parameters to update in the score. (required)
updateParams.comment?Maybe<string>A new or updated comment for the score. (optional)
updateParams.valuenumberThe new value to set for the score. (required)
Returns
typedescription
Promise<Score>A Score instance representing the updated score

​
deleteScore()

deleteScore(id): Promise<any>
Deletes a single score from the database. Parameters
ParameterTypeDescription
idstringThe unique identifier of the score to delete. (required)
Returns
typedescription
Promise<any>The ID of the deleted score

​
getDatasets()

getDatasets(): Promise<object[]>
List all datasets in the platform. Returns
typedescription
Promise<object[]>The names and ids of all datasets

​
createDataset()

createDataset(dataset): Promise<Dataset>
Creates a new dataset in the database. Parameters
ParameterTypeDescription
datasetobjectThe dataset details to be created.
dataset.namestringThe name of the dataset. (required)
dataset.description?Maybe<string>The description of the dataset. (optional)
dataset.metadata?Maybe<Record<string, any>>Additional metadata for the dataset as a key-value pair object. (optional)
dataset.type?DatasetTypeThe type of the dataset, defined by the DatasetType enum. (optional)
Returns
typedescription
Promise<Dataset>A new Dataset instance populated with the created dataset’s data

​
getDataset()

getDataset(variables): Promise<null | Dataset>
Retrieves a dataset based on provided ID or name. Parameters
ParameterTypeDescription
variablesobjectAn object containing optional id and name properties to specify which dataset to retrieve.
variables.id?string-
variables.name?string-
Returns
typedescription
Promise<null | Dataset>A Dataset instance populated with the retrieved dataset’s data, or null if no data is found

​
updateDataset()

updateDataset(id, dataset): Promise<Dataset>
Updates a dataset with new information. Parameters
ParameterTypeDescription
idstringThe unique identifier of the dataset to update. This parameter is required.
datasetobjectAn object containing the new dataset information.
dataset.name?Maybe<string>The new name of the dataset. (optional)
dataset.description?Maybe<string>The new description of the dataset. (optional)
dataset.metadata?Maybe<Record<string, any>>Additional metadata for the dataset as a key-value pair object. (optional)
Returns
typedescription
Promise<Dataset>A new Dataset instance populated with the updated dataset’s data

​
deleteDataset()

deleteDataset(id): Promise<Dataset>
Deletes a single dataset by its unique identifier. Parameters
ParameterTypeDescription
idstringThe unique identifier of the dataset to delete. This parameter is required.
Returns
typedescription
Promise<Dataset>A new Dataset instance populated with the deleted dataset’s data

​
createDatasetItem()

createDatasetItem(datasetId, datasetItem): Promise<DatasetItem>
Creates a new item in a dataset. Parameters
ParameterTypeDescription
datasetIdstringThe unique identifier of the dataset. This parameter is required.
datasetItemobjectThe data for the new dataset item. This parameter is required.
datasetItem.inputRecord<string, any>The input data for the dataset item. This field is required.
datasetItem.expectedOutput?Maybe<Record<string, any>>The expected output data for the dataset item. This field is optional.
datasetItem.metadata?Maybe<Record<string, any>>Additional metadata for the dataset item. This field is optional.
Returns
typedescription
Promise<DatasetItem>A new DatasetItem instance populated with the created dataset item’s data

​
getDatasetItem()

getDatasetItem(id): Promise<DatasetItem>
Retrieves a single item from a dataset by its unique identifier. Parameters
ParameterTypeDescription
idstringThe unique identifier of the dataset item. This parameter is required.
Returns
typedescription
Promise<DatasetItem>A DatasetItem instance populated with the retrieved dataset item’s data

​
deleteDatasetItem()

deleteDatasetItem(id): Promise<DatasetItem>
Deletes a single item from a dataset by its unique identifier. Parameters
ParameterTypeDescription
idstringThe unique identifier of the dataset item to be deleted. This parameter is required.
Returns
typedescription
Promise<DatasetItem>A DatasetItem instance populated with the data of the deleted dataset item

​
addStepToDataset()

addStepToDataset(
   datasetId, 
   stepId, 
metadata?): Promise<DatasetItem>
Adds a single step item to a dataset. Parameters
ParameterTypeDescription
datasetIdstringThe unique identifier of the dataset. This parameter is required.
stepIdstringThe unique identifier of the step to be added. This parameter is required.
metadata?Maybe<Record<string, unknown>>Additional metadata for the step as a JSON object. This parameter is optional.
Returns
typedescription
Promise<DatasetItem>A DatasetItem instance populated with the data of the newly added step

​
addGenerationToDataset()

addGenerationToDataset(
   datasetId, 
   generationId, 
metadata?): Promise<DatasetItem>
Adds a generation item to a dataset. Parameters
ParameterTypeDescription
datasetIdstringThe unique identifier of the dataset. This parameter is required.
generationIdstringThe unique identifier of the generation to be added. This parameter is required.
metadata?Maybe<Record<string, unknown>>Additional metadata for the generation as a JSON object. This parameter is optional.
Returns
typedescription
Promise<DatasetItem>A DatasetItem instance populated with the data of the newly added generation

​
addGenerationsToDataset()

addGenerationsToDataset(datasetId, generationIds): Promise<DatasetItem[]>
Adds multiple generation items to a dataset. Parameters
ParameterTypeDescription
datasetIdstringThe unique identifier of the dataset. This parameter is required.
generationIdsstring[]An array of unique identifiers for the generations to be added. This parameter is required.
Returns Promise<DatasetItem[]> An array of DatasetItem instances populated with the data of the newly added generations

​
createExperiment()

createExperiment(datasetExperiment): Promise<DatasetExperiment>
Creates a new dataset experiment. Parameters
ParameterTypeDescription
datasetExperimentobject
datasetExperiment.namestringThe name of the dataset experiment.
datasetExperiment.datasetId?stringThe dataset ID to associate with the experiment.
datasetExperiment.promptId?stringThe prompt ID to associate with the experiment.
datasetExperiment.params?Record<string, any> | Record<string, any>[]The parameters for the experiment as a key-value pair object or an array of the same.
Returns
typedescription
Promise<DatasetExperiment>The newly created dataset experiment object

​
createExperimentItem()

createExperimentItem(parameters): Promise<DatasetExperimentItem>
Creates a new dataset experiment item. Parameters
ParameterTypeDescription
parametersDatasetExperimentItem
Returns
typedescription
Promise<DatasetExperimentItem>The dataset experiment object

​
createPromptLineage()

createPromptLineage(name, description?): Promise<any>
Create a new prompt lineage. Parameters
ParameterTypeDescription
namestringThe name of the prompt lineage. This parameter is required.
description?stringA description for the prompt lineage. This parameter is optional.
Returns
typedescription
Promise<any>The newly created prompt lineage object, or null if creation failed

​
createPrompt()

createPrompt(
   name, 
   templateMessages, 
settings?): Promise<Prompt>
Parameters
ParameterType
namestring
templateMessagesIGenerationMessage[]
settings?Maybe<Record<string, any>>
Returns Promise<Prompt> Deprecated Please use getOrCreatePrompt instead.

​
getOrCreatePrompt()

getOrCreatePrompt(
   name, 
   templateMessages, 
   settings?, 
tools?): Promise<Prompt>
A Prompt is fully defined by its name, template_messages, settings and tools. If a prompt already exists for the given arguments, it is returned. Otherwise, a new prompt is created. Parameters
ParameterTypeDescription
namestringThe name of the prompt to retrieve or create.
templateMessagesIGenerationMessage[]A list of template messages for the prompt.
settings?Maybe<Record<string, any>>Optional settings for the prompt.
tools?Maybe<Record<string, any>>Optional tools for the prompt.
Returns
typedescription
Promise<Prompt>The prompt that was retrieved or created

​
getPromptById()

getPromptById(id): Promise<null | Prompt>
Retrieves a prompt by its id. Parameters
ParameterTypeDescription
idstringID of the prompt to retrieve.
Returns
typedescription
Promise<null | Prompt>The prompt with given ID

​
getPrompt()

getPrompt(name, version?): Promise<null | Prompt>
Retrieves a prompt by its name and optionally by its version. Parameters
ParameterTypeDescription
namestringThe name of the prompt to retrieve.
version?numberThe version number of the prompt (optional).
Returns
typedescription
Promise<null | Prompt>An instance of Prompt containing the prompt data, or null if not found

​
getPromptAbTesting()

getPromptAbTesting(name): Promise<null | IPromptRollout[]>
Retrieves a prompt A/B testing rollout by its name. Parameters
ParameterTypeDescription
namestringThe name of the prompt to retrieve.
Returns
typedescription
Promise<null | IPromptRollout[]>A list of prompt rollout versions

​
updatePromptAbTesting()

updatePromptAbTesting(name, rollouts): Promise<any>
Update a prompt A/B testing rollout by its name. Parameters
ParameterTypeDescription
namestringThe name of the prompt to retrieve.
rolloutsIPromptRollout[]A list of prompt rollout versions.
Returns
typedescription
Promise<any>A list of prompt rollout versions