curl -X POST https://tools.runtools.ai/v1/tools/github/execute \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "list_repos",
"params": {
"owner": "runtools-ai"
}
}'
const result = await rt.tools.execute('github', {
action: 'list_repos',
params: {
owner: 'runtools-ai',
},
oauth: {
account: 'alfo19972',
},
});
const result = await rt.tools.execute('custom-crm', {
action: 'lookup_customer',
params: { email: 'person@example.com' },
credentialOverrides: {
apiKey: 'CRM_API_KEY',
},
});
const result = await rt.tools.execute('gmail', {
action: 'list_emails',
params: { max_results: 10 },
credentialScope: 'end_user',
endUser: {
appId: 'atlas',
externalUserId: 'customer_123',
},
});
{
"data": {
"success": true,
"result": {
"repositories": []
},
"durationMs": 418
}
}
{
"data": {
"success": false,
"error": {
"code": "execution_error",
"message": "Provider request failed"
},
"durationMs": 292
}
}
Tools
Execute Tool
Execute one Tool Hub action
POST
/
v1
/
tools
/
{slug}
/
execute
curl -X POST https://tools.runtools.ai/v1/tools/github/execute \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "list_repos",
"params": {
"owner": "runtools-ai"
}
}'
const result = await rt.tools.execute('github', {
action: 'list_repos',
params: {
owner: 'runtools-ai',
},
oauth: {
account: 'alfo19972',
},
});
const result = await rt.tools.execute('custom-crm', {
action: 'lookup_customer',
params: { email: 'person@example.com' },
credentialOverrides: {
apiKey: 'CRM_API_KEY',
},
});
const result = await rt.tools.execute('gmail', {
action: 'list_emails',
params: { max_results: 10 },
credentialScope: 'end_user',
endUser: {
appId: 'atlas',
externalUserId: 'customer_123',
},
});
{
"data": {
"success": true,
"result": {
"repositories": []
},
"durationMs": 418
}
}
{
"data": {
"success": false,
"error": {
"code": "execution_error",
"message": "Provider request failed"
},
"durationMs": 292
}
}
Tool execution endpoints use:
If no matching end-user connection exists, the endpoint returns
https://tools.runtools.ai/v1
Path Parameters
string
required
Tool slug.
Request Body
string
required
Tool action name.
object
Action parameters.
string
Optional credential isolation mode. Use
end_user with endUser for customer-owned product integrations. In end-user mode, Tool Hub never uses per-request, installed, org, or builder credentials.object
Optional per-request credentials. Prefer stored secrets or OAuth connections for production.
object
Map tool credential field names to secret names so values stay server-side.
credentials and credentialOverrides are accepted only on direct Tool Hub API/SDK calls. Agent-runtime tool calls use an internal signed capability and cannot provide credential fields in request JSON.
object
Optional account selector for OAuth-backed tools. Use
oauth.account for a human-readable email, username, display name, provider account ID, or connection ID. Use oauth.connectionId when you need an exact Connected Apps connection.object
App-scoped customer identity for Hosted Connect. Requires
endUser.appId and endUser.externalUserId. When present, credentialScope is treated as end_user.Response
boolean
Whether execution succeeded.
object
Tool-specific result when successful.
object
Tool-specific error when unsuccessful. Tool failures can return a non-2xx HTTP status.
number
Server-side execution duration.
curl -X POST https://tools.runtools.ai/v1/tools/github/execute \
-H "X-API-Key: $RUNTOOLS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "list_repos",
"params": {
"owner": "runtools-ai"
}
}'
const result = await rt.tools.execute('github', {
action: 'list_repos',
params: {
owner: 'runtools-ai',
},
oauth: {
account: 'alfo19972',
},
});
const result = await rt.tools.execute('custom-crm', {
action: 'lookup_customer',
params: { email: 'person@example.com' },
credentialOverrides: {
apiKey: 'CRM_API_KEY',
},
});
const result = await rt.tools.execute('gmail', {
action: 'list_emails',
params: { max_results: 10 },
credentialScope: 'end_user',
endUser: {
appId: 'atlas',
externalUserId: 'customer_123',
},
});
{
"data": {
"success": true,
"result": {
"repositories": []
},
"durationMs": 418
}
}
{
"data": {
"success": false,
"error": {
"code": "execution_error",
"message": "Provider request failed"
},
"durationMs": 292
}
}
Tool calls are billed before execution. If the organization does not have enough credits, the endpoint returns
402 insufficient_credits. If billing is temporarily unavailable, it returns 503 billing_unavailable.Credential Resolution
For org-scoped tool execution, RunTools resolves credentials in this order:- Per-request
credentials credentialOverridesthat point at stored secrets- Stored credentials for the installed tool
- Matching organization or user secrets
- Connected OAuth account when the tool declares an OAuth provider
oauth.account or oauth.connectionId.
For end-user execution, RunTools resolves credentials only from the matching Hosted Connect scope:
builder org + appId + externalUserId + tool
409 connect_required. It does not fall back to builder credentials, org secrets, installed-tool credentials, or another product user’s connection.