cURL
curl --request POST \
--url https://api.langtail.com/{workspace}/{project}/{assistant}/{environment} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '
{
"threadId": "thread_123",
"variables": {
"variableName": "Your Value"
},
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": false,
"model": "<string>",
"max_tokens": 123,
"temperature": 123,
"top_p": 123,
"presence_penalty": 123,
"frequency_penalty": 123,
"template": [
{
"content": "<string>",
"name": "<string>",
"tool_calls": [
{
"id": "<string>",
"type": "function",
"function": {
"name": "<string>",
"arguments": "<string>"
}
}
],
"tool_choice": "auto",
"tool_call_id": "<string>"
}
],
"user": "user_123",
"doNotRecord": false,
"metadata": {
"my_identifier": "my-custom-ID"
},
"seed": 123
}
'import requests
url = "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}"
payload = {
"threadId": "thread_123",
"variables": { "variableName": "Your Value" },
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": False,
"model": "<string>",
"max_tokens": 123,
"temperature": 123,
"top_p": 123,
"presence_penalty": 123,
"frequency_penalty": 123,
"template": [
{
"content": "<string>",
"name": "<string>",
"tool_calls": [
{
"id": "<string>",
"type": "function",
"function": {
"name": "<string>",
"arguments": "<string>"
}
}
],
"tool_choice": "auto",
"tool_call_id": "<string>"
}
],
"user": "user_123",
"doNotRecord": False,
"metadata": { "my_identifier": "my-custom-ID" },
"seed": 123
}
headers = {
"X-API-Key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
threadId: 'thread_123',
variables: {variableName: 'Your Value'},
messages: [{role: 'user', content: 'Hello'}],
stream: false,
model: '<string>',
max_tokens: 123,
temperature: 123,
top_p: 123,
presence_penalty: 123,
frequency_penalty: 123,
template: [
{
content: '<string>',
name: '<string>',
tool_calls: [
{
id: '<string>',
type: 'function',
function: {name: '<string>', arguments: '<string>'}
}
],
tool_choice: 'auto',
tool_call_id: '<string>'
}
],
user: 'user_123',
doNotRecord: false,
metadata: {my_identifier: 'my-custom-ID'},
seed: 123
})
};
fetch('https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'threadId' => 'thread_123',
'variables' => [
'variableName' => 'Your Value'
],
'messages' => [
[
'role' => 'user',
'content' => 'Hello'
]
],
'stream' => false,
'model' => '<string>',
'max_tokens' => 123,
'temperature' => 123,
'top_p' => 123,
'presence_penalty' => 123,
'frequency_penalty' => 123,
'template' => [
[
'content' => '<string>',
'name' => '<string>',
'tool_calls' => [
[
'id' => '<string>',
'type' => 'function',
'function' => [
'name' => '<string>',
'arguments' => '<string>'
]
]
],
'tool_choice' => 'auto',
'tool_call_id' => '<string>'
]
],
'user' => 'user_123',
'doNotRecord' => false,
'metadata' => [
'my_identifier' => 'my-custom-ID'
],
'seed' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}"
payload := strings.NewReader("{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}")
.header("X-API-Key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"created": 123,
"model": "<string>",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'm sorry, but I'm not able to fulfill this request."
},
"finish_reason": "stop"
}
]
}{
"error": "Invalid request body",
"issues": [
{
"code": "unrecognized_keys",
"keys": [
"unknown_variable"
],
"path": [
"variables"
],
"message": "Unrecognized key(s) in object: 'unknown_variable'"
}
]
}Assistants
Invoke Assistant
Get completion for a stored assistant. This endpoint invokes the assistant and returns its response. It uses chat completions on the backend and maintains OpenAI-compatible format. Assistants are stateful AI agents that can leverage various model providers and tools, access persistent conversation threads, and execute multiple tools in parallel.
POST
/
{workspace}
/
{project}
/
{assistant}
/
{environment}
cURL
curl --request POST \
--url https://api.langtail.com/{workspace}/{project}/{assistant}/{environment} \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <x-api-key>' \
--data '
{
"threadId": "thread_123",
"variables": {
"variableName": "Your Value"
},
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": false,
"model": "<string>",
"max_tokens": 123,
"temperature": 123,
"top_p": 123,
"presence_penalty": 123,
"frequency_penalty": 123,
"template": [
{
"content": "<string>",
"name": "<string>",
"tool_calls": [
{
"id": "<string>",
"type": "function",
"function": {
"name": "<string>",
"arguments": "<string>"
}
}
],
"tool_choice": "auto",
"tool_call_id": "<string>"
}
],
"user": "user_123",
"doNotRecord": false,
"metadata": {
"my_identifier": "my-custom-ID"
},
"seed": 123
}
'import requests
url = "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}"
payload = {
"threadId": "thread_123",
"variables": { "variableName": "Your Value" },
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": False,
"model": "<string>",
"max_tokens": 123,
"temperature": 123,
"top_p": 123,
"presence_penalty": 123,
"frequency_penalty": 123,
"template": [
{
"content": "<string>",
"name": "<string>",
"tool_calls": [
{
"id": "<string>",
"type": "function",
"function": {
"name": "<string>",
"arguments": "<string>"
}
}
],
"tool_choice": "auto",
"tool_call_id": "<string>"
}
],
"user": "user_123",
"doNotRecord": False,
"metadata": { "my_identifier": "my-custom-ID" },
"seed": 123
}
headers = {
"X-API-Key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
threadId: 'thread_123',
variables: {variableName: 'Your Value'},
messages: [{role: 'user', content: 'Hello'}],
stream: false,
model: '<string>',
max_tokens: 123,
temperature: 123,
top_p: 123,
presence_penalty: 123,
frequency_penalty: 123,
template: [
{
content: '<string>',
name: '<string>',
tool_calls: [
{
id: '<string>',
type: 'function',
function: {name: '<string>', arguments: '<string>'}
}
],
tool_choice: 'auto',
tool_call_id: '<string>'
}
],
user: 'user_123',
doNotRecord: false,
metadata: {my_identifier: 'my-custom-ID'},
seed: 123
})
};
fetch('https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'threadId' => 'thread_123',
'variables' => [
'variableName' => 'Your Value'
],
'messages' => [
[
'role' => 'user',
'content' => 'Hello'
]
],
'stream' => false,
'model' => '<string>',
'max_tokens' => 123,
'temperature' => 123,
'top_p' => 123,
'presence_penalty' => 123,
'frequency_penalty' => 123,
'template' => [
[
'content' => '<string>',
'name' => '<string>',
'tool_calls' => [
[
'id' => '<string>',
'type' => 'function',
'function' => [
'name' => '<string>',
'arguments' => '<string>'
]
]
],
'tool_choice' => 'auto',
'tool_call_id' => '<string>'
]
],
'user' => 'user_123',
'doNotRecord' => false,
'metadata' => [
'my_identifier' => 'my-custom-ID'
],
'seed' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}"
payload := strings.NewReader("{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}")
.header("X-API-Key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.langtail.com/{workspace}/{project}/{assistant}/{environment}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"threadId\": \"thread_123\",\n \"variables\": {\n \"variableName\": \"Your Value\"\n },\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": \"Hello\"\n }\n ],\n \"stream\": false,\n \"model\": \"<string>\",\n \"max_tokens\": 123,\n \"temperature\": 123,\n \"top_p\": 123,\n \"presence_penalty\": 123,\n \"frequency_penalty\": 123,\n \"template\": [\n {\n \"content\": \"<string>\",\n \"name\": \"<string>\",\n \"tool_calls\": [\n {\n \"id\": \"<string>\",\n \"type\": \"function\",\n \"function\": {\n \"name\": \"<string>\",\n \"arguments\": \"<string>\"\n }\n }\n ],\n \"tool_choice\": \"auto\",\n \"tool_call_id\": \"<string>\"\n }\n ],\n \"user\": \"user_123\",\n \"doNotRecord\": false,\n \"metadata\": {\n \"my_identifier\": \"my-custom-ID\"\n },\n \"seed\": 123\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"created": 123,
"model": "<string>",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "I'm sorry, but I'm not able to fulfill this request."
},
"finish_reason": "stop"
}
]
}{
"error": "Invalid request body",
"issues": [
{
"code": "unrecognized_keys",
"keys": [
"unknown_variable"
],
"path": [
"variables"
],
"message": "Unrecognized key(s) in object: 'unknown_variable'"
}
]
}Note: The response includes an
x-langtail-thread-id header containing the
unique identifier for the thread associated with this response.Headers
Your Langtail API Key
Example:
"<LANGTAIL_API_KEY>"
Path Parameters
Your workspace URL slug
Example:
"workspace"
Your project URL slug
Example:
"project"
Your assistant URL slug
Example:
"assistant"
Your environment URL slug
Example:
"production"
Body
application/json
A unique identifier for the thread. If not provided, a new thread will be created.
Example:
"thread_123"
A mapping of variable names to their values. Will be injected in your saved assistant template.
Show child attributes
Show child attributes
Example:
{ "variableName": "Your Value" }
Additional messages. These will be appended to the Thread.
Show child attributes
Show child attributes
Example:
[{ "role": "user", "content": "Hello" }]
Example:
false
Overrides the model of deployed assistant.
Overrides the max tokens of deployed assistant. The maximum number of tokens that can be generated in the completion.
Overrides the temperature of deployed assistant. What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
Overrides the top_p of deployed assistant. An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or temperature but not both.
Overrides the presence_penalty of deployed assistant.
Overrides the frequency_penalty of deployed assistant.
Overrides the stored template messages with custom template messages.
Show child attributes
Show child attributes
Overrides the tool choice of deployed assistant.
Available options:
auto, required, none Overrides the response format of deployed assistant.
Show child attributes
Show child attributes
A unique identifier representing your end-user
Example:
"user_123"
If true, potentially sensitive data like the assistant and response will not be recorded in the logs
Example:
false
Additional custom data that will be stored for this request
Show child attributes
Show child attributes
Example:
{ "my_identifier": "my-custom-ID" }
A seed is used to generate reproducible results
Example:
123
Response
Chat completion response from OpenAI - see https://platform.openai.com/docs/api-reference/chat/object for more details. Note: The response includes an 'x-langtail-thread-id' header containing the unique identifier for the thread associated with this response.
A unique identifier for the chat completion.
The object type, which is always chat.completion.
The Unix timestamp (in seconds) of when the chat completion was created.
The model used for the chat completion.
A list of chat completion choices. Can be more than one if n is greater than 1.
Show child attributes
Show child attributes
Was this page helpful?