{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent OS Tools API",
    "version": "1.0.0",
    "description": "Enable your agent to take action in 130+ different apps with Agent OS Tools."
  },
  "servers": [
    {
      "url": "https://agentos.useparagon.com",
      "description": "Production US Cloud"
    },
    {
      "url": "https://agentos.eu.paragon.so",
      "description": "Production EU Cloud"
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys."
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "projectId",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      }
    },
    "schemas": {
      "SideEffect": {
        "type": "string",
        "enum": ["read", "write", "delete", "send", "unknown"]
      },
      "ModelTool": {
        "type": "object",
        "required": ["type", "function"],
        "properties": {
          "type": { "type": "string", "enum": ["function"] },
          "function": {
            "type": "object",
            "required": ["name", "description", "parameters"],
            "properties": {
              "name": { "type": "string" },
              "description": { "type": "string" },
              "parameters": { "type": "object", "additionalProperties": true }
            }
          }
        }
      },
      "ToolDescriptor": {
        "type": "object",
        "required": [
          "intentName",
          "integration",
          "sideEffect",
          "approvalRequired",
          "schemaSource",
          "tool"
        ],
        "properties": {
          "intentName": { "type": "string" },
          "integration": { "type": "string" },
          "sideEffect": { "$ref": "#/components/schemas/SideEffect" },
          "approvalRequired": { "type": "boolean" },
          "schemaSource": { "type": "string", "enum": ["static", "hydrated"] },
          "tool": { "$ref": "#/components/schemas/ModelTool" }
        }
      },
      "ToolSearchRequest": {
        "type": "object",
        "required": ["query"],
        "additionalProperties": false,
        "properties": {
          "query": { "type": "string", "minLength": 1, "maxLength": 1024 },
          "topK": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 8
          },
          "maxToolTokens": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "integrations": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string" }
          },
          "categories": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string" }
          },
          "maxSideEffect": {
            "type": "string",
            "enum": ["read", "write", "delete", "send"]
          },
          "connectedOnly": { "type": "boolean", "default": false },
          "rerank": {
            "type": "boolean",
            "default": true,
            "description": "Opt out only. true cannot enable reranking when the deployment has it off."
          }
        }
      },
      "ToolSearchResponse": {
        "type": "object",
        "required": ["tools", "searchQuery", "errors", "usage"],
        "properties": {
          "tools": {
            "type": "array",
            "items": {
              "allOf": [
                { "$ref": "#/components/schemas/ToolDescriptor" },
                {
                  "type": "object",
                  "required": ["relevancy"],
                  "properties": { "relevancy": { "type": "number" } }
                }
              ]
            }
          },
          "searchQuery": { "type": "string" },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["integration", "code", "message"],
              "properties": {
                "integration": { "type": "string" },
                "code": { "type": "string" },
                "message": { "type": "string" }
              }
            }
          },
          "usage": {
            "type": "object",
            "required": [
              "strategy",
              "candidates",
              "returned",
              "toolTokens",
              "omittedForBudget",
              "omittedForSideEffect",
              "hydratedIntegrations",
              "degraded",
              "visibility"
            ],
            "properties": {
              "strategy": {
                "type": "string",
                "enum": [
                  "hybrid",
                  "semantic_failed_open",
                  "lexical_failed_open"
                ]
              },
              "candidates": { "type": "integer" },
              "returned": { "type": "integer" },
              "toolTokens": { "type": "integer" },
              "omittedForBudget": { "type": "integer" },
              "omittedForSideEffect": { "type": "integer" },
              "hydratedIntegrations": {
                "type": "array",
                "items": { "type": "string" }
              },
              "degraded": {
                "oneOf": [
                  {
                    "type": "string",
                    "enum": ["lexical_only", "dense_only", "static_schema"]
                  },
                  { "type": "null" }
                ]
              },
              "visibility": {
                "type": "object",
                "required": [
                  "mode",
                  "entitledIntegrations",
                  "candidatesBeforeFilter",
                  "candidatesAfterFilter"
                ],
                "properties": {
                  "mode": { "type": "string", "enum": ["filtered"] },
                  "entitledIntegrations": { "type": "integer" },
                  "candidatesBeforeFilter": { "type": "integer" },
                  "candidatesAfterFilter": { "type": "integer" }
                }
              }
            }
          },
          "trace": {
            "type": "object",
            "description": "Present only when diagnostics=1.",
            "properties": {
              "totalMs": { "type": "number" },
              "steps": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": { "type": "string" },
                    "durationMs": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      },
      "CreateExecutionRequest": {
        "type": "object",
        "required": ["intentName"],
        "additionalProperties": false,
        "properties": {
          "intentName": { "type": "string", "minLength": 1, "maxLength": 512 },
          "args": { "type": "object", "additionalProperties": true },
          "timeoutMs": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 120000,
            "default": 60000
          },
          "outputMode": {
            "type": "string",
            "enum": ["inline", "auto", "reference"],
            "default": "auto"
          }
        }
      },
      "ExecutionResource": {
        "type": "object",
        "required": [
          "executionId",
          "engine",
          "status",
          "startedAt",
          "settledAt",
          "durationMs",
          "calls"
        ],
        "properties": {
          "executionId": { "type": "string" },
          "engine": { "type": "string", "enum": ["declarative"] },
          "status": {
            "type": "string",
            "enum": ["running", "completed", "failed", "timeout", "cancelled"]
          },
          "startedAt": { "type": "string", "format": "date-time" },
          "settledAt": {
            "oneOf": [
              { "type": "string", "format": "date-time" },
              { "type": "null" }
            ]
          },
          "durationMs": { "oneOf": [{ "type": "number" }, { "type": "null" }] },
          "deadlineMs": { "type": "number" },
          "killed": { "type": "boolean" },
          "cancelledBy": { "type": "string", "enum": ["operator"] },
          "calls": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "seq",
                "kind",
                "tool",
                "integration",
                "decision",
                "upstreamStatus"
              ],
              "properties": {
                "seq": { "type": "integer" },
                "kind": { "type": "string", "enum": ["run"] },
                "tool": { "type": "string" },
                "integration": { "type": "string" },
                "decision": {
                  "type": "string",
                  "enum": ["allowed", "denied_scope", "denied_rate", "expired"]
                },
                "upstreamStatus": {
                  "oneOf": [{ "type": "integer" }, { "type": "null" }]
                }
              }
            }
          },
          "output": {
            "type": "object",
            "properties": {
              "inline": {},
              "resultId": { "type": "string" },
              "stored": { "$ref": "#/components/schemas/StoredResult" }
            }
          }
        }
      },
      "StoredResult": {
        "type": "object",
        "required": [
          "resultId",
          "executionId",
          "tool",
          "integration",
          "byteSize",
          "tokenEstimate",
          "shape",
          "expiresAt",
          "tokenBudget"
        ],
        "properties": {
          "resultId": { "type": "string" },
          "executionId": { "type": "string" },
          "tool": { "type": "string" },
          "integration": { "type": "string" },
          "byteSize": { "type": "integer" },
          "tokenEstimate": { "type": "integer" },
          "shape": { "type": "string", "enum": ["records", "text"] },
          "recordCount": {
            "oneOf": [{ "type": "integer" }, { "type": "null" }]
          },
          "recordsPointer": {
            "oneOf": [{ "type": "string" }, { "type": "null" }]
          },
          "totalChars": {
            "oneOf": [{ "type": "integer" }, { "type": "null" }]
          },
          "schema": {},
          "sample": {},
          "expiresAt": { "type": "string", "format": "date-time" },
          "tokenBudget": {
            "type": "object",
            "required": ["fullOutputTokens", "returnedTokens", "savedTokens"],
            "properties": {
              "fullOutputTokens": { "type": "integer" },
              "returnedTokens": { "type": "integer" },
              "savedTokens": { "type": "integer" }
            }
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint", "retryable", "requestId"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "hint": { "type": "string" },
              "retryable": { "type": "boolean" },
              "retryAfterMs": { "type": "integer" },
              "requestId": { "type": "string" },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["field", "issue"],
                  "properties": {
                    "field": { "type": "string" },
                    "issue": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error envelope.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" },
            "example": {
              "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" }
                ]
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/tools/projects/{projectId}/tools/search": {
      "post": {
        "operationId": "searchTools",
        "summary": "Search Tools",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "diagnostics",
            "in": "query",
            "schema": { "type": "string", "enum": ["1"] }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ToolSearchRequest" },
              "example": {
                "query": "list open issues",
                "topK": 8,
                "connectedOnly": true,
                "maxSideEffect": "read"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked tools.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolSearchResponse" },
                "example": {
                  "tools": [
                    {
                      "intentName": "EXAMPLE_LIST_RECORDS",
                      "integration": "example",
                      "sideEffect": "read",
                      "approvalRequired": false,
                      "schemaSource": "static",
                      "relevancy": 1,
                      "tool": {
                        "type": "function",
                        "function": {
                          "name": "EXAMPLE_LIST_RECORDS",
                          "description": "List records.",
                          "parameters": {
                            "type": "object",
                            "properties": { "limit": { "type": "integer" } }
                          }
                        }
                      }
                    }
                  ],
                  "searchQuery": "list open issues",
                  "errors": [],
                  "usage": {
                    "strategy": "hybrid",
                    "candidates": 4,
                    "returned": 1,
                    "toolTokens": 120,
                    "omittedForBudget": 0,
                    "omittedForSideEffect": 0,
                    "hydratedIntegrations": [],
                    "degraded": null,
                    "visibility": {
                      "mode": "filtered",
                      "entitledIntegrations": 2,
                      "candidatesBeforeFilter": 4,
                      "candidatesAfterFilter": 1
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/tools/{intentName}": {
      "get": {
        "operationId": "getTool",
        "summary": "Get Tool",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "intentName",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool descriptor.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ToolDescriptor" },
                "example": {
                  "intentName": "EXAMPLE_LIST_RECORDS",
                  "integration": "example",
                  "sideEffect": "read",
                  "approvalRequired": false,
                  "schemaSource": "static",
                  "tool": {
                    "type": "function",
                    "function": {
                      "name": "EXAMPLE_LIST_RECORDS",
                      "description": "List records.",
                      "parameters": { "type": "object", "properties": {} }
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/executions": {
      "post": {
        "operationId": "createExecution",
        "summary": "Run Tool",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "Prefer",
            "in": "header",
            "schema": { "type": "string", "example": "wait=25" },
            "description": "RFC 7240 wait. Default 25 seconds. wait=0 returns 202 immediately."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "schema": { "type": "string" },
            "description": "Stored on the row. Not used to replay an earlier execution."
          },
          {
            "name": "x-paragon-credential",
            "in": "header",
            "schema": { "type": "string" },
            "description": "Forwarded as the execution credential. Omit to send none."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateExecutionRequest"
              },
              "example": {
                "intentName": "EXAMPLE_LIST_RECORDS",
                "args": { "limit": 10 },
                "outputMode": "auto"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The call settled within the Prefer wait.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExecutionResource" },
                "example": {
                  "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": [] } }
                }
              }
            }
          },
          "202": {
            "description": "Still running. Location is the execution URL. Retry-After is 1.",
            "headers": {
              "Location": { "schema": { "type": "string" } },
              "Retry-After": { "schema": { "type": "string", "example": "1" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExecutionResource" },
                "example": {
                  "executionId": "exec_0123456789abcdef0123456789abcdef",
                  "engine": "declarative",
                  "status": "running",
                  "startedAt": "2026-10-05T21:00:00.000Z",
                  "settledAt": null,
                  "durationMs": null,
                  "calls": []
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/executions/{executionId}": {
      "get": {
        "operationId": "getExecution",
        "summary": "Get Execution",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "executionId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "Prefer",
            "in": "header",
            "schema": { "type": "string" },
            "description": "wait=<seconds>, capped at 25. Absent means do not wait."
          }
        ],
        "responses": {
          "200": {
            "description": "Current execution resource.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExecutionResource" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/executions/{executionId}/cancel": {
      "post": {
        "operationId": "cancelExecution",
        "summary": "Cancel Execution",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "executionId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "The execution was already settled.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExecutionResource" }
              }
            }
          },
          "202": {
            "description": "The running execution was cancelled.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ExecutionResource" },
                "example": {
                  "executionId": "exec_0123456789abcdef0123456789abcdef",
                  "engine": "declarative",
                  "status": "cancelled",
                  "startedAt": "2026-10-05T21:00:00.000Z",
                  "settledAt": "2026-10-05T21:00:02.000Z",
                  "durationMs": 2000,
                  "cancelledBy": "operator",
                  "calls": []
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/results/{resultId}": {
      "get": {
        "operationId": "getResult",
        "summary": "Get Result",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "resultId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Stored result envelope.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/StoredResult" },
                "example": {
                  "resultId": "res_0123456789abcdef0123456789abcdef",
                  "executionId": "exec_0123456789abcdef0123456789abcdef",
                  "tool": "EXAMPLE_LIST_RECORDS",
                  "integration": "example",
                  "byteSize": 42,
                  "tokenEstimate": 20,
                  "shape": "records",
                  "recordCount": 1,
                  "recordsPointer": "/records",
                  "totalChars": null,
                  "schema": { "type": "object" },
                  "expiresAt": "2026-10-06T21:00:00.000Z",
                  "tokenBudget": {
                    "fullOutputTokens": 20,
                    "returnedTokens": 12,
                    "savedTokens": 8
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/results/{resultId}/rows": {
      "get": {
        "operationId": "getResultRows",
        "summary": "Get Result Rows",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "resultId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "pointer",
            "in": "query",
            "schema": { "type": "string" },
            "description": "RFC 6901 JSON Pointer. Must start with /."
          },
          {
            "name": "select",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Comma-separated fields, at most 32."
          },
          {
            "name": "where",
            "in": "query",
            "schema": { "type": "array", "items": { "type": "string" } },
            "style": "form",
            "explode": true,
            "description": "Repeatable filter in the format field:operator:value, at most 8. Clauses are combined with AND. field is a top-level record key. Operators (lowercase): eq, ne, gt, gte, lt, lte, contains, exists. Everything after the second colon is the value, and exists takes no value. Example: status:eq:open."
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "continuationToken",
            "in": "query",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data", "paging", "matched", "tokenBudget"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "additionalProperties": true
                      }
                    },
                    "paging": {
                      "type": "object",
                      "required": ["pageSize", "continuationToken"],
                      "properties": {
                        "pageSize": { "type": "integer" },
                        "continuationToken": {
                          "oneOf": [{ "type": "string" }, { "type": "null" }]
                        }
                      }
                    },
                    "matched": { "type": "integer" },
                    "tokenBudget": {
                      "type": "object",
                      "required": [
                        "fullOutputTokens",
                        "returnedTokens",
                        "savedTokens"
                      ],
                      "properties": {
                        "fullOutputTokens": { "type": "integer" },
                        "returnedTokens": { "type": "integer" },
                        "savedTokens": { "type": "integer" }
                      }
                    }
                  }
                },
                "example": {
                  "data": [{ "id": "1", "name": "Open issue" }],
                  "paging": { "pageSize": 50, "continuationToken": null },
                  "matched": 1,
                  "tokenBudget": {
                    "fullOutputTokens": 20,
                    "returnedTokens": 8,
                    "savedTokens": 12
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/tools/projects/{projectId}/results/{resultId}/content": {
      "get": {
        "operationId": "getResultContent",
        "summary": "Get Result Content",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "resultId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "startChar",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          {
            "name": "maxChars",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 20000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A character slice of a text result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "startChar",
                    "endChar",
                    "totalChars",
                    "text",
                    "nextStartChar",
                    "tokenBudget"
                  ],
                  "properties": {
                    "startChar": { "type": "integer" },
                    "endChar": { "type": "integer" },
                    "totalChars": { "type": "integer" },
                    "text": { "type": "string" },
                    "nextStartChar": {
                      "oneOf": [{ "type": "integer" }, { "type": "null" }]
                    },
                    "tokenBudget": {
                      "type": "object",
                      "required": [
                        "fullOutputTokens",
                        "returnedTokens",
                        "savedTokens"
                      ],
                      "properties": {
                        "fullOutputTokens": { "type": "integer" },
                        "returnedTokens": { "type": "integer" },
                        "savedTokens": { "type": "integer" }
                      }
                    }
                  }
                },
                "example": {
                  "startChar": 0,
                  "endChar": 11,
                  "totalChars": 11,
                  "text": "hello world",
                  "nextStartChar": null,
                  "tokenBudget": {
                    "fullOutputTokens": 3,
                    "returnedTokens": 3,
                    "savedTokens": 0
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  }
}
