Skip to main content
POST
/
agents
/
{id}
/
execute
curl --request POST \ --url https://api.tess.im/agents/{id}/execute \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "temperature": "1", "model": "tess-6", "messages": [ { "role": "user", "content": "Summarize the latest ticket updates." } ], "tools": "no-tools", "waitExecution": false, "file_ids": [ 123, 321 ] } '

Code Examples

curl --request POST \
  --url 'https://api.tess.im/agents/{id}/execute' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
  }'
const axios = require('axios');

const data = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
  };

const config = {
  method: 'post',
  url: 'https://api.tess.im/agents/{id}/execute',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  data: data
};

const response = await axios(config);
console.log(response.data);
import requests
import json

url = "https://api.tess.im/agents/{id}/execute"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": False,
    "file_ids": [123, 321],
    "memory_collections": [456]
  }

response = requests.post(url, headers=headers, json=data)
print(response.json())
<?php
$curl = curl_init();

$data = [
    "temperature" => "1",
    "model" => "tess-5",
    "messages" => [
        [ "role" => "user", "content" => "Hello, how can you help me today?" ]
    ],
    "tools" => "no-tools",
    "waitExecution" => false,
    "file_ids" => [123, 321],
    "memory_collections" => [456]
];

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tess.im/agents/{id}/execute",
  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($data),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer YOUR_API_KEY",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "Error: " . $err;
} else {
  echo $response;
}
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Map;

public class Main {
    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();

        Map<String, Object> data = Map.of(
            "temperature", "1",
            "model", "tess-5",
            "messages", List.of(Map.of("role", "user", "content", "Hello, how can you help me today?")),
            "tools", "no-tools",
            "waitExecution", false,
            "file_ids", List.of(123, 321),
            "memory_collections", List.of(456)
        );

        String jsonPayload = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tess.im/agents/{id}/execute"))
            .header("Authorization", "Bearer YOUR_API_KEY")
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonPayload))
            .build();

        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}
package main

import (
    "fmt"
    "strings"
    "io/ioutil"
    "net/http"
)

func main() {
    payload := `{
        "temperature": "1",
        "model": "tess-5",
        "messages": [
            { "role": "user", "content": "Hello, how can you help me today?" }
        ],
        "tools": "no-tools",
        "waitExecution": false,
        "file_ids": [123, 321],
        "memory_collections": [456]
    }`

    client := &http.Client{}
    req, err := http.NewRequest("POST", "https://api.tess.im/agents/{id}/execute", strings.NewReader(payload))
    if err != nil {
        fmt.Println(err)
        return
    }
    
    req.Header.Add("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Add("Content-Type", "application/json")
    
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
        return
    }
    defer resp.Body.Close()
    
    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        fmt.Println(err)
        return
    }
    
    fmt.Println(string(body))
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
using System.Collections.Generic;

class Program
{
    static async Task Main(string[] args)
    {
        using (var client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_KEY");

            var data = new
            {
                temperature = "1",
                model = "tess-5",
                messages = new List<object> { new { role = "user", content = "Hello, how can you help me today?" } },
                tools = "no-tools",
                waitExecution = false,
                file_ids = new List<int> { 123, 321 },
                memory_collections = new List<int> { 456 }
            };

            var jsonPayload = JsonConvert.SerializeObject(data);
            var content = new StringContent(jsonPayload, Encoding.UTF8, "application/json");

            try
            {
                var response = await client.PostAsync("https://api.tess.im/agents/{id}/execute", content);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException e)
            {
                Console.WriteLine("\nException Caught!");
                Console.WriteLine("Message :{0} ", e.Message);
            }
        }
    }
}
require 'uri'
require 'net/http'
require 'json'

uri = URI('https://api.tess.im/agents/{id}/execute')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = {
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "Hello, how can you help me today?" }
    ],
    "tools": "no-tools",
    "waitExecution": false,
    "file_ids": [123, 321],
    "memory_collections": [456]
}.to_json

response = http.request(request)
puts response.read_body

Headers

ParameterTypeRequiredDescription
x-workspace-idintegerNoID of the workspace. If not provided, the user’s selected workspace will be used. Will be required in a future release.

Path Parameters

ParameterTypeRequiredDescription
idintegerYesThe agent ID.

Request Body

ParameterTypeRequiredDescription
temperaturestringNoChat Agent field. Sampling temperature between 0 and 2. Higher values produce more creative outputs (default: "1").
modelstringNoChat Agent field. Model identifier to use for execution (e.g., "tess-6").
toolsstringNoChat Agent field. Tool configuration for the agent (e.g., "agent", "no-tools").
root_idintegerNoChat Agent field. ID of an existing execution to continue a conversation thread.
messagesarrayNoChat Agent field. The agent messages. Required for Chat Agent templates. Supports user, assistant, developer roles.
waitExecutionbooleanNoIf true, waits for execution to finish before returning (timeout: 100 s). Default: false.
file_idsarrayNoArray of file IDs to attach to the execution.
memory_collectionsarrayNoArray of Memory Collection IDs to use in this execution. Memories indexed in these collections are automatically retrieved and injected into the agent context via semantic search.
Other root-level fieldsanyDepends on agentThis is not a fixed field name. You can send additional fields required by your specific agent directly at the request root. Check which fields are required in Get Agent by ID.
How to use memories in an executionTo inject memory context into an agent, pass Memory Collection IDs in the memory_collections field. The full flow is:
  1. Create a CollectionPOST /api/memory-collections — and save the returned id.
  2. Create MemoriesPOST /api/memories — passing collection_id and the memory text in the memory field.
  3. Execute the Agent — include "memory_collections": [collection_id] in the request body.
The agent will automatically use the relevant memories to contextualize the response.See the full guide at Memories.

Messages Roles (Chat Type Templates)

For chat type templates, the messages array supports the following roles:
RoleRequiredDescription
userYesUser messages. Must be paired with assistant messages.
assistantYesAssistant messages. Must be paired with user messages.
developerNoOptional developer message. Only allowed as the first message in the array.
systemNoNot supported. Using this role will cause an error.
Important rules:
  • Messages must alternate between user and assistant roles (after the optional developer message).
  • The developer role can only appear as the first message in the array and will be extracted before processing the rest.
  • If two consecutive messages have the same role (e.g., two user messages), the API will return a validation error: “Chat messages must be a pair of user/assistant”.
  • The system role is not supported and will cause an error.
Example with developer message:
{
  "messages": [
    { "role": "developer", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help you?" },
    { "role": "user", "content": "What's the weather like?" }
  ]
}
Example without developer message:
{
  "messages": [
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help you?" },
    { "role": "user", "content": "What's the weather like?" }
  ]
}
Get more details of which options are accepted by this Agent requesting this endpoint: Get Agent

Response

{
"template_id": "8794",
"responses": [
  {
    "id": 4773337,
    "status": "starting",
    "input": "hello",
    "output": "",
    "credits": 0.000337,
    "root_id": 4773337,
    "created_at": "2025-01-05T19:35:21.000000Z",
    "updated_at": "2025-01-05T19:35:21.000000Z",
    "template_id": 8794
  }
]
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-workspace-id
integer

ID of the workspace. If not provided, the user's selected workspace will be used. This field will be required in a future release.

Path Parameters

id
integer
required

The agent ID.

Body

application/json

Send a JSON object. Known fields are supported, and you can add custom fields directly at the root (for example: department, reporting_period, include_risks).

Free-form JSON object. Send known fields and any custom agent fields directly at the root level.

Response

200

Execution started (or completed if waitExecution: true).