Overview

Welcome to the Tess AI API documentation! This guide will help you get started with our API and understand how to integrate Tess AI’s powerful capabilities into your applications.

Base URL

All API requests should be made to the following base URL:

https://api.tess.im

Authentication

All API requests require authentication using an API key. You can obtain your API key from the Tess AI Dashboard. To authenticate your requests, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Workspace header

Authenticated API requests must include the workspace context header:

x-workspace-id: YOUR_WORKSPACE_ID

Required as of 2026-09-01 for agent execution and other authenticated API endpoints. Until then, if omitted, the API falls back to the user’s selected workspace (deprecated). After the cutoff, a missing header returns 422. See Errors.

API Endpoints

The Tess AI API provides the following main categories of endpoints:

Agents

Endpoint	Method	Description	Documentation
`/agents`	GET	List all agents	List Agents
`/agents/{id}`	GET	Get a specific agent	Get Agent
`/agents/{id}/execute`	POST	Execute an agent	Execute Agent
`/agent-responses/{id}`	GET	Get agent execution response	Get Agent Response

Agent Files

Endpoint	Method	Description	Documentation
`/agents/{agentId}/files`	GET	List agent files	List Agent Files
`/agents/{agentId}/files`	POST	Link files to agent	Link Files to Agent
`/agents/{agentId}/files/{fileId}`	DELETE	Delete agent file	Delete Agent File

Agent Webhooks

Endpoint	Method	Description	Documentation
`/agents/{id}/webhooks`	GET	List agent webhooks	List Agent Webhooks
`/agents/{id}/webhooks`	POST	Create agent webhook	Create Agent Webhook

Workspaces

Endpoint	Method	Description	Documentation
`/workspaces/usage`	GET	List agent execution history (usage)	Workspace usage

Mission Control

Endpoint	Method	Description	Documentation
`/mission-control/usage`	GET	Workspace AI consumption, executions and adoption	Mission Control usage

Audit Events

Endpoint	Method	Description	Documentation
`/audit-events`	GET	Pull workspace-scoped audit events for SIEM ingestion	Audit events

Memories

Endpoint	Method	Description	Documentation
`/memories`	GET	List all memories	List Memories
`/memories`	POST	Create a memory	Create Memory
`/memories/{memoryId}`	PATCH	Update a memory	Update Memory
`/memories/{memoryId}`	DELETE	Delete a memory	Delete Memory

Memory Collections

Endpoint	Method	Description	Documentation
`/memory-collections`	GET	List all collections	List Collections
`/memory-collections`	POST	Create a collection	Create Collection
`/memory-collections/{collection_id}`	PUT	Update a collection	Update Collection
`/memory-collections/{collection_id}`	DELETE	Delete a collection	Delete Collection

Files

Endpoint	Method	Description	Documentation
`/files`	GET	List all files	List Files
`/files`	POST	Upload a file	Upload File
`/files/{fileId}`	GET	Get file details	Get File
`/files/{fileId}`	DELETE	Delete a file	Delete File
`/files/{fileId}/process`	POST	Process a file	Process File

Webhooks

Endpoint	Method	Description	Documentation
`/webhooks`	GET	List all webhooks	List Webhooks
`/webhooks/{id}`	DELETE	Delete a webhook	Delete Webhook

Agent Versions

Endpoint	Method	Description	Documentation
`/agents/{id}/versions`	GET	List Agent Versions	List Agent Versions
`/agents/{id}/versions/{version_number}`	GET	Get Agent Version	Get Agent Version
`/agents/{id}/versions/{version_number}/rollback`	POST	Rollback Agent Version	Rollback Agent Version

Agent Schedulers

Endpoint	Method	Description	Documentation
`/schedulers`	GET	List All Schedulers	List All Schedulers
`/agents/{agentId}/schedulers`	GET	List Agent Schedulers	List Agent Schedulers
`/agents/{agentId}/schedulers`	POST	Create Scheduler	Create Scheduler
`/agents/{agentId}/schedulers/{schedulerId}`	GET	Get Scheduler	Get Scheduler
`/agents/{agentId}/schedulers/{schedulerId}`	PUT	Update Scheduler	Update Scheduler
`/agents/{agentId}/schedulers/{schedulerId}`	DELETE	Delete Scheduler	Delete Scheduler
`/agents/{agentId}/schedulers/by-root-execution/{agentRootIdExecution}`	DELETE	Delete Schedulers by Root Execution	Delete Schedulers by Root Execution

Artifacts

Endpoint	Method	Description	Documentation
`/artifacts`	GET	List Artifacts	List Artifacts
`/artifacts`	POST	Create Artifact	Create Artifact
`/artifacts/{universal_id}`	GET	Get Artifact	Get Artifact
`/artifacts/{universal_id}`	PATCH	Rename Artifact	Rename Artifact
`/artifacts/{universal_id}`	DELETE	Delete Artifact	Delete Artifact
`/artifacts/{universal_id}/edit`	POST	Edit Artifact	Edit Artifact
`/artifacts/{universal_id}/publish`	POST	Publish Artifact Version	Publish Artifact Version
`/artifacts/{universal_id}/publish`	DELETE	Unpublish Artifact	Unpublish Artifact
`/artifacts/{universal_id}/restore`	POST	Restore Artifact Version	Restore Artifact Version
`/artifacts/{universal_id}/share`	POST	Share or Unshare Artifact	Share or Unshare Artifact
`/artifacts/{universal_id}/versions`	GET	List Artifact Versions	List Artifact Versions
`/artifacts/{universal_id}/versions/{version}`	DELETE	Delete Artifact Version	Delete Artifact Version
`/artifact-templates`	GET	List Artifact Templates	List Artifact Templates

Memory Import

Endpoint	Method	Description	Documentation
`/memory-import`	POST	Import Memories from Text	Import Memories from Text
`/memory-import/{id}`	GET	Get Memory Import Status	Get Memory Import Status

Account

Endpoint	Method	Description	Documentation
`/me`	GET	Get Current User	Get Current User

Agent Responses

Endpoint	Method	Description	Documentation
`/agent-responses`	GET	List Agent Responses	List Agent Responses

File References and Visibility

Endpoint	Method	Description	Documentation
`/files/resolve`	POST	Resolve File Reference	Resolve File Reference
`/files/{fileId}/visibility`	PATCH	Update File Visibility	Update File Visibility

Memory Collection IDs

Endpoint	Method	Description	Documentation
`/memory-collections/ids`	GET	List Collection IDs	List Collection IDs

Digital Employees

Endpoint	Method	Description	Documentation
`/digital-employees/capabilities`	GET	Get Capabilities	Get Capabilities
`/digital-employees`	GET	List Digital Employees	List Digital Employees
`/digital-employees/standalone`	POST	Create Standalone Employee	Create Standalone Employee
`/digital-employees/agents/{agentId}`	POST	Create Employee from Agent	Create Employee from Agent
`/digital-employees/{employeeId}`	GET	Get Digital Employee	Get Digital Employee
`/digital-employees/{employeeId}`	PUT	Update Digital Employee	Update Digital Employee
`/digital-employees/{employeeId}/duplicate`	POST	Duplicate Digital Employee	Duplicate Digital Employee
`/digital-employees/{employeeId}`	DELETE	Delete Digital Employee	Delete Digital Employee
`/digital-employees/schedule-preview`	POST	Preview Schedule	Preview Schedule
`/digital-employees/{employeeId}/invoke`	POST	Invoke Digital Employee	Invoke Digital Employee
`/digital-employees/{employeeId}/runs/{runId}/retry`	POST	Retry Run	Retry Run
`/digital-employees/{employeeId}/runs`	GET	List Runs	List Runs
`/digital-employees/{employeeId}/runs/{runId}`	GET	Get Run	Get Run
`/digital-employees/{employeeId}/runs/{runId}/output`	GET	Get Run Output	Get Run Output
`/digital-employees/{employeeId}/runs/{runId}/stream`	GET	Stream Run	Stream Run
`/digital-employees/{employeeId}/pause`	POST	Pause Digital Employee	Pause Digital Employee
`/digital-employees/{employeeId}/resume`	POST	Resume Digital Employee	Resume Digital Employee
`/digital-employees/{employeeId}/rollback-options`	GET	Get Rollback Options	Get Rollback Options
`/digital-employees/{employeeId}/rollback`	POST	Rollback Digital Employee	Rollback Digital Employee
`/digital-employees/{employeeId}/reparent`	POST	Reparent Digital Employee	Reparent Digital Employee
`/digital-employees/{employeeId}/detach`	POST	Detach Digital Employee	Detach Digital Employee
`/digital-employees/{employeeId}/runs/summary`	GET	Get Runs Summary	Get Runs Summary
`/digital-employees/{employeeId}/activity`	GET	Get Activity Log	Get Activity Log
`/digital-employees/{employeeId}/files`	GET	Get Employee Files	Get Employee Files
`/digital-employees/{employeeId}/goal`	PUT	Update Goal	Update Goal
`/digital-employees/{employeeId}/approve`	POST	Approve Hire Request	Approve Hire Request
`/digital-employees/{employeeId}/reject`	POST	Reject Hire Request	Reject Hire Request
`/digital-employees/avatar-upload`	POST	Upload Avatar	Upload Avatar
`/digital-employees/template-packs/agents/{agentId}`	GET	Export Template Pack	Export Template Pack
`/digital-employees/template-packs/preview-import`	POST	Preview Template Import	Preview Template Import
`/digital-employees/template-packs/import`	POST	Import Template Pack	Import Template Pack

Request Format

Most API endpoints accept JSON-encoded request bodies. Make sure to include the following header in your requests:

Content-Type: application/json

Response Format

All API responses are returned in JSON format. A successful response will typically have a 2xx HTTP status code and contain the requested data. Error responses will have a 4xx or 5xx status code and include an error message.

API Guide

API Reference

Integrations

Model Context Protocol (MCP)

Base URL

Authentication

Workspace header

API Endpoints

Agents

Agent Files

Agent Webhooks

Workspaces

Mission Control

Audit Events

Memories

Memory Collections

Files

Webhooks

Agent Versions

Agent Schedulers

Artifacts

Memory Import

Account

Agent Responses

File References and Visibility

Memory Collection IDs

Digital Employees

Request Format

Response Format

​Base URL

​Authentication

​Workspace header

​API Endpoints

​Agents

​Agent Files

​Agent Webhooks

​Workspaces

​Mission Control

​Audit Events

​Memories

​Memory Collections

​Files

​Webhooks

​Agent Versions

​Agent Schedulers

​Artifacts

​Memory Import

​Account

​Agent Responses

​File References and Visibility

​Memory Collection IDs

​Digital Employees

​Request Format

​Response Format

Base URL

Authentication

Workspace header

API Endpoints

Agents

Agent Files

Agent Webhooks

Workspaces

Mission Control

Audit Events

Memories

Memory Collections

Files

Webhooks

Agent Versions

Agent Schedulers

Artifacts

Memory Import

Account

Agent Responses

File References and Visibility

Memory Collection IDs

Digital Employees

Request Format

Response Format