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`](https://developer.air.inc/page/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`](https://developer.air.inc/page/mcp-server) 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  
```ts
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](https://developer.air.inc/page/air-api-sdk) 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:

```shell
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:

```shell
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](https://developer.air.inc/page/public-api-oauth) 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.

| 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 credentials |
| 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`](https://developer.air.inc/page/air-api-sdk#configuration) 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](https://developer.air.inc/page/air-api-sdk#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](https://developer.air.inc/page/air-api-sdk) for full resource documentation and code examples.
- **Connecting an AI client?** See the [MCP Server guide](https://developer.air.inc/page/mcp-server) 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.