Skip to main content

Tool API

The Tool API allows you to execute custom tools that you've built in the Autessa platform. Tools can be executed synchronously for immediate results or via WebSocket for real-time streaming output.

All Tool API requests require the resourceId query parameter set to your tool ID and an Authorization header with your API key.

Base URL​

REST API:   https://api.autessa.com/clients/tool
WebSocket:  wss://api.autessa.com/ws/clients/tools/execute

Authentication​

HTTP REST APIs​

Pass your API key in the Authorization header (no "Bearer" prefix):

Authorization: your_api_key_here

WebSocket APIs​

Pass your API key as a query parameter:

authorization=your_api_key_here
curl https://api.autessa.com/clients/tool/execute?resourceId=456 \
  -H "Authorization: your_api_key" \
  -H "Content-Type: application/json"

REST API Endpoints​

Execute Tool POST/execute​

Executes a tool synchronously and returns the complete result. This endpoint waits for the tool execution to complete before returning.

Query Parameters​

  • Name
    resourceId
    Type
    integer
    Description

    The ID of the tool to execute.

Request Body​

  • Name
    toolId
    Type
    integer
    Description

    The ID of the tool to execute.

  • Name
    variables
    Type
    object
    Description

    Public variables (input parameters) for the tool. Key-value pairs where values can be any JSON type.

  • Name
    privateVariables
    Type
    object
    Description

    Private variables that won't be exposed in the output or logs.

  • Name
    environmentVariables
    Type
    object
    Description

    Environment variables that won't be stored on the server. Useful for secrets.

  • Name
    version
    Type
    CustomVersion
    Description

    Optional version override. If not specified, uses the PUBLISHED version.

Response​

  • Name
    responseType
    Type
    string
    Description

    Always "EXECUTE_TOOL" for tool responses.

  • Name
    toolName
    Type
    string
    Description

    Name of the tool that was executed.

  • Name
    result
    Type
    any
    Description

    The result data from the tool execution. Can be any JSON structure.

  • Name
    publicVars
    Type
    object
    Description

    Public variables returned by the tool.

  • Name
    debuggingInfo
    Type
    object
    Description

    Debugging information including success status, logs, and final response.

  • Name
    errors
    Type
    array<string>
    Description

    Array of error messages if any occurred.

  curl --request POST \
    --url 'https://api.autessa.com/clients/tool/execute?resourceId=456' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: your_api_key' \
    --data '{
      "toolId": 456,
      "variables": {
        "city": "Seattle",
        "state": "WA"
      },
      "environmentVariables": {
        "API_KEY": "secret_key"
      }
    }'
  {
    "responseType": "EXECUTE_TOOL",
    "toolName": "GetWeather",
    "result": "It is 65 degrees Fahrenheit with partly cloudy skies",
    "publicVars": {
      "city": "Seattle",
      "state": "WA"
    },
    "debuggingInfo": {
      "success": true,
      "finalResponse": "It is 65 degrees Fahrenheit with partly cloudy skies",
      "logs": [
        "[2025-01-29 15:23:41.123] [LOG] Fetching weather data...",
        "[2025-01-29 15:23:42.456] [LOG] Weather data retrieved successfully"
      ]
    },
    "errors": []
  }

WebSocket API​

Stream Tool Execution WSS/ws/clients/tools/execute​

Real-time tool execution with streaming output. Allows you to receive intermediate results and debugging messages as the tool executes.

Connection URL​

wss://api.autessa.com/ws/clients/tools/execute?authorization={key}&resourceId={toolId}

Query Parameters​

  • Name
    authorization
    Type
    string
    Description

    Your API key.

  • Name
    resourceId
    Type
    integer
    Description

    The tool ID.

Connection Lifecycle​

  1. Connect - WebSocket connection established
  2. Send Message - Client sends tool execution request
  3. Receive Streams - Server streams execution messages in real-time
  4. Final Result - Server sends final execution result
  5. Disconnect - Connection closes after execution completes
websocat "wss://api.autessa.com/ws/clients/tools/execute?authorization=your_api_key&resourceId=456"

Client-to-Server Message​

Send a JSON message to execute the tool:

  • Name
    toolId
    Type
    integer
    Description

    The tool ID to execute

  • Name
    variables
    Type
    object
    Description

    Public variables (input parameters)

  • Name
    privateVariables
    Type
    object
    Description

    Private variables

  • Name
    environmentVariables
    Type
    object
    Description

    Environment variables

  • Name
    version
    Type
    CustomVersion
    Description

    Version override

JSON
{
  "toolId": 456,
  "variables": {
    "city": "Seattle",
    "state": "WA"
  },
  "privateVariables": {},
  "environmentVariables": {
    "API_KEY": "secret_key"
  }
}

Server-to-Client Messages​

The server sends multiple messages during tool execution:

1. Execution Start​

Sent when the tool begins executing:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "invocationId": "inv_abc123",
  "publicVars": {
    "city": "Seattle",
    "state": "WA"
  },
  "streamMessage": "EXECUTION START: GetWeather"
}

2. Variables Preview​

Shows the public variables being used:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "invocationId": "inv_abc123",
  "streamMessage": "EXECUTION VARIABLES: {\"city\":\"Seattle\",\"state\":\"WA\"}"
}

3. Custom Stream Messages​

Any custom messages your tool sends via console.log or stream APIs:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "invocationId": "inv_abc123",
  "streamMessage": "Fetching weather data from API..."
}

4. Execution End​

Sent when the tool finishes executing:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "invocationId": "inv_abc123",
  "streamMessage": "EXECUTION END: GetWeather"
}

5. Execution Result Preview​

Preview of the tool's return value:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "invocationId": "inv_abc123",
  "streamMessage": "EXECUTION RESULT: \"It is 65 degrees Fahrenheit with partly cloudy skies\""
}

6. Final Result​

The complete execution result with debugging info:

JSON
{
  "responseType": "EXECUTE_TOOL",
  "toolName": "GetWeather",
  "result": "It is 65 degrees Fahrenheit with partly cloudy skies",
  "publicVars": {
    "city": "Seattle",
    "state": "WA"
  },
  "debuggingInfo": {
    "success": true,
    "finalResponse": "It is 65 degrees Fahrenheit with partly cloudy skies",
    "logs": [
      "[2025-01-29 15:23:41.123] [LOG] Fetching weather data...",
      "[2025-01-29 15:23:42.456] [LOG] Weather data retrieved successfully"
    ]
  }
}

Built-in Stream Message Prefixes​

The Tool API uses built-in prefixes for system messages. Avoid using these prefixes in your custom stream messages:

  • Name
    EXECUTION START
    Description

    Sent when tool execution begins

  • Name
    EXECUTION VARIABLES
    Description

    Shows the public variables being used

  • Name
    EXECUTION END
    Description

    Sent when tool execution completes

  • Name
    EXECUTION RESULT
    Description

    Preview of the tool's return value

Custom Version​

Override the default PUBLISHED version of a tool:

  • Name
    versionState
    Type
    string
    Description

    Version state: "PUBLISHED", "DRAFT", or "ARCHIVED". Defaults to "PUBLISHED".

  • Name
    versionNumber
    Type
    integer
    Description

    Specific version number to use (optional).

{
  "toolId": 456,
  "version": {
    "versionState": "DRAFT"
  },
  "variables": {...}
}

Variables Guide​

Public Variables​

Public variables are the main input parameters for your tool. They are:

  • Visible in debugging output
  • Logged for monitoring and evaluation
  • Returned in the publicVars field

Use these for normal input parameters like IDs, search queries, etc.

Private Variables​

Private variables are not exposed in outputs or logs. Use these for:

  • Intermediate values you want to pass
  • Data that should not be logged
  • Internal processing parameters

Note: Private variables are still visible during execution, just not in logs.

Environment Variables​

Environment variables are not stored on the server. Use these for:

  • API keys and secrets
  • Credentials
  • Temporary configuration values

Important: Environment variables are passed with each request and never persisted.

Rate Limiting​

Tool execution endpoints are rate limited. Rate limit information is included in response headers:

  • X-RateLimit-Limit-Minute - Requests allowed per minute
  • X-RateLimit-Remaining-Minute - Remaining requests this minute
  • X-RateLimit-Limit-Day - Requests allowed per day
  • X-RateLimit-Remaining-Day - Remaining requests today

When rate limited, you'll receive a 429 status code with a Retry-After header.

Complete Examples​

Simple Tool Execution​

async function executeTool(toolId, variables) {
  const response = await fetch(
    `https://api.autessa.com/clients/tool/execute?resourceId=${toolId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'your_api_key'
      },
      body: JSON.stringify({
        toolId,
        variables
      })
    }
  );

  const data = await response.json();

  if (data.errors && data.errors.length > 0) {
    throw new Error(data.errors.join(', '));
  }

  return data.result;
}

// Usage
const weather = await executeTool(456, {
  city: 'Seattle',
  state: 'WA'
});

console.log(weather);
// Output: "It is 65 degrees Fahrenheit with partly cloudy skies"

Streaming Tool Execution​

function executeToolStreaming(toolId, variables) {
  return new Promise((resolve, reject) => {
    const ws = new WebSocket(
      `wss://api.autessa.com/ws/clients/tools/execute?authorization=your_api_key&resourceId=${toolId}`
    );

    const streamMessages = [];
    let finalResult = null;

    ws.onopen = () => {
      ws.send(JSON.stringify({
        toolId,
        variables
      }));
    };

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);

      // Collect stream messages
      if (data.streamMessage) {
        console.log('Stream:', data.streamMessage);
        streamMessages.push(data.streamMessage);
      }

      // Final result
      if (data.result !== undefined) {
        finalResult = data.result;
        ws.close();
      }
    };

    ws.onclose = () => {
      resolve({
        result: finalResult,
        streamMessages
      });
    };

    ws.onerror = (error) => {
      reject(error);
    };
  });
}

// Usage
const { result, streamMessages } = await executeToolStreaming(456, {
  city: 'Seattle',
  state: 'WA'
});

console.log('Final result:', result);
console.log('Stream messages:', streamMessages);

Tool with Environment Variables​

JavaScript
async function executeToolWithSecrets(toolId, variables, secrets) {
  const response = await fetch(
    `https://api.autessa.com/clients/tool/execute?resourceId=${toolId}`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'your_api_key'
      },
      body: JSON.stringify({
        toolId,
        variables,
        environmentVariables: secrets
      })
    }
  );

  const data = await response.json();
  return data.result;
}

// Usage - secrets are never logged
const result = await executeToolWithSecrets(
  456,
  { city: 'Seattle', state: 'WA' },
  { WEATHER_API_KEY: 'secret_key_123' }
);

Error Handling​

Always check for errors in the response:

JavaScript
const response = await fetch(
  'https://api.autessa.com/clients/tool/execute?resourceId=456',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'your_api_key'
    },
    body: JSON.stringify({
      toolId: 456,
      variables: { city: 'Seattle' }
    })
  }
);

const data = await response.json();

if (data.errors && data.errors.length > 0) {
  console.error('Tool execution failed:', data.errors);
  // Handle error
} else {
  console.log('Result:', data.result);
  // Handle success
}

Best Practices​

Security​

  • Use environmentVariables for API keys and secrets
  • Never log sensitive data in stream messages
  • Rotate API keys regularly

Performance​

  • Use WebSocket for long-running tools that benefit from streaming
  • Use REST API for quick, simple tool executions
  • Implement exponential backoff for retries

Debugging​

  • Check debuggingInfo for detailed execution logs
  • Use stream messages to provide progress updates
  • Monitor rate limit headers to avoid throttling

Error Handling​

  • Always check the errors array
  • Check debuggingInfo.success for execution status
  • Implement proper error handling for network failures