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 '
{
  "stream": true,
  "temperature": "1",
  "model": "tess-6",
  "messages": [
    {
      "role": "user",
      "content": "Generate a concise status update."
    }
  ],
  "tools": "no-tools",
  "file_ids": [
    123,
    321
  ]
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.tess.im/llms.txt

Use this file to discover all available pages before exploring further.

​
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 '{
    "stream": true,
    "temperature": "1",
    "model": "tess-5",
    "messages": [
        { "role": "user", "content": "hello there!" }
    ],
    "tools": "no-tools",
    "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
streambooleanYesMust be true for this streaming endpoint.
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.
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.

​
Response

data: {"id": 123, "status": "running", "output": "Hi!", "error": null, "credits": null, "root_id": 123, "created_at": "2025-01-01T10:00:00.000000Z", "updated_at": "2025-01-01T10:00:00.000000Z", "template_id": 10}

data: {"id": 123, "status": "completed", "output": "", "error": null, "credits": 10, "root_id": 123, "created_at": "2025-01-01T10:00:00.000000Z", "updated_at": "2025-01-01T10:00:00.000000Z", "template_id": 10}

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. Keep stream: true in this endpoint and add any custom fields directly at the root.

Free-form JSON object. Use stream: true and add known or custom fields at the root level.

Response

200

Server-Sent Events stream.