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]
  }'

​
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.
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.

​
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).