Arcade Python API Client

Common errors

• AttributeError: module 'arcadepy' has no attribute 'open_window'

  cause Attempting to use a function from the 'arcade' game development library with the 'arcadepy' API client library.
  fix This error indicates you've likely confused the 'arcadepy' API client with the 'arcade' game library. For game development, install and import 'arcade'. For API interaction, use the correct 'arcadepy' client methods like `client.tools.execute()`.

• arcadepy.APIConnectionError: Failed to connect to API

  cause The library was unable to establish a network connection to the Arcade API, possibly due to network issues, DNS problems, or incorrect API endpoint configuration.
  fix Check your internet connection, verify the API endpoint (if manually configured), and ensure there are no firewall rules blocking access to the Arcade API servers.

• arcadepy.APIStatusError: status_code=401, message='Unauthorized'

  cause The provided API key is invalid, expired, or missing, leading to an authentication failure with the Arcade API.
  fix Verify that your `ARCADE_API_KEY` environment variable is correctly set with a valid, active API key from your Arcade dashboard.

• arcadepy.APIStatusError: status_code=400, message='Bad Request'

  cause The request payload (e.g., `tool_name` or `input` parameters for `client.tools.execute`) does not conform to the expected API schema.
  fix Review the documentation for the specific Arcade tool you are calling and ensure all required parameters are provided with correct data types and formats.

Warnings

• gotcha Do not confuse 'arcadepy' (API client) with 'arcade' (game development library). They are distinct projects with different purposes and APIs.
  Fix: Always use 'arcadepy' for the API client. If you intended the game library, install 'arcade' instead.
• gotcha API keys should be managed securely using environment variables (e.g., ARCADE_API_KEY) or a .env file, rather than hardcoding them directly in your source code.
  Fix: Use `os.environ.get("ARCADE_API_KEY")` for client initialization and avoid embedding credentials.
• breaking While generally following SemVer, the library may introduce certain backwards-incompatible changes in minor versions, especially concerning static types or internal implementation details not expected to affect most runtime behavior.
  Fix: Review changelogs and API documentation for each minor version upgrade, especially if relying on intricate type hints or undocumented internals.
• gotcha For asynchronous usage, import `AsyncArcade` and use `await` with API calls. If using `aiohttp` for improved performance, install `arcadepy[aiohttp]` and explicitly pass `http_client=DefaultAioHttpClient()` to the `AsyncArcade` client.
  Fix: Ensure `AsyncArcade` is imported and `await` is used for async operations. Install `aiohttp` extra and configure client if desired.

Install

• pip install arcadepy Install core library
• pip install arcadepy[aiohttp] Install with aiohttp for enhanced async performance

Imports

• Arcade
  wrong:

  import arcadepy.Arcade

  correct:

  from arcadepy import Arcade

  The main synchronous client class is directly importable from the top-level package.
• AsyncArcade
  wrong:

  import arcadepy.AsyncArcade

  correct:

  from arcadepy import AsyncArcade

  The main asynchronous client class is directly importable from the top-level package.

Quickstart

Initializes the synchronous Arcade client using an API key from environment variables and demonstrates executing a sample tool. Ensure 'ARCADE_API_KEY' is set.

import os
from arcadepy import Arcade

# Ensure ARCADE_API_KEY is set in your environment variables
# e.g., export ARCADE_API_KEY="your_api_key_here"
client = Arcade(
    api_key=os.environ.get("ARCADE_API_KEY", "")
)

# Example: Execute a tool (replace with actual tool_name and input)
try:
    execute_tool_response = client.tools.execute(
        tool_name="Google.Search",
        input={
            "query": "latest news on AI models"
        },
        user_id="user@example.com", # Required for many tools requiring user context
    )
    print(f"Tool execution ID: {execute_tool_response.id}")
    print(f"Tool output: {execute_tool_response.output}")
except Exception as e:
    print(f"An error occurred: {e}")