Execute tool
Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.
import requests
url = "https://backend.composio.dev/api/v3/tools/execute/{tool_slug}"
payload = {
"connected_account_id": "ca_1a2b3c4d5e6f",
"entity_id": "repo-123",
"user_id": "user-123",
"version": "latest",
"custom_auth_params": {
"base_url": "https://api.example.com",
"parameters": [
{
"name": "x-api-key",
"value": "secret-key",
"in": "header"
}
]
},
"custom_connection_data": {
"authScheme": "OAUTH2",
"toolkitSlug": "github",
"val": { "access_token": "secret-token" }
},
"arguments": {
"repository": "octocat/Hello-World",
"workflow_id": "main.yml",
"ref": "main",
"inputs": { "environment": "production" }
},
"text": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment",
"allow_tracing": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connected_account_id: 'ca_1a2b3c4d5e6f',
entity_id: 'repo-123',
user_id: 'user-123',
version: 'latest',
custom_auth_params: {
base_url: 'https://api.example.com',
parameters: [{name: 'x-api-key', value: 'secret-key', in: 'header'}]
},
custom_connection_data: {
authScheme: 'OAUTH2',
toolkitSlug: 'github',
val: {access_token: 'secret-token'}
},
arguments: {
repository: 'octocat/Hello-World',
workflow_id: 'main.yml',
ref: 'main',
inputs: {environment: 'production'}
},
text: 'Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment',
allow_tracing: false
})
};
fetch('https://backend.composio.dev/api/v3/tools/execute/{tool_slug}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://backend.composio.dev/api/v3/tools/execute/{tool_slug} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"connected_account_id": "ca_1a2b3c4d5e6f",
"entity_id": "repo-123",
"user_id": "user-123",
"version": "latest",
"custom_auth_params": {
"base_url": "https://api.example.com",
"parameters": [
{
"name": "x-api-key",
"value": "secret-key",
"in": "header"
}
]
},
"custom_connection_data": {
"authScheme": "OAUTH2",
"toolkitSlug": "github",
"val": {
"access_token": "secret-token"
}
},
"arguments": {
"repository": "octocat/Hello-World",
"workflow_id": "main.yml",
"ref": "main",
"inputs": {
"environment": "production"
}
},
"text": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment",
"allow_tracing": false
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.composio.dev/api/v3/tools/execute/{tool_slug}"
payload := strings.NewReader("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.composio.dev/api/v3/tools/execute/{tool_slug}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://backend.composio.dev/api/v3/tools/execute/{tool_slug}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-api-key", "<api-key>");
request.AddJsonBody("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
false{
"data": {
"run_id": 12345678,
"status": "queued",
"created_at": "2023-01-01T12:00:00Z",
"html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"
},
"error": "<string>",
"successful": true,
"session_info": {
"session_id": "session-12345",
"expires_at": "2023-01-01T13:00:00Z"
},
"log_id": "log_1a2b3c4d5e6f"
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}Authorizations
Headers
Body
Unique identifier for the connected account to use for authentication. Pass instant_account to run the tool on the Composio instant account for its toolkit, even when the user has connected the toolkit themselves; the request fails rather than falling back to another credential.
instant_account "ca_1a2b3c4d5e6f"
Natural language description of the task to perform (mutually exclusive with arguments)
"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment"
Response
Successfully executed action and received response
import requests
url = "https://backend.composio.dev/api/v3/tools/execute/{tool_slug}"
payload = {
"connected_account_id": "ca_1a2b3c4d5e6f",
"entity_id": "repo-123",
"user_id": "user-123",
"version": "latest",
"custom_auth_params": {
"base_url": "https://api.example.com",
"parameters": [
{
"name": "x-api-key",
"value": "secret-key",
"in": "header"
}
]
},
"custom_connection_data": {
"authScheme": "OAUTH2",
"toolkitSlug": "github",
"val": { "access_token": "secret-token" }
},
"arguments": {
"repository": "octocat/Hello-World",
"workflow_id": "main.yml",
"ref": "main",
"inputs": { "environment": "production" }
},
"text": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment",
"allow_tracing": False
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connected_account_id: 'ca_1a2b3c4d5e6f',
entity_id: 'repo-123',
user_id: 'user-123',
version: 'latest',
custom_auth_params: {
base_url: 'https://api.example.com',
parameters: [{name: 'x-api-key', value: 'secret-key', in: 'header'}]
},
custom_connection_data: {
authScheme: 'OAUTH2',
toolkitSlug: 'github',
val: {access_token: 'secret-token'}
},
arguments: {
repository: 'octocat/Hello-World',
workflow_id: 'main.yml',
ref: 'main',
inputs: {environment: 'production'}
},
text: 'Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment',
allow_tracing: false
})
};
fetch('https://backend.composio.dev/api/v3/tools/execute/{tool_slug}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://backend.composio.dev/api/v3/tools/execute/{tool_slug} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"connected_account_id": "ca_1a2b3c4d5e6f",
"entity_id": "repo-123",
"user_id": "user-123",
"version": "latest",
"custom_auth_params": {
"base_url": "https://api.example.com",
"parameters": [
{
"name": "x-api-key",
"value": "secret-key",
"in": "header"
}
]
},
"custom_connection_data": {
"authScheme": "OAUTH2",
"toolkitSlug": "github",
"val": {
"access_token": "secret-token"
}
},
"arguments": {
"repository": "octocat/Hello-World",
"workflow_id": "main.yml",
"ref": "main",
"inputs": {
"environment": "production"
}
},
"text": "Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment",
"allow_tracing": false
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.composio.dev/api/v3/tools/execute/{tool_slug}"
payload := strings.NewReader("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.composio.dev/api/v3/tools/execute/{tool_slug}")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://backend.composio.dev/api/v3/tools/execute/{tool_slug}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-api-key", "<api-key>");
request.AddJsonBody("{\n \"connected_account_id\": \"ca_1a2b3c4d5e6f\",\n \"entity_id\": \"repo-123\",\n \"user_id\": \"user-123\",\n \"version\": \"latest\",\n \"custom_auth_params\": {\n \"base_url\": \"https://api.example.com\",\n \"parameters\": [\n {\n \"name\": \"x-api-key\",\n \"value\": \"secret-key\",\n \"in\": \"header\"\n }\n ]\n },\n \"custom_connection_data\": {\n \"authScheme\": \"OAUTH2\",\n \"toolkitSlug\": \"github\",\n \"val\": {\n \"access_token\": \"secret-token\"\n }\n },\n \"arguments\": {\n \"repository\": \"octocat/Hello-World\",\n \"workflow_id\": \"main.yml\",\n \"ref\": \"main\",\n \"inputs\": {\n \"environment\": \"production\"\n }\n },\n \"text\": \"Trigger the main workflow in the octocat/Hello-World repository on the main branch for the production environment\",\n \"allow_tracing\": false\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
false{
"data": {
"run_id": 12345678,
"status": "queued",
"created_at": "2023-01-01T12:00:00Z",
"html_url": "https://github.com/octocat/Hello-World/actions/runs/12345678"
},
"error": "<string>",
"successful": true,
"session_info": {
"session_id": "session-12345",
"expires_at": "2023-01-01T13:00:00Z"
},
"log_id": "log_1a2b3c4d5e6f"
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}