{"openapi":"3.1.1","info":{"title":"AirDG API","version":"1.0.0","description":"AirDG's forwarder API for mail, AI usage, the workspace and airlines; reads take a key or the owner's website session, changes a key. Until the company is verified, most operations answer 403 verification_required."},"servers":[{"url":"https://airdg.ai"}],"paths":{"/api/v1/me":{"get":{"operationId":"verifyApiAccess","summary":"Verify forwarder API access","description":"Returns the account behind the credential. Send the key as Authorization: Bearer <key> from your server; 60 requests per account per minute.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"responses":{"200":{"description":"Access verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Access"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail":{"get":{"operationId":"getMailboxes","summary":"The account's mailboxes","description":"Every mailbox of the account, disconnected ones included, with settings and version; processing says whether new mail waits on the AI service.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"responses":{"200":{"description":"The mailboxes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/mode":{"put":{"operationId":"setMailMode","summary":"Manual approval or automatic replies","description":"Sets one mailbox's reply mode. Automatic sends only questions, document requests, answers, the air-freight-only note, the payable-minimum offer and the acknowledgement; manual turns unsent automatic replies into drafts.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModeChange"}}}},"responses":{"200":{"description":"The mailbox with its new mode and version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/one-tonne-minimum":{"put":{"operationId":"setMailOneTonneMinimum","summary":"Legacy 1-tonne setting (deprecated)","deprecated":true,"description":"Deprecated: stored and returned as oneTonneMinimum; it controls nothing, except that turning it off withdraws unsent legacy decline_underweight replies. A shipment under the minimum is offered it first, before any document request.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneTonneChange"}}}},"responses":{"200":{"description":"The mailbox with its new setting and version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/signature":{"put":{"operationId":"setMailSignature","summary":"The mailbox's signature under replies","description":"Sets one mailbox's reply signature (up to 1,000 characters and 12 lines; empty for none). Each reply carries it in the reply's language.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignatureChange"}}}},"responses":{"200":{"description":"The mailbox with its new signature and version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/archive-after-reply":{"put":{"operationId":"setMailArchiveAfterReply","summary":"Move the answered conversation out of the Inbox","description":"When on, the messages AirDG answered leave the Inbox once its reply is sent; nothing is deleted. Off by default; see archiveAccess.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveAfterReplyChange"}}}},"responses":{"200":{"description":"The mailbox with its new setting and version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads":{"get":{"operationId":"listMailThreads","summary":"Freight-request threads","description":"Threads by latest activity, up to 50 per page (default 20); continue with nextCursor under the same filters (another filter refuses it, 400). counts gives active threads per state, plus archived. A linked thread is neither listed nor counted (its messages are in its conversation).","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"mailboxId","in":"query","required":false,"description":"A mailbox id from GET /api/v1/mail; another account's id is 404.","schema":{"type":"string","format":"uuid"}},{"name":"state","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ThreadState"}},{"name":"archived","in":"query","required":false,"description":"true: the Archive (archived by a person or after the 30-day active window); false or omitted: active threads.","schema":{"type":"boolean"}},{"name":"q","in":"query","required":false,"description":"The sender's address or the subject contains this text (case-insensitive; % _ and \\ are literal).","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"One page of threads","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}":{"get":{"operationId":"getMailThread","summary":"One thread","description":"The thread with the newest page of messages (50), replies (20), events (20) and current originals (50); older pages via messagesNext, outboundNext, eventsNext and originalsNext.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/messages":{"get":{"operationId":"listMailThreadMessages","summary":"Older messages of a thread","description":"Messages older than the cursor, as plain text with attachment metadata. Up to 50 per page; continue with nextCursor.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessagePage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/outbound":{"get":{"operationId":"listMailThreadReplies","summary":"Older replies of a thread","description":"AirDG's replies older than the cursor, with their states. Up to 50 per page; continue with nextCursor.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/events":{"get":{"operationId":"listMailThreadEvents","summary":"Older events of a thread","description":"The thread's events older than the cursor. Up to 50 per page; continue with nextCursor.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/originals":{"get":{"operationId":"listMailThreadOriginals","summary":"The current original files of a thread","description":"The current version of each original file, newest first, up to 50 per page. reading describes content, not whether a document is required or valid.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"One page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OriginalPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/attachments/{attachmentId}":{"get":{"operationId":"downloadMailAttachment","summary":"An original attachment","description":"The file exactly as received, as a download.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"attachmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The original file","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/draft":{"patch":{"operationId":"editMailDraft","summary":"Edit the draft text","description":"Edits the draft's text; recipient, subject and sender are fixed. A legacy decline_underweight cannot be edited (409 state_conflict).","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftEdit"}}}},"responses":{"200":{"description":"The edited draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/draft/approve":{"post":{"operationId":"approveMailDraft","summary":"Approve and send","description":"Queues this draft version for sending; repeating returns the same send. An unconfirmed delivery is never retried automatically; a legacy decline_underweight is 409.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the draft's version"},"responses":{"202":{"description":"Queued for sending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/draft/discard":{"post":{"operationId":"discardMailDraft","summary":"Discard the draft","description":"Discards the draft and pauses the thread.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the draft's version"},"responses":{"200":{"description":"The paused thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadSummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/pause":{"post":{"operationId":"pauseMailThread","summary":"Pause processing in a thread","description":"Pauses processing in this thread until it is resumed.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the thread's version"},"responses":{"200":{"description":"The paused thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadSummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/resume":{"post":{"operationId":"resumeMailThread","summary":"Resume processing in a thread","description":"Processes a paused thread again in the current reply mode, replacing its draft; nothing sent is resent. Other states and your own company's correspondence: 409.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the thread's version"},"responses":{"202":{"description":"Processing resumed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadSummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/archive":{"post":{"operationId":"archiveMailThread","summary":"Archive a thread","description":"Moves the thread to the Archive: nothing is analysed or sent until it is restored, and a queued reply becomes a draft. Refused while a delivery is in flight or unconfirmed; the draft's version changes, so an earlier approval or edit is 409.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the thread's version"},"responses":{"200":{"description":"The archived thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadSummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/restore":{"post":{"operationId":"restoreMailThread","summary":"Restore a thread from the Archive","description":"Restores the thread as it was, with a new 30-day window; its draft needs a fresh approval. Mail received meanwhile is not processed until the sender writes again; a thread archived during its analysis returns paused for review (restored_unanalysed).","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the thread's version"},"responses":{"200":{"description":"The restored thread","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadSummaryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/link":{"post":{"operationId":"linkMailThread","summary":"Link a continuation into its conversation","description":"Moves a thread held for review, with its messages and files, into the conversation it continues (a target from link.candidates); nothing is sent, and repeating returns the same result. 409: version_conflict for a stale version on either side, mailbox_not_active for a stopped mailbox, else state_conflict.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkChange"}}},"description":"version: this thread's version; intoThreadId and intoVersion: the conversation to link into and its version."},"responses":{"202":{"description":"This thread as the link's record, and the conversation it went into","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/outbound/{outboundId}/send-again":{"post":{"operationId":"sendMailReplyAgain","summary":"Send again after an unconfirmed delivery","description":"Sends an unconfirmed reply once more after you checked your Sent folder (checkedSent: true); repeating returns the same send. A legacy decline_underweight is 409.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"outboundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAgain"}}}},"responses":{"202":{"description":"Queued for sending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/mail/threads/{threadId}/outbound/{outboundId}/mark-sent":{"post":{"operationId":"markMailReplySent","summary":"Mark an unconfirmed reply as sent","description":"Records your statement that the reply was sent; it is not the provider's confirmation.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"outboundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionChange"}}},"description":"version: the reply's version"},"responses":{"200":{"description":"The reply, marked as sent by you","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/ai-usage":{"get":{"operationId":"getAiUsage","summary":"AI usage of the account for a period","description":"Tokens the provider reported in full for one UTC period, with the attempts not fully known (not counted) and a breakdown by function.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsagePeriod"}}],"responses":{"200":{"description":"The summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/ai-usage/history":{"get":{"operationId":"listAiUsage","summary":"AI usage history of the account","description":"The period's attempts, newest first, up to 50 per page (default 20). A cursor keeps its first page's window; a malformed or foreign cursor is 400.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"period","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsagePeriod"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"One page of attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageHistory"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/MailForbidden"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace":{"get":{"operationId":"getWorkspace","summary":"The workspace's country and airports","description":"The country and its choices, airports, airportLimit and airportAllowance, and the company verification. Answers while the workspace is closed.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"responses":{"200":{"description":"The workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Workspace"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace/country":{"put":{"operationId":"setWorkspaceCountry","summary":"The country the workspace works from","description":"Sets the country (null: none); a change clears the airports and, while unverified, the company standing. Answered while closed; locked once verified (409 country_locked).","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryChange"}}}},"responses":{"200":{"description":"The change and the workspace after it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceChange"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/WorkspaceConflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace/verification":{"get":{"operationId":"getCompanyVerification","summary":"The workspace's company verification","description":"The verification state, company name and document number, validity, latest check and uploads left. Answers while the workspace is closed.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"responses":{"200":{"description":"The standing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResponse"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"submitCompanyVerification","summary":"Upload the company's document for verification","description":"Uploads the country's document (see document) — one PDF, JPEG, PNG or WEBP up to 10 MiB, with Content-Length — and starts the check; poll GET until attempt.state is not checking. At most 5 uploads per 24 hours; a rejected check leaves a verified workspace as it was.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/VerificationUpload"}}}},"responses":{"202":{"description":"Stored; the check has started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResponse"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/WorkspaceConflict"},"413":{"$ref":"#/components/responses/TooLarge"},"415":{"$ref":"#/components/responses/UnsupportedType"},"429":{"$ref":"#/components/responses/VerificationLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace/airports":{"put":{"operationId":"setWorkspaceAirports","summary":"The airports the workspace works from","description":"Replaces the set with IATA codes of the workspace's country (empty clears), at most 5 airports (too_many_airports). After the first five additions, 5 per 30 days, re-adding included (airport_changes_exhausted); removing is free. Duplicates are folded; a refused set saves nothing.","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportsChange"}}}},"responses":{"200":{"description":"The change and the workspace after it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportsChangeResponse"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/WorkspaceConflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airports":{"get":{"operationId":"listAirports","summary":"Airports of a country","description":"The country's current airports, by city then code, with their total.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"country","in":"query","required":true,"description":"One of the countries a workspace may choose.","schema":{"$ref":"#/components/schemas/CountryCode"}},{"name":"search","in":"query","required":false,"description":"Code, name or city contains this text (case-insensitive; English or any interface language).","schema":{"type":"string","maxLength":60}}],"responses":{"200":{"description":"The airports","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirportList"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace/users":{"get":{"operationId":"listWorkspaceUsers","summary":"The workspace's managers and invitations","description":"Every manager and invitation in the order made, removed ones included, with the invitation e-mail's state.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"responses":{"200":{"description":"The users","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUsers"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"post":{"operationId":"inviteWorkspaceUser","summary":"Invite a manager","description":"Invites the address by e-mail; the person joins at their first sign-in with it (Google or e-mail code, no password). At most 20 invitations an hour (429).","security":[{"apiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invitation"}}}},"responses":{"202":{"description":"The invitation is queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationResponse"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"409":{"$ref":"#/components/responses/WorkspaceConflict"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/workspace/users/{memberId}":{"delete":{"operationId":"removeWorkspaceUser","summary":"Withdraw an invitation or remove a manager","description":"Withdraws an open invitation, or removes a manager and ends their sessions now. The row stays as history; the address can be invited again.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"memberId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemovedUser"}}}},"400":{"$ref":"#/components/responses/WorkspaceBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/WorkspaceNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airlines":{"get":{"operationId":"listAirlines","summary":"The workspace's airlines of the last 14 days","description":"Airlines that departed from the workspace's airports in 14 full UTC days up to yesterday (the day before until 02:00 UTC), most departures first; failed days are retried at least every 6 hours. Reading it queues the window's missing days for collection.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"airport","in":"query","required":false,"description":"IATA code of one of the workspace's airports; omitted, all of them. Another airport is 400 invalid_request.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"search","in":"query","required":false,"description":"Every word must match the airline's name or code, or a destination's full IATA or ICAO code (case-insensitive).","schema":{"type":"string","maxLength":60}},{"name":"relationship","in":"query","required":false,"description":"all (default); active: at least one active partner; none: no active partner.","schema":{"type":"string","enum":["all","active","none"],"default":"all"}}],"responses":{"200":{"description":"The airlines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirlineList"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airlines/{icao}":{"get":{"operationId":"getAirline","summary":"One airline with schedule, partners and instructions","description":"One airline with the workspace's partners. With airport: its timetable from that airport, built from actual take-offs with delays left out, and the rate instructions there.","security":[{"apiKeyBearer":[]},{"websiteSession":[]}],"parameters":[{"name":"icao","in":"path","required":true,"description":"The airline's ICAO designator (three letters, any case).","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"airport","in":"query","required":false,"description":"IATA code of one of the workspace's airports; omitted, all of them. Another airport is 400 invalid_request.","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"destination","in":"query","required":false,"description":"One destination (IATA, else ICAO): the schedule keeps only it, the summary stays whole. Malformed: 400 invalid_request.","schema":{"type":"string","pattern":"^[A-Za-z0-9]{3,4}$"}}],"responses":{"200":{"description":"The airline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirlineDetail"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airlines/{icao}/partners":{"post":{"operationId":"addAirlinePartner","summary":"Add a partner at an airline","description":"Adds a contact at this airline at one of the workspace's airports; active defaults to true. Nothing is sent to the partner.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"icao","in":"path","required":true,"description":"The airline's ICAO designator (three letters, any case).","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerInput"}}}},"responses":{"201":{"description":"The partner and the airline's new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerResponse"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airlines/{icao}/partners/{partnerId}":{"put":{"operationId":"updateAirlinePartner","summary":"Change a partner or its Active switch","description":"Changes only the fields given; null or an empty text clears email, phone or notes, not the name. An airline is working while one of its partners is active.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"icao","in":"path","required":true,"description":"The airline's ICAO designator (three letters, any case).","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"partnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerChange"}}}},"responses":{"200":{"description":"The partner and the airline's new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerResponse"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}},"delete":{"operationId":"removeAirlinePartner","summary":"Remove a partner","description":"Removes the partner; nothing is sent to them, and they can be added again.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"icao","in":"path","required":true,"description":"The airline's ICAO designator (three letters, any case).","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}},{"name":"partnerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Removed, with the airline's new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRemoved"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}},"/api/v1/airlines/{icao}/instructions":{"put":{"operationId":"setAirlineInstructions","summary":"How to request rates from an airline","description":"Saves how to request rates from this airline at one airport: plain text up to 8,000 characters, empty clears. Not used yet; nothing is sent to a partner or an airline.","security":[{"apiKeyBearer":[]}],"parameters":[{"name":"icao","in":"path","required":true,"description":"The airline's ICAO designator (three letters, any case).","schema":{"type":"string","pattern":"^[A-Za-z]{3}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionsChange"}}}},"responses":{"200":{"description":"The saved instructions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstructionsResponse"}}}},"400":{"$ref":"#/components/responses/AirlinesBadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/AirlinesNotFound"},"405":{"$ref":"#/components/responses/MailMethodNotAllowed"},"413":{"$ref":"#/components/responses/TooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Unavailable"}}}}},"components":{"securitySchemes":{"apiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"AirDG API key","description":"A secret key from the workspace's API page, for server-side use only."},"websiteSession":{"type":"apiKey","in":"cookie","name":"__Host-airdg-session","description":"The workspace owner's HttpOnly website session; a manager's session is refused with 403. Integrations use the Bearer key."}},"schemas":{"UsagePeriod":{"type":"string","enum":["this_month","last_30_days","all"],"default":"this_month","description":"this_month: since the first of the current UTC month; last_30_days: the last 30 × 24 hours; all: since counting began."},"UsageSummary":{"type":"object","required":["period","timezone","from","to","since","tokens","requests","undetermined","byFeature"],"properties":{"period":{"$ref":"#/components/schemas/UsagePeriod"},"timezone":{"type":"string","const":"UTC"},"from":{"type":["string","null"],"format":"date-time"},"to":{"type":"string","format":"date-time","description":"End of the window (inclusive): when this page, or the first page of a cursor, was read."},"since":{"type":["string","null"],"format":"date-time","description":"When counting began for this account; earlier use is not counted. null until then."},"tokens":{"type":"integer","format":"int64","description":"Tokens of the attempts reported in full."},"requests":{"type":"integer","description":"Attempts reported in full."},"undetermined":{"type":"object","required":["pending","incomplete","unavailable"],"description":"Attempts with unknown usage, not counted: pending, incomplete or unavailable.","properties":{"pending":{"type":"integer"},"incomplete":{"type":"integer"},"unavailable":{"type":"integer"}}},"byFeature":{"type":"array","items":{"type":"object","required":["feature","operation","requests","tokens"],"properties":{"feature":{"type":"string","description":"mail_intake (email analysis), mail_triage (request check) or company_verification."},"operation":{"type":"string","description":"analysis, triage, read_document or read_registry."},"requests":{"type":"integer"},"tokens":{"type":"integer","format":"int64"}}}}},"example":{"period":"this_month","timezone":"UTC","from":"2026-10-01T00:00:00.000Z","to":"2026-10-08T12:00:00.000Z","since":"2026-10-08T06:30:00.000Z","tokens":1500,"requests":1,"undetermined":{"pending":0,"incomplete":0,"unavailable":0},"byFeature":[{"feature":"mail_intake","operation":"analysis","requests":1,"tokens":1500}]}},"UsageEntry":{"type":"object","required":["id","at","feature","operation","resource","status","tokens","note","reportedAt"],"description":"One attempt, exactly as the provider reported it.","properties":{"id":{"type":"string","format":"uuid"},"at":{"type":"string","format":"date-time","description":"When the attempt began."},"feature":{"type":"string"},"operation":{"type":"string"},"resource":{"type":["object","null"],"required":["type","id","title","available"],"properties":{"type":{"type":"string","description":"mail_thread or company_verification."},"id":{"type":"string","format":"uuid"},"title":{"type":["string","null"],"description":"The thread's subject while it exists; otherwise null."},"available":{"type":"boolean"}}},"status":{"type":"string","enum":["pending","reported","incomplete","unavailable","duplicate"],"description":"reported is counted; pending (no answer yet), incomplete, unavailable and duplicate are not."},"tokens":{"type":"object","required":["input","output","total","cachedInput","cacheWrite","reasoning"],"description":"As reported; null where nothing was reported. cachedInput and cacheWrite are part of input, reasoning part of output. Integers up to 2^53 − 1.","properties":{"input":{"type":["integer","null"],"format":"int64"},"output":{"type":["integer","null"],"format":"int64"},"total":{"type":["integer","null"],"format":"int64"},"cachedInput":{"type":["integer","null"],"format":"int64"},"cacheWrite":{"type":["integer","null"],"format":"int64"},"reasoning":{"type":["integer","null"],"format":"int64"}}},"note":{"type":["string","null"],"description":"Why the attempt is not reported, as a short code."},"reportedAt":{"type":["string","null"],"format":"date-time"}}},"UsageHistory":{"type":"object","required":["period","timezone","from","to","entries","nextCursor"],"properties":{"period":{"$ref":"#/components/schemas/UsagePeriod"},"timezone":{"type":"string","const":"UTC"},"from":{"type":["string","null"],"format":"date-time"},"to":{"type":"string","format":"date-time","description":"End of the window (inclusive): when this page, or the first page of a cursor, was read."},"entries":{"type":"array","items":{"$ref":"#/components/schemas/UsageEntry"}},"nextCursor":{"type":["string","null"],"maxLength":200}}},"Access":{"type":"object","additionalProperties":false,"required":["account","authentication","scopes"],"properties":{"account":{"type":"object","additionalProperties":false,"required":["id","role"],"properties":{"id":{"type":"string","format":"uuid"},"role":{"type":"string","const":"forwarder"}}},"authentication":{"type":"string","enum":["api_key","session"]},"scopes":{"type":"array","description":"A fixed legacy value: always [\"account:read\"]; not a permission you choose.","items":{"type":"string","const":"account:read"},"minItems":1,"maxItems":1}},"example":{"account":{"id":"00000000-0000-4000-8000-000000000001","role":"forwarder"},"authentication":"api_key","scopes":["account:read"]}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"string"}}},"ThreadState":{"type":"string","enum":["analyzing","draft_ready","sending","awaiting_sender","declined","underweight","collected","paused"],"description":"analyzing; draft_ready: awaits approval; sending: sending or unconfirmed; awaiting_sender; declined: not air freight; collected: documents complete — the sender's new email is still answered (only noted if the acknowledgement was discarded or refused); paused: see pauseReason; underweight: legacy."},"Mailbox":{"type":"object","additionalProperties":false,"required":["id","provider","email","displayName","signature","signatureSource","readMarking","archiveAfterReply","archiveAccess","status","statusReason","mode","oneTonneMinimum","readingSince","version","connected","connectedAt","disconnectedAt","threads","listening"],"properties":{"id":{"type":"string","format":"uuid","description":"The mailbox's stable id, kept through a reconnect."},"provider":{"type":"string","enum":["google","aliyun"],"description":"google (Gmail API) or aliyun (Alibaba Mail over IMAP and SMTP)."},"email":{"type":"string","format":"email"},"displayName":{"type":["string","null"],"description":"The verified sender name from the provider; null while unknown (Alibaba Mail has none)."},"signature":{"type":"string","maxLength":1000,"description":"The saved signature added under new replies (empty: none); set with PUT /api/v1/mail/signature."},"signatureSource":{"type":"string","enum":["default","custom"],"description":"default: never set — a closing with displayName, or nothing; custom: set by the account."},"readMarking":{"type":"string","enum":["on","needs_permission"],"description":"on: AirDG marks a message read once it answers it; needs_permission: a Google grant without gmail.modify — reconnect the mailbox."},"archiveAfterReply":{"type":"boolean","description":"true: once AirDG's reply is sent, the answered conversation leaves the Inbox; nothing is deleted. Off by default."},"archiveAccess":{"type":"string","enum":["on","needs_permission","unsupported"],"description":"on; needs_permission: reconnect the Google mailbox to grant gmail.modify; unsupported: this Alibaba Mail server cannot move messages."},"status":{"type":"string","enum":["active","access_lost","stopped"]},"statusReason":{"type":["string","null"],"description":"Why the mailbox is stopped: not_started, disconnected, not_allowed or another reason."},"mode":{"type":"string","enum":["manual","automatic"]},"oneTonneMinimum":{"type":"boolean","deprecated":true,"description":"Deprecated: stored and returned, controls nothing. Off by default."},"readingSince":{"type":["string","null"],"format":"date-time","description":"When reading started; null if never."},"version":{"type":"integer","minimum":1},"connected":{"type":"boolean","description":"Connected now; false: disconnected, kept as history with its threads."},"connectedAt":{"type":"string","format":"date-time"},"disconnectedAt":{"type":["string","null"],"format":"date-time"},"threads":{"type":"integer","minimum":0,"description":"The mailbox's threads, active and archived."},"listening":{"oneOf":[{"$ref":"#/components/schemas/MailboxListening"},{"type":"null"}],"description":"The IMAP listener of an aliyun mailbox; null for google."}}},"MailboxListening":{"type":"object","additionalProperties":false,"required":["state","detail","since","lastEventAt"],"properties":{"state":{"type":"string","enum":["off","armed","connecting","listening","reconnecting","deferred","auth_failed"],"description":"armed, connecting, listening (IDLE), reconnecting, deferred (no capacity, waiting), auth_failed (reconnect with a new client password) or off."},"detail":{"type":["string","null"],"description":"A short code behind the state, e.g. polling, capacity, token_refused, network."},"since":{"type":["string","null"],"format":"date-time","description":"When the current session started."},"lastEventAt":{"type":["string","null"],"format":"date-time","description":"When the server last notified a change."}}},"MailboxList":{"type":"object","additionalProperties":false,"required":["mailboxes","connected","limit","mailbox","processing"],"properties":{"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/Mailbox"},"description":"Every mailbox of the account, history included."},"connected":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"description":"How many mailboxes may be connected at a time."},"mailbox":{"oneOf":[{"$ref":"#/components/schemas/Mailbox"},{"type":"null"}],"description":"The single connected mailbox, else null."},"processing":{"type":"object","additionalProperties":false,"required":["delayed","waiting","since","error"],"properties":{"delayed":{"type":"boolean"},"waiting":{"type":"integer","minimum":0,"description":"Emails waiting because the AI service failed twice or more in a row"},"since":{"type":["string","null"],"format":"date-time","description":"When the AI service began failing; null if unknown"},"error":{"type":["string","null"],"description":"The last failure as a short label, e.g. \"429\" or \"timeout\"; null if unknown"}},"description":"Whether new mail is held up by the AI service; AirDG retries by itself."}}},"MailboxResponse":{"type":"object","additionalProperties":false,"required":["mailbox"],"properties":{"mailbox":{"$ref":"#/components/schemas/Mailbox"}}},"ThreadSummary":{"type":"object","additionalProperties":false,"required":["id","subject","customer","mailbox","routing","state","pauseReason","reviewCode","processing","flags","archive","counts","missing","lastActivityAt","version"],"properties":{"id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"customer":{"type":"object","additionalProperties":false,"required":["email","own"],"properties":{"email":{"type":"string","format":"email"},"own":{"type":"boolean","description":"true: the correspondent is your own company (one of your mailboxes or domains); AirDG never answers such a thread, and Resume is refused (409)."}}},"mailbox":{"type":"object","additionalProperties":false,"required":["id","email"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"}},"description":"The mailbox that received and answers this thread."},"routing":{"oneOf":[{"type":"object","additionalProperties":false,"required":["responseMailbox","standing"],"properties":{"responseMailbox":{"type":"object","additionalProperties":false,"required":["id","email"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"}}},"standing":{"type":"string","enum":["to","cc","not_visible"]}}},{"type":"null"}],"description":"Set on a paused copy: the same email reached another of your mailboxes, which answers it (responseMailbox); null otherwise."},"state":{"$ref":"#/components/schemas/ThreadState"},"pauseReason":{"type":["string","null"],"enum":["human_reply","operator","draft_discarded","unexpected_participant","review",null],"description":"human_reply: you or a colleague replied; operator: paused by you; draft_discarded; unexpected_participant: someone else wrote; review: see reviewCode."},"reviewCode":{"type":["string","null"],"description":"Why a person must decide (pauseReason review). A free string; new values may appear — see examples.","examples":["unclear_request","followup_without_thread","new_request_in_thread","copy","copy_unverified","own_sender","model_failed","model_unavailable","not_a_request","message_unreadable","expired","mailbox_stopped","delivery_rejected","signature_not_adapted","signature_changed","acknowledgement_missing","repeated_reply","reply_contains_link","answer_missing","missing_reply_draft","linked","restored_unanalysed","input_too_large"]},"processing":{"type":"boolean","description":"Still being checked; may disappear if it is not a freight request."},"flags":{"type":"object","additionalProperties":false,"required":["deliveryUnconfirmed","newMailSince","deletionNoticeAt","deletesAt","archivesAt","archiveNoticeAt","suspected"],"properties":{"deliveryUnconfirmed":{"type":"boolean","description":"A reply's delivery is unconfirmed: check your Sent folder, then send-again or mark-sent. Never resent automatically."},"newMailSince":{"type":["string","null"],"format":"date-time"},"deletionNoticeAt":{"type":"null","deprecated":true,"description":"Deprecated: always null. See archiveNoticeAt."},"deletesAt":{"type":"null","deprecated":true,"description":"Deprecated: always null. See archivesAt."},"archivesAt":{"type":["string","null"],"format":"date-time","description":"When AirDG archives an active thread: 30 days after the start of collection or the last restore. null once archived."},"archiveNoticeAt":{"type":["string","null"],"format":"date-time","description":"From day 25 of the active window: when the archive notice applies; null before and once archived."},"suspected":{"type":"boolean"}}},"archive":{"oneOf":[{"type":"object","additionalProperties":false,"required":["archivedAt","reason"],"properties":{"archivedAt":{"type":"string","format":"date-time"},"reason":{"type":"string","enum":["person","retention"],"description":"person: archived by you; retention: archived by AirDG at the end of the 30-day window."}}},{"type":"null"}],"description":"null while active. An archived thread is read-only (409 state_conflict) and nothing is sent until it is restored."},"counts":{"type":"object","additionalProperties":false,"required":["incoming","outgoing","outgoingByAirdg","outgoingByYou","unconfirmed","coverage","incomingCoverage"],"properties":{"incoming":{"type":"integer","minimum":0,"description":"Unique inbound messages from the sender and other participants (the sender's out-of-office replies are not kept); a lower bound unless incomingCoverage is observed."},"outgoing":{"type":"integer","minimum":0,"description":"Replies that went out: outgoingByAirdg + outgoingByYou; a resent reply counts once. A lower bound unless coverage is observed."},"outgoingByAirdg":{"type":"integer","minimum":0,"description":"AirDG's replies that went out, one per reply however often it was resent."},"outgoingByYou":{"type":"integer","minimum":0,"description":"Your own replies from the mail client in this thread; a lower bound unless coverage is observed."},"coverage":{"type":"string","enum":["observed","partial","unknown"],"description":"observed: your sent mail for this thread was read in full; partial or unknown: outgoingByYou and outgoing are lower bounds."},"incomingCoverage":{"type":"string","enum":["observed","partial","unknown"],"description":"observed: the inbox was read in full for this thread; partial or unknown: incoming is a lower bound."},"unconfirmed":{"type":"integer","minimum":0,"description":"Replies whose delivery is unknown, not counted in outgoing; resolve with send-again or mark-sent."}},"description":"The thread's counts as the Mail list shows them: received · sent · unconfirmed."},"missing":{"type":"array","items":{"type":"string"},"description":"What AirDG asked the sender for, as codes (e.g. invoice, packing_list, sds, minimum_agreement), or the names of unreadable files."},"lastActivityAt":{"type":"string","format":"date-time"},"version":{"type":"integer","minimum":1}}},"Minimum":{"type":"object","additionalProperties":false,"description":"1,000 kg chargeable weight, or the sender's agreement to pay as for 1,000 kg. A stated weight under 1,000 kg (chargeable, else gross or net), or with no weight stated goods plainly far lighter, is below: the option is offered first and alone, the documents only after the agreement.","required":["payableKg","status","basis","grossKg","netKg","chargeableKg","chargeableSource","agreement","offered","explained"],"properties":{"payableKg":{"type":"integer","description":"The payable minimum: 1000."},"status":{"type":"string","enum":["met","below","unknown","conflict"],"description":"conflict: weights contradict (all under 1,000 kg: below); met: agreed, or a stated weight of 1,000 kg or more; below: a stated weight under 1,000 kg (chargeable, else gross or net), or with no weight stated goods plainly far lighter, no agreement; unknown: no weight is stated and none is evident — the minimum is not mentioned."},"basis":{"type":["string","null"],"enum":["agreement","stated_chargeable","gross_lower_bound","net_lower_bound",null],"description":"Why the minimum counts as met; null otherwise."},"grossKg":{"type":["number","null"],"description":"The stated total gross weight (message or documents)."},"netKg":{"type":["number","null"],"description":"The stated total net weight: a lower bound of the gross and chargeable weight; null if none."},"chargeableKg":{"type":["number","null"],"description":"A chargeable weight the sender or documents stated; never computed."},"chargeableSource":{"type":["string","null"],"enum":["stated",null]},"agreement":{"type":"object","additionalProperties":false,"required":["state","payableKg","messageId","sequence","quote"],"description":"The sender's agreement, bound to its message; payableKg is the stated weight, never rounded up; quote is the sender's own words (untrusted).","properties":{"state":{"type":"string","enum":["none","asked","agreed","withdrawn"]},"payableKg":{"type":["number","null"]},"messageId":{"type":["string","null"],"description":"The provider's message id."},"sequence":{"type":["integer","null"],"description":"The message's customer sequence in the thread."},"quote":{"type":"string","maxLength":300}}},"offered":{"oneOf":[{"type":"object","additionalProperties":false,"required":["outboundId","at","state","standing","confirmedByGmail","latestOutboundId","latestState"],"properties":{"outboundId":{"type":"string","format":"uuid"},"at":{"type":"string","format":"date-time"},"state":{"type":["string","null"],"description":"That reply's own state, as in the replies list."},"standing":{"type":"string","enum":["none","pending","communicated","unconfirmed"],"description":"communicated (sent or in flight), unconfirmed (a person decides), pending (draft or queued) or none."},"confirmedByGmail":{"type":"boolean","description":"The provider accepted at least one send of the chain; Mark as sent does not count."},"latestOutboundId":{"type":["string","null"],"format":"uuid","description":"The newest resend of this reply; null if never resent."},"latestState":{"type":["string","null"],"description":"That resend's own state."}}},{"type":"null"}],"description":"The latest reply that offered the 1,000 kg basis, or null; its standing says whether it reached the sender."},"explained":{"oneOf":[{"type":"object","additionalProperties":false,"required":["outboundId","at","state","standing","confirmedByGmail","latestOutboundId","latestState"],"properties":{"outboundId":{"type":"string","format":"uuid"},"at":{"type":"string","format":"date-time"},"state":{"type":["string","null"],"description":"That reply's own state, as in the replies list."},"standing":{"type":"string","enum":["none","pending","communicated","unconfirmed"],"description":"communicated (sent or in flight), unconfirmed (a person decides), pending (draft or queued) or none."},"confirmedByGmail":{"type":"boolean","description":"The provider accepted at least one send of the chain; Mark as sent does not count."},"latestOutboundId":{"type":["string","null"],"format":"uuid","description":"The newest resend of this reply; null if never resent."},"latestState":{"type":["string","null"],"description":"That resend's own state."}}},{"type":"null"}],"description":"The reply that explained the minimum, or null; only the offer explains it. It counts only while that reply reached the sender."}}},"ThreadSummaryResponse":{"type":"object","additionalProperties":false,"required":["thread"],"properties":{"thread":{"$ref":"#/components/schemas/ThreadSummary"}}},"ThreadList":{"type":"object","additionalProperties":false,"required":["threads","nextCursor","counts"],"properties":{"threads":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/ThreadSummary"}},"nextCursor":{"type":["string","null"]},"counts":{"type":"object","additionalProperties":{"type":"integer"},"description":"Active threads per state under the same mailboxId and q, plus archived (always present)."}}},"Outbound":{"type":"object","additionalProperties":false,"required":["id","kind","origin","state","version","text","signature","recipient","cc","subject","approvedAt","approvedVia","approvedByYou","sentAt","confirmedByGmail","markedSentAt","failure","evidence","retryOf","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["ask","decline_non_air","decline_underweight","acknowledge"],"description":"ask: questions, document requests, answers or the minimum offer; decline_non_air: air freight only; acknowledge: complete set; decline_underweight: legacy, never sent again."},"origin":{"type":"string","enum":["manual","automatic"]},"state":{"type":"string","enum":["draft","queued","sending","sent","failed","ambiguous","discarded","superseded","marked_sent","retried"]},"version":{"type":"integer","minimum":1,"description":"The reply's version, named in Edit, Approve and Discard; unique within the thread."},"text":{"type":"string","maxLength":12000},"signature":{"type":"string","maxLength":1000,"description":"The signature this reply carries (empty: none), adapted to its language and sent as shown."},"recipient":{"type":"string","format":"email","description":"To: the thread's reply address (Reply-To, else From, of the first customer message)."},"cc":{"type":"array","maxItems":10,"items":{"type":"string","format":"email"},"description":"The answered message's other To and Cc recipients, without your mailbox or automated addresses; never Bcc. More than 10 sends the thread to a person."},"subject":{"type":"string"},"approvedAt":{"type":["string","null"],"format":"date-time"},"approvedVia":{"type":["string","null"],"enum":["cabinet","api",null]},"approvedByYou":{"type":"boolean"},"sentAt":{"type":["string","null"],"format":"date-time"},"confirmedByGmail":{"type":"boolean"},"markedSentAt":{"type":["string","null"],"format":"date-time"},"failure":{"type":["string","null"],"description":"e.g. smtp_<code>, send_timeout, send_network or recipients_rejected (see the event's detail). Never resent automatically."},"evidence":{"type":["string","null"],"description":"How delivery is known: accepted, late_acceptance, partial (some recipients refused), none or inconclusive."},"retryOf":{"type":["string","null"],"format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}},"OutboundResponse":{"type":"object","additionalProperties":false,"required":["outbound"],"properties":{"outbound":{"$ref":"#/components/schemas/Outbound"}}},"MailMessage":{"type":"object","required":["id","direction","from","to","cc","sentAt","text","outboundId","readMark","archiveMark","reply","attachments"],"properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["customer","airdg","person","participant"]},"from":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":["string","null"]}}},"to":{"type":"array","items":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"sentAt":{"type":"string","format":"date-time"},"text":{"type":"string","description":"Plain text; never HTML."},"outboundId":{"type":["string","null"],"format":"uuid"},"readMark":{"type":["object","null"],"required":["state","reason"],"description":"For a customer message AirDG answers: awaiting, pending, done (reason already_read), failed (event read_mark_failed) or skipped (permission_missing, not_found); null otherwise.","properties":{"state":{"type":"string","enum":["awaiting","pending","done","failed","skipped"]},"reason":{"type":["string","null"]}}},"archiveMark":{"type":["object","null"],"required":["state","reason"],"description":"For a message AirDG moves out of the Inbox after replying: pending, moving, done (reason unconfirmed), failed (event archive_failed) or skipped (permission_missing, not_found, unsupported, folder_unavailable, identity_mismatch, renamed, setting_off); null otherwise.","properties":{"state":{"type":"string","enum":["pending","moving","done","failed","skipped"]},"reason":{"type":["string","null"]}}},"reply":{"type":["object","null"],"required":["kind","origin","approvedVia","approvedByYou","state","failure"],"description":"For an AirDG message: its reply's kind, how it was sent (automatic, or approved in the cabinet or API), its current state and any failure code; null otherwise.","properties":{"kind":{"type":"string","enum":["ask","decline_non_air","decline_underweight","acknowledge"]},"origin":{"type":"string","enum":["manual","automatic"]},"approvedVia":{"type":["string","null"]},"approvedByYou":{"type":"boolean"},"state":{"type":"string"},"failure":{"type":["string","null"]}}},"attachments":{"type":"array","items":{"type":"object","required":["id","filename","mime","size","status","sameAs","replacedBy","removal"],"properties":{"id":{"type":"string","format":"uuid"},"filename":{"type":"string"},"mime":{"type":"string"},"size":{"type":"integer"},"status":{"type":"string","enum":["stored","too_large","unsupported","unavailable","duplicate","retired"],"description":"duplicate: the same bytes as a current file (sameAs); retired: replaced in full by newer files (replacedBy), no longer served."},"sameAs":{"type":["string","null"],"format":"uuid"},"replacedBy":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"}},"removal":{"type":["string","null"],"enum":["pending","done",null],"description":"For a duplicate or retired file: pending until AirDG's copy is purged, then done. The mail stays in the mailbox."}}}}}},"MailEvent":{"type":"object","required":["kind","at","via","byYou","detail"],"properties":{"kind":{"type":"string"},"at":{"type":"string","format":"date-time"},"via":{"type":["string","null"]},"byYou":{"type":"boolean"},"detail":{"description":"Data by event type, or null — sent: { outbound, rejected? }; paused: { reason, outbound?, rejected?, accepted? }; send_stopped: { outbound, to, reason? } (reason archived, mailbox_stopped, state_changed, basis_changed, outside_test_scope, legacy_decline, mode_manual, human_reply, newer_message, basis_removed or reply_invalid); read_mark_failed: { message, reason, attempts }; linked, linked_into: { from or into, messages, customerMessages, attachments } — or { from?, into?, automatic: true } when AirDG joined a reply that arrived without reply headers; customer_mail, participant: { unreadable: true }."}}},"MailOriginal":{"type":"object","additionalProperties":false,"required":["id","messageId","receivedAt","filename","mime","size","status","reading","preview","receipts","receiptsTotal","replacement"],"properties":{"id":{"type":"string","format":"uuid"},"messageId":{"type":"string","format":"uuid"},"receivedAt":{"type":"string","format":"date-time"},"filename":{"type":"string","description":"As received; may repeat in a thread."},"mime":{"type":"string","description":"As received; not verified."},"size":{"type":"integer"},"status":{"type":"string","enum":["stored","too_large","unsupported","unavailable"],"description":"stored: AirDG kept the bytes; not an assessment of the document."},"reading":{"description":"The analysis's reading: kinds (one file may hold several) and a one-line description; or notRead with the reason; null when not classified.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["kinds","description"],"properties":{"kinds":{"type":"array","minItems":1,"items":{"type":"string","enum":["invoice","packing_list","sds","un38_3","cargo_photo","permit","supply_contract","other","unreadable"]}},"description":{"type":"string","description":"Plain text; never HTML."}}},{"type":"object","additionalProperties":false,"required":["notRead"],"properties":{"notRead":{"type":"string","enum":["unavailable","limit","format","context","unreadable"],"description":"unavailable (not readable from the mailbox), limit (a file over 25 MiB, an Office file over 3 MiB, or the thread over 20 files / 25 MiB), format (unsupported), context (thread over the input limit) or unreadable (damaged or password-protected). format, unreadable and an oversize file are asked from the sender."}}}]},"preview":{"type":["string","null"],"enum":["pdf","image",null],"description":"The website may show it inline."},"receipts":{"type":"array","minItems":1,"maxItems":20,"description":"The first 20 receipts of these exact bytes, oldest first (the first is this file's own); AirDG keeps the bytes once.","items":{"type":"object","additionalProperties":false,"required":["messageId","receivedAt","filename"],"properties":{"messageId":{"type":"string","format":"uuid"},"receivedAt":{"type":"string","format":"date-time"},"filename":{"type":"string"}}}},"receiptsTotal":{"type":"integer","minimum":1,"description":"How many messages supplied these exact bytes."},"replacement":{"description":"null, or the files (by) holding a newer version of some of this file's documents; the file stays current for the rest.","oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["state","by","note"],"properties":{"state":{"type":"string","enum":["partly_replaced"]},"by":{"type":"array","maxItems":20,"items":{"type":"string","format":"uuid"}},"note":{"type":"string","description":"One plain-text line."}}}]}}},"OriginalPage":{"type":"object","additionalProperties":false,"required":["originals","nextCursor","total"],"properties":{"originals":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/MailOriginal"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"}}},"MessagePage":{"type":"object","additionalProperties":false,"required":["messages","nextCursor","total"],"properties":{"messages":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/MailMessage"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"}}},"OutboundPage":{"type":"object","additionalProperties":false,"required":["outbound","nextCursor","total"],"properties":{"outbound":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Outbound"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"}}},"EventPage":{"type":"object","additionalProperties":false,"required":["events","nextCursor","total"],"properties":{"events":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/MailEvent"}},"nextCursor":{"type":["string","null"]},"total":{"type":"integer"}}},"ThreadResponse":{"type":"object","additionalProperties":false,"required":["thread"],"properties":{"thread":{"allOf":[{"$ref":"#/components/schemas/ThreadSummary"},{"type":"object","required":["sourceUrl","collected","minimum","messages","messagesTotal","messagesNext","outbound","outboundTotal","outboundNext","acknowledgement","events","eventsTotal","eventsNext","originals","originalsTotal","originalsNext","link"],"properties":{"link":{"type":["object","null"],"description":"For a thread held for review: candidates (up to ten), more and linkedInto null; for a linked thread, linkedInto; otherwise null.","required":["candidates","more","linkedInto"],"properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/LinkCandidate"}},"more":{"type":"boolean"},"linkedInto":{"type":["object","null"],"required":["id","subject"],"properties":{"id":{"type":"string","format":"uuid"},"subject":{"type":"string"}}}}},"sourceUrl":{"type":["string","null"],"format":"uri","example":"https://mail.google.com/mail/?authuser=ops%40example.test#all/0123456789abcdef","description":"The thread in the Gmail web interface for the mailbox's account; null for aliyun or when unknown. Built from stored data; not a contract Google publishes."},"collected":{"type":"object","description":"Facts and documents collected so far (values may be null)."},"minimum":{"oneOf":[{"$ref":"#/components/schemas/Minimum"},{"type":"null"}],"description":"The payable minimum's standing; null before the first analysis."},"messages":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/MailMessage"}},"messagesTotal":{"type":"integer"},"messagesNext":{"type":["string","null"]},"outbound":{"type":"array","maxItems":21,"items":{"$ref":"#/components/schemas/Outbound"}},"outboundTotal":{"type":"integer"},"outboundNext":{"type":["string","null"]},"acknowledgement":{"type":["object","null"],"required":["outboundId","state","at"],"description":"The acknowledgement of the complete set, with its state and time; null while there is none.","properties":{"outboundId":{"type":"string","format":"uuid"},"state":{"type":"string"},"at":{"type":["string","null"],"format":"date-time"}}},"events":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/MailEvent"}},"eventsTotal":{"type":"integer"},"eventsNext":{"type":["string","null"]},"originals":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/MailOriginal"}},"originalsTotal":{"type":"integer"},"originalsNext":{"type":["string","null"]}}}]}}},"ModeChange":{"type":"object","additionalProperties":false,"required":["mode","version"],"properties":{"mode":{"type":"string","enum":["manual","automatic"]},"version":{"type":"integer","minimum":1},"mailboxId":{"type":"string","format":"uuid","description":"The mailbox (from GET /api/v1/mail); optional with exactly one, else 400 mailbox_required."}}},"OneTonneChange":{"type":"object","additionalProperties":false,"required":["enabled","version"],"properties":{"enabled":{"type":"boolean"},"version":{"type":"integer","minimum":1},"mailboxId":{"type":"string","format":"uuid","description":"The mailbox (from GET /api/v1/mail); optional with exactly one, else 400 mailbox_required."}}},"ArchiveAfterReplyChange":{"type":"object","additionalProperties":false,"required":["enabled","version"],"properties":{"enabled":{"type":"boolean"},"version":{"type":"integer","minimum":1},"mailboxId":{"type":"string","format":"uuid","description":"The mailbox (from GET /api/v1/mail); optional with exactly one, else 400 mailbox_required."}}},"SignatureChange":{"type":"object","additionalProperties":false,"required":["signature","version"],"properties":{"signature":{"type":"string","minLength":0,"maxLength":1000,"description":"The signature, in any language: at most 1,000 characters and 12 lines; an empty string means none."},"version":{"type":"integer","minimum":1},"mailboxId":{"type":"string","format":"uuid","description":"The mailbox (from GET /api/v1/mail); optional with exactly one, else 400 mailbox_required."}}},"VersionChange":{"type":"object","additionalProperties":false,"required":["version"],"properties":{"version":{"type":"integer","minimum":1}}},"LinkChange":{"type":"object","additionalProperties":false,"required":["version","intoThreadId","intoVersion"],"properties":{"version":{"type":"integer","minimum":1},"intoThreadId":{"type":"string","format":"uuid"},"intoVersion":{"type":"integer","minimum":1}}},"LinkResponse":{"type":"object","additionalProperties":false,"required":["thread","into"],"properties":{"thread":{"$ref":"#/components/schemas/ThreadSummary"},"into":{"$ref":"#/components/schemas/ThreadSummary"}}},"LinkCandidate":{"type":"object","additionalProperties":false,"required":["id","subject","state","lastActivityAt","version"],"properties":{"id":{"type":"string","format":"uuid"},"subject":{"type":"string"},"state":{"type":"string"},"lastActivityAt":{"type":"string","format":"date-time"},"version":{"type":"integer","minimum":1}}},"DraftEdit":{"type":"object","additionalProperties":false,"required":["text","version"],"properties":{"text":{"type":"string","minLength":1,"maxLength":12000},"version":{"type":"integer","minimum":1}}},"SendAgain":{"type":"object","additionalProperties":false,"required":["version","checkedSent"],"properties":{"version":{"type":"integer","minimum":1},"checkedSent":{"type":"boolean","const":true}}},"CountryCode":{"type":"string","enum":["AE","HK","CN","GB"],"description":"AE United Arab Emirates, HK Hong Kong, CN China, GB United Kingdom."},"CountryOption":{"type":"object","additionalProperties":false,"required":["code","name"],"properties":{"code":{"$ref":"#/components/schemas/CountryCode"},"name":{"type":"string","description":"The English name"}}},"Airport":{"type":"object","additionalProperties":false,"required":["iata","icao","name","city","tz","lat","lon","type","retired"],"properties":{"iata":{"type":"string","pattern":"^[A-Z]{3}$"},"icao":{"type":["string","null"],"pattern":"^[A-Z]{4}$","description":"The ICAO code; null if none"},"name":{"type":"string","description":"The English name"},"city":{"type":"string","description":"The city served, in English; may be empty"},"tz":{"type":["string","null"],"description":"The IANA time zone"},"lat":{"type":"number"},"lon":{"type":"number"},"type":{"type":"string","enum":["large_airport","medium_airport","small_airport"]},"retired":{"type":"boolean","description":"true: no longer in the reference base; stays chosen until removed"}},"example":{"iata":"DXB","icao":"OMDB","name":"Dubai International Airport","city":"Dubai","tz":"Asia/Dubai","lat":25.2528,"lon":55.3644,"type":"large_airport","retired":false}},"Workspace":{"type":"object","additionalProperties":false,"required":["country","countries","airports","airportLimit","airportAllowance","verification"],"properties":{"country":{"type":["object","null"],"additionalProperties":false,"required":["code","name","chosenAt"],"properties":{"code":{"$ref":"#/components/schemas/CountryCode"},"name":{"type":"string"},"chosenAt":{"type":["string","null"],"format":"date-time"}},"description":"The workspace's country; null if none"},"countries":{"type":"array","items":{"$ref":"#/components/schemas/CountryOption"},"description":"The countries it may choose"},"airports":{"type":"array","items":{"$ref":"#/components/schemas/Airport"},"description":"Its airports, by city then code"},"airportLimit":{"$ref":"#/components/schemas/AirportLimit"},"airportAllowance":{"$ref":"#/components/schemas/AirportAllowance"},"verification":{"$ref":"#/components/schemas/CompanyVerification"}},"example":{"country":{"code":"AE","name":"United Arab Emirates","chosenAt":"2026-11-08T12:27:00.000Z"},"countries":[{"code":"AE","name":"United Arab Emirates"},{"code":"HK","name":"Hong Kong"},{"code":"CN","name":"China"},{"code":"GB","name":"United Kingdom"}],"airports":[{"iata":"DXB","icao":"OMDB","name":"Dubai International Airport","city":"Dubai","tz":"Asia/Dubai","lat":25.2528,"lon":55.3644,"type":"large_airport","retired":false}],"airportLimit":{"airports":5,"changes":5,"windowDays":30},"airportAllowance":{"chosen":1,"setupLeft":4,"changesUsed":0,"changesLeft":5,"canAdd":4,"nextChangeAt":null},"verification":{"state":"verified","companyName":"EXAMPLE FREIGHT FZCO","documentNumber":"DG 100","document":"gcaa_dg_certificate","verifiedAt":"2026-11-15T09:12:00.000Z","verifiedUntil":"2027-01-15T00:00:00.000Z","attempt":{"id":"00000000-0000-4000-8000-000000000002","state":"verified","reason":null,"at":"2026-11-15T09:12:00.000Z"},"attemptsLeft":4}}},"CompanyVerification":{"type":"object","additionalProperties":false,"required":["state","companyName","documentNumber","document","verifiedAt","verifiedUntil","attempt","attemptsLeft"],"description":"The workspace is open only while state is verified (verifiedUntil in the future)","properties":{"state":{"type":"string","enum":["unverified","checking","verified","expired"],"description":"unverified, checking or expired: closed; verified: open. A renewal's check shows in attempt.state"},"companyName":{"type":["string","null"],"description":"The company's name as the register prints it; null when documentNumber is"},"documentNumber":{"type":["string","null"],"description":"The verified document's number; null before verification, after a country change or once it verifies another workspace"},"document":{"type":["string","null"],"enum":["gcaa_dg_certificate","cad_regulated_agent","uk_regulated_agent","cn_business_licence",null],"description":"The country's required document: AE gcaa_dg_certificate, HK cad_regulated_agent, GB uk_regulated_agent, CN cn_business_licence (air freight forwarding in scope); null without a country."},"verifiedAt":{"type":["string","null"],"format":"date-time"},"verifiedUntil":{"type":["string","null"],"format":"date-time","description":"When the workspace closes unless renewed: the official expiry, else 12 months after verification (China: the business term's end, at most 12 months)"},"attempt":{"type":["object","null"],"additionalProperties":false,"required":["id","state","reason","at"],"description":"The latest check; null before the first upload","properties":{"id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["checking","verified","rejected","failed","superseded"],"description":"rejected: the document did not verify the company; failed: the check could not be made (upload again); superseded: the country changed"},"reason":{"type":["string","null"],"enum":["wrong_document","unreadable","not_in_registry","mismatch","expired","already_used","scope_without_air","registry_unavailable","check_unavailable",null],"description":"rejected: wrong_document, unreadable, not_in_registry, mismatch, expired, already_used, scope_without_air; failed: registry_unavailable, check_unavailable; else null"},"at":{"type":"string","format":"date-time","description":"When the check ended, or began while it runs"}}},"attemptsLeft":{"type":"integer","minimum":0,"maximum":5,"description":"Uploads left in the last 24 hours (5 at most)"}}},"VerificationResponse":{"type":"object","additionalProperties":false,"required":["verification"],"properties":{"verification":{"$ref":"#/components/schemas/CompanyVerification"}}},"VerificationUpload":{"type":"object","additionalProperties":false,"required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"One PDF, JPEG, PNG or WEBP file, at most 10 MiB"}}},"VerificationLimit":{"type":"object","additionalProperties":false,"required":["error","retryAt"],"properties":{"error":{"type":"string","const":"verification_limit"},"retryAt":{"type":"string","format":"date-time","description":"When the next upload is allowed"}}},"AirportLimit":{"type":"object","additionalProperties":false,"required":["airports","changes","windowDays"],"properties":{"airports":{"type":"integer","const":5,"description":"The most airports at a time"},"changes":{"type":"integer","const":5,"description":"The most changes in windowDays; each airport added after the first five additions is one, removing is free"},"windowDays":{"type":"integer","const":30,"description":"The rolling window for changes, in days"}}},"AirportAllowance":{"type":"object","additionalProperties":false,"required":["chosen","setupLeft","changesUsed","changesLeft","canAdd","nextChangeAt"],"properties":{"chosen":{"type":"integer","minimum":0,"description":"The airports chosen now"},"setupLeft":{"type":"integer","minimum":0,"description":"Unused additions of the first five (the setup, not changes)"},"changesUsed":{"type":"integer","minimum":0,"description":"The changes made in the last windowDays"},"changesLeft":{"type":"integer","minimum":0,"description":"The changes still available in the window"},"canAdd":{"type":"integer","minimum":0,"description":"How many airports may be added now"},"nextChangeAt":{"type":["string","null"],"format":"date-time","description":"When one more change becomes available, while none is left; else null"}}},"CountryChange":{"type":"object","additionalProperties":false,"properties":{"country":{"oneOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}],"description":"AE, HK, CN or GB; null: none. A change clears the airports."}},"example":{"country":"AE"}},"WorkspaceChange":{"type":"object","additionalProperties":false,"required":["change","airportsCleared","workspace"],"properties":{"change":{"type":"string","enum":["saved","cleared","unchanged"]},"airportsCleared":{"type":"integer","minimum":0,"description":"The airports removed because the country changed"},"workspace":{"$ref":"#/components/schemas/Workspace"}}},"AirportsChange":{"type":"object","additionalProperties":false,"required":["codes"],"properties":{"codes":{"type":"array","maxItems":1000,"items":{"type":"string","pattern":"^[A-Za-z]{3}$"},"description":"The whole new set of IATA codes (a JSON array; comma-separated in the explorer); empty clears. At most 5; see the operation for the change limit."}},"example":{"codes":["DXB","DWC","SHJ"]}},"AirportsChangeResponse":{"type":"object","additionalProperties":false,"required":["change","count","workspace"],"properties":{"change":{"type":"string","enum":["saved","unchanged"]},"count":{"type":"integer","minimum":0,"description":"The airports chosen now"},"workspace":{"$ref":"#/components/schemas/Workspace"}}},"TooManyAirports":{"type":"object","additionalProperties":false,"required":["error","limit"],"properties":{"error":{"type":"string","const":"too_many_airports"},"limit":{"type":"integer","const":5,"description":"The most airports at a time"}}},"AirportChangesExhausted":{"type":"object","additionalProperties":false,"required":["error","left","limit","windowDays","nextChangeAt"],"properties":{"error":{"type":"string","const":"airport_changes_exhausted"},"left":{"type":"integer","minimum":0,"description":"Airports that may still be added now"},"limit":{"type":"integer","const":5,"description":"The most changes in windowDays"},"windowDays":{"type":"integer","const":30},"nextChangeAt":{"type":["string","null"],"format":"date-time","description":"When one more change becomes available; null if some are left"}}},"InvalidCodes":{"type":"object","additionalProperties":false,"required":["error","codes"],"properties":{"error":{"type":"string","const":"invalid_codes"},"codes":{"type":"array","items":{"type":"string"},"description":"Codes that are not current airports of the country"}}},"AirportList":{"type":"object","additionalProperties":false,"required":["country","total","airports"],"properties":{"country":{"$ref":"#/components/schemas/CountryOption"},"total":{"type":"integer","minimum":0,"description":"The country's airports before the search"},"airports":{"type":"array","items":{"$ref":"#/components/schemas/Airport"}}}},"Member":{"type":"object","additionalProperties":false,"required":["id","email","name","state","invitation","invitedAt","sentAt","joinedAt","removedAt"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string"},"name":{"type":["string","null"],"description":"The person's name once they joined"},"state":{"type":"string","enum":["invited","active","removed"]},"invitation":{"type":["object","null"],"additionalProperties":false,"required":["sendState"],"properties":{"sendState":{"type":"string","enum":["pending","sending","sent","failed","ambiguous"]}},"description":"The invitation e-mail's state while open; else null"},"invitedAt":{"type":"string","format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"joinedAt":{"type":["string","null"],"format":"date-time"},"removedAt":{"type":["string","null"],"format":"date-time"}}},"WorkspaceUsers":{"type":"object","additionalProperties":false,"required":["members"],"properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/Member"}}}},"Invitation":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"The address to invite; the person joins at their first sign-in with it."}},"example":{"email":"manager@example.com"}},"InvitationResponse":{"type":"object","additionalProperties":false,"required":["member"],"properties":{"member":{"$ref":"#/components/schemas/Member"}}},"RemovedUser":{"type":"object","additionalProperties":false,"required":["removed","id"],"properties":{"removed":{"type":"string","enum":["invitation","member"],"description":"What ended: an open invitation, or a manager's access"},"id":{"type":"string","format":"uuid"},"sessionsEnded":{"type":"integer","minimum":0,"description":"The manager's sessions were ended (members only)"}}},"AirlineDestination":{"type":"object","additionalProperties":false,"required":["code","iata","icao","flights","transit"],"properties":{"code":{"type":"string","description":"IATA code, else ICAO"},"iata":{"type":["string","null"],"description":"The airport's IATA code, if it has one"},"icao":{"type":"string","description":"The airport's ICAO code"},"flights":{"type":"integer","minimum":1,"description":"The airline's flights that reached it in the window"},"transit":{"type":"integer","minimum":0,"description":"Of those, the flights for which it was a transit stop; traffic rights are not covered"}}},"AirlineStatus":{"type":"object","additionalProperties":false,"required":["partners","activePartners","working"],"properties":{"partners":{"type":"integer","minimum":0,"description":"The workspace's partners at the airline"},"activePartners":{"type":"integer","minimum":0,"description":"Of them, the active ones"},"working":{"type":"boolean","description":"true: at least one partner is active"}}},"Airline":{"type":"object","additionalProperties":false,"required":["icao","iata","name","named","departures","destinations","partners","activePartners","working"],"properties":{"icao":{"type":"string","pattern":"^[A-Z]{3}$","description":"The ICAO airline designator"},"iata":{"type":["string","null"],"description":"Its current IATA code; null if none"},"name":{"type":"string","description":"International name from AirDG's airline registry; the ICAO code if unknown"},"named":{"type":"boolean","description":"false when the registry has no such airline"},"departures":{"type":"integer","minimum":0,"description":"Its departures in the window from the airport asked, or from all"},"destinations":{"type":"array","items":{"$ref":"#/components/schemas/AirlineDestination"},"description":"Most flights first; each stop of a flight number counts as a destination."},"partners":{"type":"integer","minimum":0,"description":"The workspace's partners at it, at the airport asked or all"},"activePartners":{"type":"integer","minimum":0},"working":{"type":"boolean","description":"At least one partner is active (at the airport asked, or any)"}},"example":{"icao":"UAE","iata":"EK","name":"Emirates","named":true,"departures":1204,"destinations":[{"code":"LHR","iata":"LHR","icao":"EGLL","flights":84,"transit":0},{"code":"BKK","iata":"BKK","icao":"VTBS","flights":56,"transit":14}],"partners":2,"activePartners":1,"working":true}},"Coverage":{"type":"object","additionalProperties":false,"required":["iata","icao","days","complete","collecting","progress","loading"],"properties":{"iata":{"type":"string","pattern":"^[A-Z]{3}$"},"icao":{"type":["string","null"],"description":"null without a known ICAO code: the airport cannot be collected"},"days":{"type":"integer","minimum":0,"description":"The days of the window"},"complete":{"type":"integer","minimum":0,"description":"The days whose departures are all in the cache"},"collecting":{"type":"boolean","description":"Work is still to be done for the window"},"progress":{"type":"number","minimum":0,"maximum":1,"description":"Share of the airport's work done, 0–1; 0 without an ICAO code"},"loading":{"type":["object","null"],"additionalProperties":false,"required":["day","phase"],"properties":{"day":{"type":"string","format":"date"},"phase":{"type":"string","enum":["departures","cargo","stops"]}},"description":"What is being fetched now: departures, cargo or stops; null if nothing"}}},"AirlineList":{"type":"object","additionalProperties":false,"required":["gate","country","airports","airport","window","flightData","collection","coverage","progress","total","counts","relationship","airlines"],"properties":{"gate":{"type":["string","null"],"enum":["no_country","no_airports",null],"description":"What to choose in Settings → Workspace first; null if nothing"},"country":{"type":["object","null"],"additionalProperties":false,"required":["code","name"],"properties":{"code":{"$ref":"#/components/schemas/CountryCode"},"name":{"type":"string"}}},"airports":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["iata","icao","airlines"],"properties":{"iata":{"type":"string"},"icao":{"type":["string","null"]},"airlines":{"type":"integer","minimum":0,"description":"Airlines that departed from it in the window (0 without an ICAO code)"}}},"description":"The workspace's airports, by city then code"},"airport":{"oneOf":[{"$ref":"#/components/schemas/AirlinesAirport"},{"type":"null"}],"description":"The airport asked; null for all together or behind a gate"},"window":{"type":"object","additionalProperties":false,"required":["from","to","days"],"properties":{"from":{"type":"string","format":"date","description":"The first UTC day"},"to":{"type":"string","format":"date","description":"The last UTC day: yesterday from 02:00 UTC, the day before until then"},"days":{"type":"integer","const":14}}},"flightData":{"type":"string","enum":["available","unavailable"],"description":"unavailable: AirDG does not collect flight data for this workspace; collected data still shows. A delay is collection.delayed, not unavailable"},"collection":{"type":"object","additionalProperties":false,"required":["delayed","error","since"],"properties":{"delayed":{"type":"boolean","description":"The collection is paused or a day has failed twice in a row; AirDG retries, and nothing in the window is given up"},"error":{"type":["string","null"],"description":"The failure as a short label, e.g. \"502\", \"402\" or \"400\", \"timeout\" or \"network\"; null otherwise"},"since":{"type":["string","null"],"format":"date-time","description":"When the pause began, else the earliest standing failure; null when not delayed"}},"description":"Whether the flight data collection is delayed; never while flightData is unavailable or behind a gate"},"coverage":{"type":"array","items":{"$ref":"#/components/schemas/Coverage"},"description":"Per airport, always for every airport of the workspace: days cached, collecting, progress and loading."},"progress":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Share of the whole collection done, 0–1; null when nothing is being collected"},"total":{"type":"integer","minimum":0,"description":"Airlines before the search and the filter"},"counts":{"type":"object","additionalProperties":false,"required":["all","active","none"],"properties":{"all":{"type":"integer","minimum":0},"active":{"type":"integer","minimum":0},"none":{"type":"integer","minimum":0}},"description":"Search matches by relationship, before the filter"},"relationship":{"type":"string","enum":["all","active","none"],"description":"The relationship filter applied"},"airlines":{"type":"array","items":{"$ref":"#/components/schemas/Airline"}}}},"Partner":{"type":"object","additionalProperties":false,"required":["id","airport","airportIcao","name","email","phone","notes","active","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"airport":{"type":["string","null"],"description":"IATA code of the partner's airport; null if AirDG has no such airport"},"airportIcao":{"type":"string","pattern":"^[A-Z]{4}$","description":"The ICAO code of that airport (ZZZZ: none)"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"notes":{"type":["string","null"]},"active":{"type":"boolean","description":"The partner's Active switch"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"AirlinesAirport":{"type":"object","additionalProperties":false,"required":["iata","icao"],"properties":{"iata":{"type":"string","pattern":"^[A-Z]{3}$"},"icao":{"type":["string","null"],"description":"null without a known ICAO code: nothing is collected or kept there"}}},"ScheduleFlight":{"type":"object","additionalProperties":false,"required":["flight","via","days","dates","collected","departs","aircraft","category","loading","departures"],"properties":{"flight":{"type":["string","null"],"description":"Flight number — the one its callsign usually carries (else the callsign); null if neither is known"},"via":{"type":"array","items":{"type":"string"},"description":"Stops before this destination, in order; empty for a direct flight"},"days":{"type":"array","items":{"type":"integer","minimum":0},"minItems":7,"maxItems":7,"description":"Departures per local weekday, Monday first (the most on one date); delays left out — up to 6 hours late or 1 hour early counts on the day it was due, and a take-off repeated within 4 hours counts once."},"dates":{"type":"array","items":{"type":"integer","minimum":0},"minItems":7,"maxItems":7,"description":"Monday first: on how many of the weekday's dates in the window it departed (0–2; 3 at the window's edge), counted as days. 1 means once only where collected is 2."},"collected":{"type":"array","items":{"type":"integer","minimum":0},"minItems":7,"maxItems":7,"description":"Monday first: how many of the weekday's dates (0–2) were collected in full for this flight. Recent days, days still being retried, newly added airports and the window's edge do not count."},"departs":{"type":["string","null"],"pattern":"^([01][0-9]|2[0-3]):[0-5][05]$","description":"The usual local take-off time (HH:MM, rounded to 5 minutes), delays left out — not a published departure time; null when it varies"},"aircraft":{"type":"array","items":{"type":"string"},"description":"The ICAO aircraft type designators flown, most frequent first"},"category":{"type":["string","null"],"enum":["cargo","passenger","mixed",null],"description":"cargo: a freighter type or listed as cargo; passenger: not listed as cargo; mixed: both; null: not known yet"},"loading":{"type":["string","null"],"enum":["uld","uld_optional","bulk",null],"description":"Best loading of its aircraft types: uld (containers and pallets), uld_optional (containers or loose), bulk (loose); null if unknown"},"departures":{"type":"integer","minimum":1,"description":"Its departures in the window, a repeated take-off once"}}},"ScheduleDestination":{"type":"object","additionalProperties":false,"required":["code","iata","icao","city","departures","flights"],"properties":{"code":{"type":"string","description":"IATA code, else ICAO"},"iata":{"type":["string","null"]},"icao":{"type":"string"},"city":{"type":["string","null"],"description":"The city, in English; null if the airport is unknown"},"departures":{"type":"integer","minimum":1,"description":"Departures to it, a repeated take-off once"},"flights":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleFlight"},"description":"Flights by route, ordered by usual take-off time (null last), then by departures"}},"example":{"code":"HKG","iata":"HKG","icao":"VHHH","city":"Hong Kong","departures":13,"flights":[{"flight":"EK384","via":["BKK"],"days":[1,1,1,1,1,1,1],"dates":[2,2,1,2,2,2,2],"collected":[2,2,1,1,2,2,2],"departs":"10:25","aircraft":["A388","B77W"],"category":"passenger","loading":"uld","departures":13}]}},"ScheduleSummary":{"type":"object","additionalProperties":false,"required":["flights","destinations","cargo","passenger"],"properties":{"flights":{"type":"integer","minimum":0,"description":"The airline's departures from the airport in the window, a repeated take-off once; those without a known destination included"},"destinations":{"type":"integer","minimum":0},"cargo":{"type":"integer","minimum":0,"description":"Of the flights, the cargo ones"},"passenger":{"type":"integer","minimum":0,"description":"Of the flights, the passenger ones"}}},"AirlineDetail":{"type":"object","additionalProperties":false,"required":["airline","airport","schedule","summary","partners","instructions"],"properties":{"airline":{"$ref":"#/components/schemas/Airline"},"airport":{"oneOf":[{"$ref":"#/components/schemas/AirlinesAirport"},{"type":"null"}],"description":"The airport asked; null without one"},"schedule":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ScheduleDestination"},"description":"The schedule from the airport, by destination; null without an airport"},"summary":{"oneOf":[{"$ref":"#/components/schemas/ScheduleSummary"},{"type":"null"}],"description":"The schedule's counts; null without an airport"},"partners":{"type":"array","items":{"$ref":"#/components/schemas/Partner"},"description":"The workspace's partners at the airline (at the airport, or all), oldest first"},"instructions":{"oneOf":[{"$ref":"#/components/schemas/Instructions"},{"type":"null"}],"description":"Rate instructions at the airport; null if none or without an airport"}}},"PartnerInput":{"type":"object","additionalProperties":false,"required":["airport","name"],"properties":{"airport":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"IATA code of one of the workspace's airports (see GET /api/v1/workspace); required"},"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"maxLength":254},"phone":{"type":["string","null"],"maxLength":50},"notes":{"type":["string","null"],"maxLength":2000},"active":{"type":"boolean","default":true}},"example":{"airport":"DWC","name":"Al Noor Cargo Services","email":"rates@alnoor-cargo.example","phone":"+971 50 412 7731","notes":"Sales agent for freighters at DWC.","active":true}},"PartnerChange":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"email":{"type":["string","null"],"maxLength":254},"phone":{"type":["string","null"],"maxLength":50},"notes":{"type":["string","null"],"maxLength":2000},"active":{"type":"boolean"}},"example":{"active":false}},"PartnerResponse":{"type":"object","additionalProperties":false,"required":["partner","status"],"properties":{"partner":{"$ref":"#/components/schemas/Partner"},"status":{"$ref":"#/components/schemas/AirlineStatus"}}},"PartnerRemoved":{"type":"object","additionalProperties":false,"required":["removed","status"],"properties":{"removed":{"type":"string","format":"uuid","description":"The removed partner's id"},"status":{"$ref":"#/components/schemas/AirlineStatus"}}},"Instructions":{"type":"object","additionalProperties":false,"required":["rateInstructions","updatedAt"],"properties":{"rateInstructions":{"type":"string"},"updatedAt":{"type":"string","format":"date-time"}}},"InstructionsChange":{"type":"object","additionalProperties":false,"required":["airport","rateInstructions"],"properties":{"airport":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"IATA code of one of the workspace's airports (see GET /api/v1/workspace); required"},"rateInstructions":{"type":"string","minLength":0,"maxLength":8000,"description":"How rates should be requested from this airline: plain text, at most 8,000 characters; empty clears. Not used yet."}},"example":{"airport":"DWC","rateInstructions":"Write to rates@alnoor-cargo.example in English. Give origin, destination, pieces, gross weight, dimensions, UN number and class."}},"InstructionsResponse":{"type":"object","additionalProperties":false,"required":["instructions"],"properties":{"instructions":{"$ref":"#/components/schemas/Instructions"}}},"InvalidPartner":{"type":"object","additionalProperties":false,"required":["error","fields"],"properties":{"error":{"type":"string","const":"invalid_partner"},"fields":{"type":"array","items":{"type":"string","enum":["name","email","phone","notes","active","airport"]},"description":"The fields refused"}}},"InvalidInstructions":{"type":"object","additionalProperties":false,"required":["error","fields"],"properties":{"error":{"type":"string","const":"invalid_instructions"},"fields":{"type":"array","items":{"type":"string","enum":["rateInstructions","airport"]},"description":"The fields refused"}}}},"responses":{"MethodNotAllowed":{"description":"Only GET is supported","headers":{"Allow":{"schema":{"type":"string","const":"GET"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method_not_allowed"}}}},"BadRequest":{"description":"Query parameters or ambiguous Bearer + session credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"query":{"value":{"error":"invalid_request"}},"mixed":{"value":{"error":"ambiguous_credentials"}}}}}},"Unauthorized":{"description":"Missing, malformed, unknown, expired or revoked credential","headers":{"WWW-Authenticate":{"schema":{"type":"string"},"description":"Bearer authentication challenge"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unauthorized"}}}},"Forbidden":{"description":"Not a forwarder, or a manager's session (forbidden); or the company is not verified (verification_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"value":{"error":"forbidden"}},"closed":{"value":{"error":"verification_required"}}}}}},"RateLimited":{"description":"The account's limit of 60 requests a minute (its keys and session together) was reached; a known key with a wrong secret counts too.","headers":{"Retry-After":{"required":true,"schema":{"type":"integer","minimum":1},"description":"Whole seconds to wait before trying again"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"rate_limited"}}}},"MailForbidden":{"description":"Not a forwarder, a manager's session or Mail not turned on (forbidden); or the company is not verified (verification_required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden":{"value":{"error":"forbidden"}},"closed":{"value":{"error":"verification_required"}}}}}},"MailMethodNotAllowed":{"description":"Method not supported here; Allow names the supported one","headers":{"Allow":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"method_not_allowed"}}}},"NotFound":{"description":"No such thread, reply or attachment for this account, or Mail is off","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"Conflict":{"description":"Outdated version (version_conflict), the action does not fit the state (state_conflict), or the mailbox is not reading (mailbox_not_active)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"version":{"value":{"error":"version_conflict"}},"state":{"value":{"error":"state_conflict"}},"mailbox":{"value":{"error":"mailbox_not_active"}}}}}},"TooLarge":{"description":"The body or draft is too long, or the file is over 10 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"too_large"}}}},"WorkspaceBadRequest":{"description":"invalid_request (bad parameters, body or credentials), own_address, invalid_codes (with the codes), too_many_airports (with the limit) or empty (no file)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/InvalidCodes"},{"$ref":"#/components/schemas/TooManyAirports"}]},"examples":{"request":{"value":{"error":"invalid_request"}},"own":{"value":{"error":"own_address"}},"codes":{"value":{"error":"invalid_codes","codes":["JFK"]}},"tooMany":{"value":{"error":"too_many_airports","limit":5}},"empty":{"value":{"error":"empty"}}}}}},"WorkspaceNotFound":{"description":"No such user in this workspace (an already removed one included), or not a workspace owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"WorkspaceConflict":{"description":"no_country, country_locked, verification_in_progress, verification_unavailable, country_changed, airport_changes_exhausted, already_registered or already_invited","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AirportChangesExhausted"}]},"examples":{"country":{"value":{"error":"no_country"}},"locked":{"value":{"error":"country_locked"}},"checking":{"value":{"error":"verification_in_progress"}},"unavailable":{"value":{"error":"verification_unavailable"}},"changes":{"value":{"error":"airport_changes_exhausted","left":0,"limit":5,"windowDays":30,"nextChangeAt":"2026-12-09T10:15:00.000Z"}},"registered":{"value":{"error":"already_registered"}},"invited":{"value":{"error":"already_invited"}}}}}},"AirlinesBadRequest":{"description":"invalid_request (bad parameters or body, a search over 60 characters, an airport not the workspace's), invalid_partner or invalid_instructions (with the refused fields: name one line, email an address, no control characters except line breaks and tabs in notes and rateInstructions)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/InvalidPartner"},{"$ref":"#/components/schemas/InvalidInstructions"}]},"examples":{"request":{"value":{"error":"invalid_request"}},"partner":{"value":{"error":"invalid_partner","fields":["name","airport"]}},"instructions":{"value":{"error":"invalid_instructions","fields":["rateInstructions"]}}}}}},"AirlinesNotFound":{"description":"An airline the workspace cannot open (none of its airports' departures, not in AirDG's registry, no partners or instructions kept), a partner of another airline or workspace, or not a workspace owner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"not_found"}}}},"UnsupportedType":{"description":"The file is not a PDF, JPEG, PNG or WEBP (read from its bytes)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unsupported_type"}}}},"VerificationLimited":{"description":"rate_limited, or verification_limit: 5 uploads in 24 hours used (with retryAt)","headers":{"Retry-After":{"required":true,"schema":{"type":"integer","minimum":1},"description":"Whole seconds to wait before trying again"}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/VerificationLimit"}]},"examples":{"rate":{"value":{"error":"rate_limited"}},"limit":{"value":{"error":"verification_limit","retryAt":"2026-11-16T09:12:00.000Z"}}}}}},"Unavailable":{"description":"The service is unavailable; try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"unavailable"}}}}}}}