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

All requests are authenticated through the use of an API key. Contact your account manager to get started with API access.

Additionally, requests are scoped to a specific workspace using the x-air-workspace-id header.

If you're using the SDK, pass these as constructor options or set the AIR_API_KEY and AIR_WORKSPACE_ID environment variables. For direct API requests, include these headers with every request:

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

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.

Code	Description
200 - OK	Request succeeded
201 - Created	New resource created successfully
204 - No Content	Request succeeded with no response body
400 - Bad Request	Invalid request. Check the response for details
401 - Unauthorized	Missing or invalid API key
403 - Forbidden	Valid credentials, but insufficient permissions
404 - Not Found	The requested resource doesn't exist
409 - Conflict	Request conflicts with current resource state
429 - Too Many Requests	You've hit the rate limit. Slow down and retry

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.