Run Tool
curl --request POST \
--url https://agentos.useparagon.com/api/tools/projects/{projectId}/executions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"intentName": "EXAMPLE_LIST_RECORDS",
"args": {
"limit": 10
},
"outputMode": "auto"
}
'import requests
url = "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions"
payload = {
"intentName": "EXAMPLE_LIST_RECORDS",
"args": { "limit": 10 },
"outputMode": "auto"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({intentName: 'EXAMPLE_LIST_RECORDS', args: {limit: 10}, outputMode: 'auto'})
};
fetch('https://agentos.useparagon.com/api/tools/projects/{projectId}/executions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'intentName' => 'EXAMPLE_LIST_RECORDS',
'args' => [
'limit' => 10
],
'outputMode' => 'auto'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions"
payload := strings.NewReader("{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agentos.useparagon.com/api/tools/projects/{projectId}/executions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agentos.useparagon.com/api/tools/projects/{projectId}/executions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}"
response = http.request(request)
puts response.read_body{
"executionId": "exec_0123456789abcdef0123456789abcdef",
"engine": "declarative",
"status": "completed",
"startedAt": "2026-10-05T21:00:00.000Z",
"settledAt": "2026-10-05T21:00:01.200Z",
"durationMs": 1200,
"calls": [
{
"seq": 1,
"kind": "run",
"tool": "EXAMPLE_LIST_RECORDS",
"integration": "example",
"decision": "allowed",
"upstreamStatus": 200
}
],
"output": {
"inline": {
"records": []
}
}
}{
"executionId": "exec_0123456789abcdef0123456789abcdef",
"engine": "declarative",
"status": "running",
"startedAt": "2026-10-05T21:00:00.000Z",
"settledAt": null,
"durationMs": null,
"calls": []
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}Tools
Run Tool
Run a tool on behalf of a Connected User.
POST
/
api
/
tools
/
projects
/
{projectId}
/
executions
Run Tool
curl --request POST \
--url https://agentos.useparagon.com/api/tools/projects/{projectId}/executions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"intentName": "EXAMPLE_LIST_RECORDS",
"args": {
"limit": 10
},
"outputMode": "auto"
}
'import requests
url = "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions"
payload = {
"intentName": "EXAMPLE_LIST_RECORDS",
"args": { "limit": 10 },
"outputMode": "auto"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({intentName: 'EXAMPLE_LIST_RECORDS', args: {limit: 10}, outputMode: 'auto'})
};
fetch('https://agentos.useparagon.com/api/tools/projects/{projectId}/executions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'intentName' => 'EXAMPLE_LIST_RECORDS',
'args' => [
'limit' => 10
],
'outputMode' => 'auto'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agentos.useparagon.com/api/tools/projects/{projectId}/executions"
payload := strings.NewReader("{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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://agentos.useparagon.com/api/tools/projects/{projectId}/executions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agentos.useparagon.com/api/tools/projects/{projectId}/executions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"intentName\": \"EXAMPLE_LIST_RECORDS\",\n \"args\": {\n \"limit\": 10\n },\n \"outputMode\": \"auto\"\n}"
response = http.request(request)
puts response.read_body{
"executionId": "exec_0123456789abcdef0123456789abcdef",
"engine": "declarative",
"status": "completed",
"startedAt": "2026-10-05T21:00:00.000Z",
"settledAt": "2026-10-05T21:00:01.200Z",
"durationMs": 1200,
"calls": [
{
"seq": 1,
"kind": "run",
"tool": "EXAMPLE_LIST_RECORDS",
"integration": "example",
"decision": "allowed",
"upstreamStatus": 200
}
],
"output": {
"inline": {
"records": []
}
}
}{
"executionId": "exec_0123456789abcdef0123456789abcdef",
"engine": "declarative",
"status": "running",
"startedAt": "2026-10-05T21:00:00.000Z",
"settledAt": null,
"durationMs": null,
"calls": []
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}{
"error": {
"code": "REQUEST_INVALID",
"message": "The request payload failed validation.",
"hint": "Correct the fields named in details and retry.",
"retryable": false,
"requestId": "req_01hxyz",
"details": [
{
"field": "query",
"issue": "query should not be empty"
}
]
}
}This endpoint can be used to call any Tool on behalf of your user.
You can find specific input parameters for a Tool you want to call in the Tools Reference, for example:
Each Tool in the Reference is an example call to this endpoint.
A stored response has
Output Modes
outputMode controls whether the provider body is returned on the execution or stored. When a Tool returns a large result (e.g. hundreds of CRM records), you can store the output server-side and receive a compact envelope instead of the full payload.
| Mode | Behavior |
|---|---|
inline | Returns the complete provider body on output.inline |
auto | Returns output.inline when the body is at most 4000 tokens. A body larger than 4000 tokens is stored. |
reference | Stores every body and returns output.resultId with output.stored. |
output.resultId and output.stored. output.inline is omitted.
Stored Result Envelope
output.storedis the envelope written with the stored body.output.resultId(also available asstored.resultId) is an ID beginning withres_that can be used to retrieve a stored result with Get Result or page through arecordsresult with Get Result Rows.
| Field | Meaning |
|---|---|
byteSize | Byte size of the stored value. |
tokenEstimate | Token count of the stored value. Same number as tokenBudget.fullOutputTokens. |
shape | records or text. A string body is text. An object array is records, including one nested under records, data, results, or items. Any other value is stored as JSON text. |
schema | Inferred schema for a records result. null for text, and null when the schema itself is larger than 4096 bytes. |
sample | Up to 3 records. Each object keeps at most 12 keys, and strings are truncated to 240 characters. Omitted for text, and omitted when the schema plus sample exceed 4096 bytes. |
recordCount | Number of records when shape is records. null for text. |
recordsPointer | JSON Pointer to the record array when shape is records. null for text. |
expiresAt | ISO timestamp, 86400 seconds after the result was stored. |
Authorizations
Your Paragon User Token (JWT), which you can generate using your project's signing keys.
Headers
Body
application/json
Response
The call settled within the Prefer wait.