API documentation

Public documentation · v1

Connect your applications to your AirDG forwarder account with an API key.

Contents
  1. Overview
  2. Quick start
  3. Authentication
  4. API keys
  5. Check the connection
  6. Mail threads
  7. AI usage
  8. Workspace
  9. Airlines
  10. API explorer
  11. Errors
  12. Request limits

Overview

Covers the account check (GET /api/v1/me), mail (Gmail and Alibaba Mail), AI usage, the workspace and airlines; until your company is verified, only the workspace, country and verification operations answer. Not included: document checks, quotations, bookings, rate requests and published timetables.

Quick start

  1. In your workspace, open API and create a key. Copy it now — it is shown only once. Open API keys · Forwarder sign-in required
  2. Send a request from your server:
    Request · curl
    curl --request GET "https://airdg.ai/api/v1/me" \
      --header "Authorization: Bearer <YOUR_API_KEY>"
  3. A 200 response with your account means the key works.

Authentication

Send your forwarder API key in server-to-server requests over HTTPS; Google OAuth is not needed.

Send the key in the Authorization header:

Header
Authorization: Bearer <YOUR_API_KEY>

Reads also accept the forwarder owner's website session (authentication: session, not api_key); changes need a key. A shipper session is not permitted, nor a manager's.

A key cannot sign in, manage keys or connect a mailbox — use the website for those.

API keys

Each key reaches the whole API for your own account, and no other.

  • Name the key and choose an expiry: 30, 90, 180 or 365 days.
  • Copy the key at once — it is shown only once, and AirDG keeps only its hash. Up to 5 active keys.
  • To rotate, create a replacement with the same name, then keep the old key up to 24 hours or revoke it now.
  • Revoking a key stops it immediately.

Open API keys · Forwarder sign-in required

Keep keys in your server's secret storage — never in URLs, browser code, localStorage, repositories or logs.

Check the connection

GET /api/v1/me

Returns the account behind the credential and how the request was authenticated.

Request · curl
curl --request GET "https://airdg.ai/api/v1/me" \
  --header "Authorization: Bearer <YOUR_API_KEY>"
Response · 200 · example
{
  "account": {
    "id": "00000000-0000-4000-8000-000000000001",
    "role": "forwarder"
  },
  "authentication": "api_key",
  "scopes": [
    "account:read"
  ]
}

scopes is always ["account:read"] — a fixed value kept for compatibility.

Mail threads

The Mail place's threads and actions; mailboxes are connected on the website. 403 for a non-forwarder session, 404 while mail is off.

MethodPathWhat it does
GET/api/v1/mailThe account's mailboxes with their settings and version; connected, limit (5 across both providers), mailbox (legacy) and processing (mail waiting on the AI service).
PUT/api/v1/mail/modeManual approval or automatic replies for one mailbox (mode, version, mailboxId).
PUT/api/v1/mail/one-tonne-minimumDeprecated: stored and returned, but controls nothing (enabled, version, mailboxId).
PUT/api/v1/mail/signatureThe signature under every new reply, adapted to its language (signature up to 1,000 characters and 12 lines, version, mailboxId). Until one is saved: a closing with the sender's name.
PUT/api/v1/mail/archive-after-replyMove answered messages out of the Inbox after AirDG replies; nothing is deleted (enabled, version, mailboxId; see archiveAccess).
GET/api/v1/mail/threadsThreads, latest activity first: mailboxId, state, q, archived, limit (≤ 50), cursor. Each has its mailbox, routing, archive and counts; a linked thread is not listed.
GET/api/v1/mail/threads/{threadId}One thread with its newest messages, replies, events and originals (each with a cursor), minimum, acknowledgement and sourceUrl (Gmail only).
GET/api/v1/mail/threads/{threadId}/messagesOlder messages: cursor, limit (≤ 50).
GET/api/v1/mail/threads/{threadId}/outboundOlder replies with their states: cursor, limit (≤ 50).
GET/api/v1/mail/threads/{threadId}/eventsOlder events: cursor, limit (≤ 50).
GET/api/v1/mail/threads/{threadId}/originalsThe current version of each original file, newest first, with its receipts and reading (content only, not a document check): cursor, limit (≤ 50).
GET/api/v1/mail/threads/{threadId}/attachments/{attachmentId}An original attachment, exactly as received.
PATCH/api/v1/mail/threads/{threadId}/draftEdit the draft text; recipients, subject and sender are fixed.
POST/api/v1/mail/threads/{threadId}/draft/approveApprove and send this draft version once; a legacy decline_underweight is 409.
POST/api/v1/mail/threads/{threadId}/draft/discardDiscard the draft; the thread pauses.
POST/api/v1/mail/threads/{threadId}/pausePause the thread.
POST/api/v1/mail/threads/{threadId}/resumeResume the thread. 409 when the correspondent is your own company (customer.own).
POST/api/v1/mail/threads/{threadId}/archiveArchive the thread (version): frozen and read-only until restored. 409 while a reply is being sent or unconfirmed.
POST/api/v1/mail/threads/{threadId}/restoreRestore the thread (version) as it was; nothing is sent and a new 30-day window starts.
POST/api/v1/mail/threads/{threadId}/linkLink a kept continuation into its conversation (version, intoThreadId, intoVersion; see link.candidates). Its messages and files move over; nothing is sent. Repeating returns the same result; a stale version on either side is 409 version_conflict.
POST/api/v1/mail/threads/{threadId}/outbound/{outboundId}/send-againAfter an unconfirmed delivery and a check of Sent: send once more.
POST/api/v1/mail/threads/{threadId}/outbound/{outboundId}/mark-sentMark an unconfirmed reply as sent — your statement, not the provider's.

Changes need an API key and a JSON body with the current version (stale: 409, nothing changes). Without mailboxId: 400 mailbox_required if there are several mailboxes, 409 mailbox_not_active if none is connected.

Example: approve and send a draft
curl --request POST "https://airdg.ai/api/v1/mail/threads/<THREAD_ID>/draft/approve" \
  --header "Authorization: Bearer <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"version": 1}'

The minimum is 1,000 kg chargeable weight, or the sender's agreement to pay as for 1,000 kg. A shipment stated under 1,000 kg, or with no weight stated plainly far lighter by the goods described, is offered this first; otherwise, with no weight stated, the minimum is not mentioned. A file AirDG cannot read (unsupported format, damaged or password-protected, over 25 MiB or an Office file over 3 MiB) is asked from the sender.

AI usage

The account's AI use in tokens, exactly as the model provider reports them, by function (mail_triage, mail_intake, company_verification). No prices, credits or limits.

MethodPathWhat it does
GET/api/v1/ai-usageTotals for a period: tokens, requests, attempts not fully known, by function, with the UTC window and when counting began.
GET/api/v1/ai-usage/historyThe period's attempts, newest first: cursor, limit (≤ 50); null where nothing was reported.

period is this_month, last_30_days or all; a cursor keeps its window. Earlier use is not estimated.

Summary request
curl --request GET "https://airdg.ai/api/v1/ai-usage?period=this_month" \
  --header "Authorization: Bearer <YOUR_API_KEY>"

Partial or lost reports are kept but not counted; a duplicate counts once. Token counts are integers up to 2^53 − 1.

Workspace

The workspace's country, airports, company verification and managers.

MethodPathWhat it does
GET/api/v1/workspaceThe country and its choices, airports, verification, airportLimit and airportAllowance (setupLeft, changesLeft, canAdd, nextChangeAt).
PUT/api/v1/workspace/countrySet the country, or null to clear; a change clears the airports. Locked once verified (409 country_locked).
GET/api/v1/workspace/verificationThe verification: state (unverified, checking, verified, expired), company, document, verifiedAt, verifiedUntil, attempt and attemptsLeft.
POST/api/v1/workspace/verificationUpload the country's document (202) — AE: GCAA DG certificate (freight forwarder); HK: CAD Regulated Agent registration; GB: UK Regulated Agent approval; CN: business licence with air freight forwarding in scope. One PDF, JPEG, PNG or WEBP up to 10 MiB as multipart/form-data with Content-Length; read back until attempt.state is not checking. A rejected check leaves a verified workspace as it was. 409 verification_in_progress, 429 verification_limit (5 per 24 hours), 409 verification_unavailable.
PUT/api/v1/workspace/airportsReplace the set with IATA codes of the workspace's country; empty clears (400 invalid_codes, 409 no_country). At most 5 (400 too_many_airports). The first five additions are the setup; then 5 additions per 30 days, re-adds included (409 airport_changes_exhausted, with nextChangeAt). Removing is free.
GET/api/v1/airportsA country's current airports (country required), by city, with the total; search filters by code, name or city.
GET/api/v1/workspace/usersManagers and invitations, history included: invited, active or removed.
POST/api/v1/workspace/usersInvite a manager by email (202); they join at their first sign-in. An address that is yours, already registered or already invited is refused. At most 20 invitations an hour (429).
DELETE/api/v1/workspace/users/{memberId}Withdraw an invitation or remove a manager; their sessions end at once. Unknown id: 404.

Until the company is verified, only GET /api/v1/workspace, PUT /api/v1/workspace/country and the two verification operations answer; the rest is 403 verification_required.

Example: set the workspace's airports
curl --request PUT "https://airdg.ai/api/v1/workspace/airports" \
  --header "Authorization: Bearer <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"codes": ["DXB", "DWC", "SHJ"]}'

Airlines

Airlines that departed from the workspace's airports in 14 full UTC days up to yesterday (the day before until 02:00 UTC), with your partners and rate instructions. Schedules come from actual departures, kept at most 30 days.

MethodPathWhat it does
GET/api/v1/airlinesAirlines at one airport or all, most departures first (airport, search, relationship). gate (no_country, no_airports) explains an empty list; flightData (whether flight data is collected for the workspace), coverage (per airport: complete, collecting, progress, loading) and collection (delayed, since) report the data; failed days are retried at least every 6 hours. Reading it queues the window's missing days for collection.
GET/api/v1/airlines/{icao}One airline; with airport, its timetable there by destination (destination keeps one): via, days (a late departure counts on its due day), dates, collected, the usual take-off with delays left out (departs), aircraft, category and loading, plus partners and instructions. 400: not the workspace's airport; 404: not found.
POST/api/v1/airlines/{icao}/partnersAdd a partner (201): airport and name required; email, phone, notes and active optional. 400 invalid_partner names the refused fields (no control characters, except line breaks and tabs in notes); nothing is sent to the partner.
PUT/api/v1/airlines/{icao}/partners/{partnerId}Change the given fields; active alone is the on/off switch; empty or null clears email, phone or notes. Another airline's or workspace's partner: 404.
DELETE/api/v1/airlines/{icao}/partners/{partnerId}Remove the partner; they can be added again.
PUT/api/v1/airlines/{icao}/instructionsSave rate instructions for one airport (airport; rateInstructions: plain text up to 8,000 characters, line breaks and tabs allowed; empty clears). 400 invalid_instructions. Not used yet.

A partner change returns the partner with partners, activePartners and working.

Example: add a partner at Emirates
curl --request POST "https://airdg.ai/api/v1/airlines/UAE/partners" \
  --header "Authorization: Bearer <YOUR_API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"airport": "DWC", "name": "Al Noor Cargo Services", "email": "rates@alnoor-cargo.example"}'

API explorer

API explorer

GET /api/v1/me

Authorize once with your API key, then run any operation. The key stays in this page's memory and goes only to airdg.ai, in the Authorization header.

The API explorer needs JavaScript.

Errors

Errors return JSON with one error code. A 401 adds WWW-Authenticate; a 429 adds Retry-After.

StatusErrorMeaning
400invalid_requestambiguous_credentialsmailbox_requiredown_addressinvalid_codestoo_many_airportsemptyinvalid_partnerinvalid_instructionsUnknown parameter or field, an invalid value, or a Bearer key sent with a session cookie.
401unauthorizedNo valid credential: missing, invalid, expired or revoked.
403forbiddenverification_requiredThe account, session or feature does not allow it. verification_required: the workspace's company is not verified.
404not_foundNot found for this account, or mail is off.
405method_not_allowedWrong method; the Allow header names the right one.
409version_conflictstate_conflictmailbox_not_activeno_countrycountry_lockedcountry_changedverification_in_progressverification_unavailableairport_changes_exhaustedalready_registeredalready_invitedStale version, wrong state or reading not active for the mailbox — read it again. country_locked: the workspace is verified; verification_in_progress: a check is running.
413too_largeThe body, draft or file (over 10 MiB) is too large.
415unsupported_typeThe file is not a PDF, JPEG, PNG or WEBP.
429rate_limitedverification_limitToo many requests — wait the Retry-After seconds. verification_limit: 5 checks per 24 hours used (see retryAt).
503unavailableTemporarily unavailable; the request is not confirmed.
Error body · example
{
  "error": "unauthorized"
}

Request limits

  • 60 requests per account per minute, shared by its keys and website session.
  • Key changes on the website: 10 per account per minute.
  • A known key with a wrong secret counts toward its account; an unknown key gets 401 and counts nowhere.

On a 429, wait for Retry-After.