The Toolhouse Platform API provides management and orchestration capabilities for AI agents and tools. It includes endpoints for user profile management, billing, API key administration, tool discovery and execution, agent run management with pagination, Agent Studio chat sessions, agent file management, agent subscriptions, bundle management, scheduled agent execution via cron expressions, and MCP server configuration. Authentication uses HTTPBearer JWT tokens.
openapi: 3.1.0
info:
title: Toolhouse API
description: All the API! \o/
version: 0.1.0
paths:
/me/agent-runs:
get:
tags:
- Agent Runs
- User API
summary: Toolhouse Get User Agent Runs
description: User Installed Tools
operationId: get_user_agent_runs_me_agent_runs_get
security:
- HTTPBearer: []
parameters:
- name: next_cursor
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Next Cursor
- name: limit
in: query
required: false
schema:
type: integer
default: 30
title: Limit
responses:
'200':
description: Successfully retrieved agent runs list
content:
application/json:
schema:
$ref: '#/components/schemas/AgentRunViewListResponse'
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agent-runs/{run_id}:
get:
tags:
- Agent Runs
- User API
summary: Toolhouse Get User Agent Run
description: User Installed Tools
operationId: get_user_agent_run_me_agent_runs__run_id__get
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
format: uuid
title: Run Id
responses:
'200':
description: Successfully retrieved agent run
content:
application/json:
schema:
$ref: '#/components/schemas/AgentRunView'
'404':
description: Agent run not found
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agent-runs/{run_id}/mcp-server-logs:
get:
tags:
- Agent Runs
- User API
summary: Toolhouse Get User Agent Run Mcp Server Logs
description: User Installed Tools
operationId: get_user_agent_run_mcp_server_logs_me_agent_runs__run_id__mcp_server_logs_get
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
format: uuid
title: Run Id
responses:
'200':
description: Successfully retrieved MCP server logs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/McpServerLog'
title: Response Get User Agent Run Mcp Server Logs Me Agent Runs Run Id Mcp Server Logs Get
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agent-runs/{run_id}/logs:
get:
tags:
- Agent Runs
- User API
summary: Toolhouse Get User Agent Run Logs
description: User Installed Tools
operationId: get_user_agent_run_logs_me_agent_runs__run_id__logs_get
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
format: uuid
title: Run Id
responses:
'200':
description: Successfully retrieved agent run logs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AgentRunLog'
title: Response Get User Agent Run Logs Me Agent Runs Run Id Logs Get
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/subscribe:
post:
tags:
- User API
summary: Toolhouse Subscribe To Agent
description: Subscribe to a paid agent
operationId: subscribe_to_agent_me_agents__agent_id__subscribe_post
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubscribeRequest'
responses:
'200':
description: Checkout session created
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubscribeResponse'
'400':
description: Agent is not a paid agent or user is the owner
'402':
description: Already subscribed
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/unsubscribe:
post:
tags:
- User API
summary: Toolhouse Unsubscribe From Agent
description: Unsubscribe from a paid agent
operationId: unsubscribe_from_agent_me_agents__agent_id__unsubscribe_post
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
responses:
'200':
description: Successfully unsubscribed
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubscriptionResponse'
'400':
description: No active subscription to cancel or no Stripe subscription found
'404':
description: Subscription not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/subscriptions:
get:
tags:
- User API
summary: Toolhouse List Agent Subscriptions
description: List all agent subscriptions for the current user
operationId: list_agent_subscriptions_me_subscriptions_get
responses:
'200':
description: Agent subscriptions retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubscriptionListResponse'
security:
- HTTPBearer: []
/me/subscriptions/{agent_id}:
get:
tags:
- User API
summary: Toolhouse Get Agent Subscription
description: Get subscription details for a specific agent
operationId: get_agent_subscription_me_subscriptions__agent_id__get
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
responses:
'200':
description: Agent subscription details retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/AgentSubscriptionResponse'
'404':
description: Subscription not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agent-studio-chats:
get:
tags:
- User API
summary: Toolhouse Get Agent Studio Chats
description: Get all agent studio chats for the authenticated user
operationId: get_agent_studio_chats_me_agent_studio_chats_get
responses:
'200':
description: Successfully retrieved agent studio chats
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AgentStudioChat'
type: array
title: Response Get Agent Studio Chats Me Agent Studio Chats Get
security:
- HTTPBearer: []
post:
tags:
- User API
summary: Toolhouse Create Agent Studio Chat
description: Create a new agent studio chat or return existing one if run_id already exists
operationId: create_agent_studio_chat_me_agent_studio_chats_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChatCreate'
required: true
responses:
'200':
description: Successfully created agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'400':
description: Agent Studio creation failed or sandbox tier attempting to create private chat
'409':
description: Agent Studio chat with this run_id already exists
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/me/agent-studio-chats/{run_id}:
get:
tags:
- User API
summary: Toolhouse Get Agent Studio Chat
description: Get a specific agent studio chat by ID
operationId: get_agent_studio_chat_me_agent_studio_chats__run_id__get
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
responses:
'200':
description: Successfully retrieved agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'403':
description: You don't have permission to access this chat
'404':
description: Agent studio chat not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- User API
summary: Toolhouse Update Agent Studio Chat
description: Update an agent studio chat (full update)
operationId: update_agent_studio_chat_me_agent_studio_chats__run_id__put
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChatCreate'
responses:
'200':
description: Successfully updated agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'400':
description: Sandbox tier attempting to set chat as private
'403':
description: You don't have permission to access this chat
'404':
description: Agent studio chat not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- User API
summary: Toolhouse Patch Agent Studio Chat
description: Update an agent studio chat (partial update)
operationId: patch_agent_studio_chat_me_agent_studio_chats__run_id__patch
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChatUpdate'
responses:
'200':
description: Successfully updated agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'400':
description: Sandbox tier attempting to set chat as private
'403':
description: You don't have permission to access this chat
'404':
description: Agent studio chat not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- User API
summary: Toolhouse Delete Agent Studio Chat
description: Delete an agent studio chat (soft delete)
operationId: delete_agent_studio_chat_me_agent_studio_chats__run_id__delete
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
responses:
'200':
description: Successfully deleted agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'400':
description: Failed to delete agent studio chat
'403':
description: You don't have permission to access this chat
'404':
description: Agent studio chat not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agent-studio-chats/{run_id}/clone:
post:
tags:
- User API
summary: Toolhouse Clone Agent Studio Chat
description: Clone an agent studio chat
operationId: clone_agent_studio_chat_me_agent_studio_chats__run_id__clone_post
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
responses:
'201':
description: Successfully cloned agent studio chat
content:
application/json:
schema:
$ref: '#/components/schemas/AgentStudioChat'
'400':
description: Private agent studio chats cannot be cloned
'404':
description: Agent studio chat not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/customizations/theme:
get:
tags:
- User API
summary: Toolhouse Get Agent Theme Preference
operationId: get_agent_theme_preference_me_agents__agent_id__customizations_theme_get
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
responses:
'200':
description: Successfully retrieved agent theme preference
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/AgentThemePreferenceResponse'
- type: 'null'
title: Response Get Agent Theme Preference Me Agents Agent Id Customizations Theme Get
'403':
description: Not authorized to access this agent
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- User API
summary: Toolhouse Upsert Agent Theme Preference
operationId: upsert_agent_theme_preference_me_agents__agent_id__customizations_theme_put
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentThemePreferenceUpsertRequest'
responses:
'200':
description: Successfully updated agent theme preference
content:
application/json:
schema:
$ref: '#/components/schemas/AgentThemePreferenceResponse'
'400':
description: Invalid theme color format
'403':
description: Not authorized to access this agent
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/files:
get:
tags:
- User API
summary: Toolhouse List Agent Files
description: List all files for an agent
operationId: list_agent_files_me_agents__agent_id__files_get
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
responses:
'200':
description: Successfully retrieved agent files
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileListResponse'
'403':
description: Not authorized to access this agent
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- User API
summary: Toolhouse Create Agent File
description: Create a new file reference for an agent
operationId: create_agent_file_me_agents__agent_id__files_post
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileCreateRequest'
responses:
'201':
description: Successfully created agent file
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileResponse'
'400':
description: Invalid request or file limit exceeded
'403':
description: Not authorized to access this agent
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/files/{file_id}:
get:
tags:
- User API
summary: Toolhouse Get Agent File
description: Get a specific agent file
operationId: get_agent_file_me_agents__agent_id__files__file_id__get
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
- name: file_id
in: path
required: true
schema:
type: string
format: uuid
title: File Id
responses:
'200':
description: Successfully retrieved agent file
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileResponse'
'403':
description: Not authorized to access this file
'404':
description: File not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- User API
summary: Toolhouse Update Agent File
description: Update an agent file (partial update)
operationId: update_agent_file_me_agents__agent_id__files__file_id__patch
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
- name: file_id
in: path
required: true
schema:
type: string
format: uuid
title: File Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileUpdateRequest'
responses:
'200':
description: Successfully updated agent file
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileResponse'
'403':
description: Not authorized to access this file
'404':
description: File not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- User API
summary: Toolhouse Delete Agent File
description: Delete an agent file
operationId: delete_agent_file_me_agents__agent_id__files__file_id__delete
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
- name: file_id
in: path
required: true
schema:
type: string
format: uuid
title: File Id
responses:
'204':
description: Successfully deleted agent file
'403':
description: Not authorized to access this file
'404':
description: File not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/files/positions:
put:
tags:
- User API
summary: Toolhouse Update File Positions
description: Batch update file positions for ordering
operationId: update_file_positions_me_agents__agent_id__files_positions_put
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
format: uuid
title: Agent Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileBatchPositionRequest'
responses:
'200':
description: Successfully updated file positions
content:
application/json:
schema:
$ref: '#/components/schemas/AgentFileListResponse'
'403':
description: Not authorized to access this agent
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents:
get:
tags:
- User API
summary: Toolhouse Get All Agents
operationId: get_all_agents_me_agents_get
responses:
'200':
description: Successfully retrieved all agents
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AgentModel'
type: array
title: Response Get All Agents Me Agents Get
security:
- HTTPBearer: []
post:
tags:
- User API
summary: Toolhouse Upsert Agent
operationId: upsert_agent_me_agents_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AgentRequest'
required: true
responses:
'200':
description: Successfully created or updated agent
content:
application/json:
schema:
$ref: '#/components/schemas/AgentModel'
'400':
description: Missing chat prompt or sandbox tier attempting to set agent as private
'403':
description: You don't have permission to access this chat
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/me/agents/{agent_id}:
get:
tags:
- User API
summary: Toolhouse Get Agent
operationId: get_agent_me_agents__agent_id__get
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
responses:
'200':
description: Successfully retrieved agent
content:
application/json:
schema:
$ref: '#/components/schemas/AgentModel'
'403':
description: You don't have permission to access this chat
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}/upsell-description:
post:
tags:
- User API
summary: Toolhouse Generate Agent Upsell Description
operationId: generate_agent_upsell_description_me_agents__agent_id__upsell_description_post
security:
- HTTPBearer: []
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
responses:
'200':
description: Successfully generated upsell description
content:
application/json:
schema:
$ref: '#/components/schemas/AgentModel'
'404':
description: Agent not found
'500':
description: Failed to generate upsell description
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/vanity/slug:
post:
tags:
- User API
summary: Toolhouse Generate Slug
operationId: generate_slug_me_agents_vanity_slug_post
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SlugRequest'
responses:
'200':
description: Successfully generated slug
content:
application/json:
schema: {}
'500':
description: Failed to generate slug from internal agent
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
get:
tags:
- User API
summary: Toolhouse Check Slug Availability
operationId: check_slug_availability_me_agents_vanity_slug_get
security:
- HTTPBearer: []
parameters:
- name: slug
in: query
required: true
schema:
type: string
title: Slug
responses:
'200':
description: Successfully validated slug
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/api-keys:
get:
tags:
- API Keys
- User API
summary: Toolhouse Get Api Keys
description: Get all API Keys
operationId: get_api_keys_me_api_keys_get
responses:
'200':
description: Successfully retrieved all API keys
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ApiKeyHidden'
type: array
title: Response Get Api Keys Me Api Keys Get
'500':
description: Internal server error
security:
- HTTPBearer: []
post:
tags:
- API Keys
- User API
summary: Toolhouse Post Create Api Key
description: Create API Key
operationId: post_create_api_key_me_api_keys_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreate'
required: true
responses:
'200':
description: Successfully created API key
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/me/api-keys/default:
get:
tags:
- API Keys
- User API
summary: Toolhouse Get Default Api Key
description: Get default API Key
operationId: get_default_api_key_me_api_keys_default_get
responses:
'200':
description: Successfully retrieved default API key
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'500':
description: Internal server error
security:
- HTTPBearer: []
/me/api-keys/{api_key_id}:
get:
tags:
- API Keys
- User API
summary: Toolhouse Get Api Key
description: Get API Key by ID
operationId: get_api_key_me_api_keys__api_key_id__get
security:
- HTTPBearer: []
parameters:
- name: api_key_id
in: path
required: true
schema:
type: integer
title: Api Key Id
responses:
'200':
description: Successfully retrieved API key
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKey'
'404':
description: API key not found
'500':
description: Internal server error
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
tags:
- API Keys
- User API
summary: Toolhouse Delete Api Key
description: D
# --- truncated at 32 KB (240 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toolhouse/refs/heads/main/openapi/toolhouse-openapi-original.yml