Getting Started with Air's API

Welcome, this guide and supporting docs will provide insight into how to programmatically manage assets, organize boards, and build workflows that scale with your team's creative output.

Choose your approach

There are three ways to work with Air's API:

• API SDK — The @air/api-sdk package is a typed TypeScript/JavaScript client that handles authentication, pagination, retries, and file uploads and imports for you. This is the recommended approach for most integrations.
• MCP Server — The @air/mcp package connects AI clients like Claude, Cursor, Windsurf, and ChatGPT directly to your Air workspace via the Model Context Protocol.
• Direct API requests — Make HTTP requests directly using any language or HTTP client. The rest of this guide covers the fundamentals you'll need for this approach.

Quick start with the SDK

import { AirApi } from "@air/api-sdk";

const air = new AirApi({
  apiKey: "your-api-key",
  workspaceId: "your-workspace-id",
});

const page = await air.boards.list();
console.log(page.data);

See the full API SDK guide for installation, configuration, and usage.

Authentication

Air supports two ways to authenticate Public API requests. Choose one per request; sending both is rejected.

API key (workspace-scoped). Contact your account manager to get started with API access. Most requests are also scoped to a specific workspace using the x-air-workspace-id header:

x-api-key: your_api_key_here
x-air-workspace-id: your_workspace_id

If you're using the SDK, pass these as constructor options or set the AIR_API_KEY and AIR_WORKSPACE_ID environment variables.

OAuth 2.0 bearer token. For integrations that act on behalf of a user or need access to more than one workspace, use the OAuth 2.0 Authorization Code + PKCE flow:

Authorization: Bearer your_access_token
x-air-workspace-id: your_workspace_id

GET /v1/workspaces is bearer-only and is the recommended entry point for OAuth integrations to discover which workspaces a user can access. See the OAuth guide for client provisioning, scopes, and the full flow.

Working with identifiers

All resource identifiers use the UUID v4 format. This includes id, assetId, boardId, customFieldId, and similar fields.

Example: 7a2b9e34-bb38-4747-a838-3ffc32fdf43d

Handling responses

Air uses conventional HTTP response codes to indicate success or failure.

All relevant response bodies are returned in JSON format.

Rate limits

To ensure reliable performance for all users, Air enforces these limits per API key:

• 15 requests per second
• 10 concurrent requests at any given time

When you exceed these limits, you'll receive a 429 status code with the message "Too Many Requests". Utilize exponential backoff starting at 1 second when you encounter rate limits. The SDK handles retries automatically with exponential backoff — see maxRetries for details.

Pagination

Many list endpoints support pagination to help you work within rate limits. Use the limit parameter to control how many items are returned (maximum 500 per request). The SDK supports auto-pagination with for await so you don't need to manage cursors manually.

Next steps

Now that you understand the basics:

• Using the SDK? Head to the API SDK guide for full resource documentation and code examples.
• Connecting an AI client? See the MCP Server guide to set up Claude, Cursor, Windsurf, or ChatGPT with your Air workspace.
• Using direct API requests? Explore the reference documentation to upload and organize creative assets, create and manage boards, add custom fields and tags, and build automated workflows for you and your team.