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.

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.

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.

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).

Next steps

Now that you understand the basics, explore the reference documentation to:

Upload and organize creative assets
Create and manage boards
Add custom fields and tags
Build automated workflows for your team