arcade-dev · Schema

Arcade Tool Execution

Schema for an Arcade tool execution request/response. Tool executions are the unit of work performed by the Arcade Engine on behalf of a user_id with user-scoped authorization.

Properties

Name	Type	Description
tool_name	string	Fully qualified tool name (Toolkit.Name@version) to execute.
user_id	string	Stable identifier of the end-user whose authorization tokens will be used. Required for user-scoped tool calls.
input	object	Input arguments conforming to the tool's input JSON Schema.
run_at	stringnull	Optional future time at which the tool should be executed. When set, the call is converted into a scheduled tool execution.
execution_id	string	Server-assigned identifier of the execution attempt (response field).
status	string	Lifecycle status of the execution.
output	object	Tool output. Present when status is completed.
error	object	Error details when status is failed.
started_at	string	When the execution started.
completed_at	string	When the execution finished.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/arcade-dev/main/json-schema/arcade-tool-execution-schema.json",
  "title": "Arcade Tool Execution",
  "description": "Schema for an Arcade tool execution request/response. Tool executions are the unit of work performed by the Arcade Engine on behalf of a user_id with user-scoped authorization.",
  "type": "object",
  "required": ["tool_name", "user_id"],
  "properties": {
    "tool_name": {
      "type": "string",
      "description": "Fully qualified tool name (Toolkit.Name@version) to execute.",
      "examples": ["[email protected]"]
    },
    "user_id": {
      "type": "string",
      "description": "Stable identifier of the end-user whose authorization tokens will be used. Required for user-scoped tool calls."
    },
    "input": {
      "type": "object",
      "description": "Input arguments conforming to the tool's input JSON Schema.",
      "additionalProperties": true
    },
    "run_at": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Optional future time at which the tool should be executed. When set, the call is converted into a scheduled tool execution."
    },
    "execution_id": {
      "type": "string",
      "description": "Server-assigned identifier of the execution attempt (response field)."
    },
    "status": {
      "type": "string",
      "enum": ["queued", "running", "completed", "failed", "needs_authorization"],
      "description": "Lifecycle status of the execution."
    },
    "output": {
      "type": "object",
      "description": "Tool output. Present when status is completed.",
      "additionalProperties": true
    },
    "error": {
      "type": "object",
      "description": "Error details when status is failed.",
      "properties": {
        "code": {"type": "string"},
        "message": {"type": "string"}
      }
    },
    "started_at": {"type": "string", "format": "date-time", "description": "When the execution started."},
    "completed_at": {"type": "string", "format": "date-time", "description": "When the execution finished."}
  },
  "additionalProperties": true
}