Toolhouse User API API
The User API API from Toolhouse — 58 operation(s) for user api.
The User API API from Toolhouse — 58 operation(s) for user api.
openapi: 3.1.0
info:
title: Toolhouse Agent Runs User API API
description: All the API! \o/
version: 0.1.0
tags:
- name: User API
paths:
/me/agent-runs:
get:
tags:
- User API
summary: 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:
- User API
summary: 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:
- User API
summary: 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:
- User API
summary: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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: 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/list:
get:
tags:
- User API
summary: Get Agents List
operationId: get_agents_list_me_agents_list_get
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 30
title: Limit
- name: next_cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Search
responses:
'200':
description: Successfully retrieved paginated agents
content:
application/json:
schema:
$ref: '#/components/schemas/AgentListResponse'
'400':
description: Invalid pagination cursor
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/agents/{agent_id}:
get:
tags:
- User API
summary: 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: 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: 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: 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/agents/{agent_id}/transfer:
post:
tags:
- User API
summary: Transfer Agent
description: Transfer agent ownership to another user (Toolhouse employees only)
operationId: transfer_agent_me_agents__agent_id__transfer_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/TransferAgentRequest'
responses:
'200':
description: Successfully transferred agent
content:
application/json:
schema:
type: object
additionalProperties: true
title: Response Transfer Agent Me Agents Agent Id Transfer Post
'403':
description: Only Toolhouse employees can transfer agents
'404':
description: Agent or recipient user not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/me/api-keys:
get:
tags:
- User API
summary: 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:
- User API
summary: 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:
# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toolhouse/refs/heads/main/openapi/toolhouse-user-api-api-openapi.yml