API Key Management

Endpoints

Method	Path	Description
`GET`	`/api/keys/validate`	Check if a key is active and retrieve its metadata
`GET`	`/api/keys/usage`	Get monthly usage history for a key
`GET`	`/api/keys/create`	Create a new API key (admin only)

Validate a key

Check whether an API key is valid and retrieve its metadata.

Request

string

required

The API key to validate.

Response

boolean

true if the key is active, false otherwise.

string

The first 14 characters of the key (safe to display/log).

string

Label assigned to the key when it was created.

integer

Maximum number of API calls per calendar month.

integer

Number of calls made in the current calendar month.

integer

Total API calls made with this key across all time.

string

ISO 8601 timestamp of when the key was created.

Example

curl "https://app.airrating.io/api/keys/validate?api_key=YOUR_API_KEY"

{
  "valid": true,
  "prefix": "ar_live_xxxxxx",
  "name": "My Integration",
  "monthly_limit": 1000,
  "month_count": 42,
  "total_requests": 387,
  "created_at": "2026-01-15T10:30:00Z"
}

Get usage history

Returns current-month usage and up to 24 months of historical usage for your key.

Request

string

required

Your API key.

integer

Filter history to a specific year (optional).

integer

Filter history to a specific month, 1–12 (optional).

Response

string

Key prefix identifier.

string

Key label.

object

Usage for the current calendar month.

Show current_month fields

integer

Current year.

integer

Current month (1–12).

integer

Calls made so far this month.

integer

Monthly call limit.

string

Always "current".

array

Past months, up to 24 entries, most recent first.

Show History entry

integer

Year.

integer

Month (1–12).

integer

Total calls in that month.

integer

Limit at that time.

float

Percentage of limit consumed.

string

ISO 8601 timestamp when the record was logged.

string

Always "historical".

integer

Cumulative total calls across all months.

Example

curl "https://app.airrating.io/api/keys/usage?api_key=YOUR_API_KEY"

{
  "key_prefix": "ar_live_xxxxxx",
  "name": "My Integration",
  "current_month": {
    "year": 2026,
    "month": 4,
    "requests": 87,
    "monthly_limit": 1000,
    "period": "current"
  },
  "history": [
    {
      "year": 2026,
      "month": 3,
      "requests": 312,
      "monthly_limit": 1000,
      "usage_pct": 31.2,
      "logged_at": "2026-04-01T00:05:00Z",
      "period": "historical"
    }
  ],
  "total_requests_all_time": 399
}

Create a key

This endpoint is restricted to admin use during private beta. It is not available to general API users.

Creates a new API key and stores it in the database.

Request

string

required

A label for the key (e.g. company name or integration name).

string

required

Contact email associated with the key.

integer

default:"100"

Maximum API calls per calendar month.

Response

string

The newly created API key. Store this immediately — it cannot be retrieved again.

string

The first 14 characters (safe reference).

integer

Monthly request limit.

string

Reminder to save the key.

Example

{
  "api_key": "ar_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "prefix": "ar_live_xxxxxx",
  "monthly_limit": 100,
  "message": "Save this key — it will NOT be shown again."
}

​Endpoints

​Validate a key

​Request

​Response

​Example

​Get usage history

​Request

​Response

​Example

​Create a key

​Request

​Response

​Example

Endpoints

Validate a key

Request

Response

Example

Get usage history

Request

Response

Example

Create a key

Request

Response

Example