Introduction

The Workwae API syncs email, calendar and contacts for Gmail and Microsoft 365 accounts, and email for any IMAP/SMTP mailbox. This reference lists every /v1 operation; the conventions below apply to all of them.

Base URLCopy Anchor Link

https://api.workwae.com

Every path starts with /v1. Requests and answers are JSON, except downloads.

AuthenticationCopy Anchor Link

Send Authorization: Bearer <credential> with one of:

• API key (wk_...) with the read, write, send or admin scope.
• Account token (wat_...), short-lived, acting with every scope on one account. It works for GET /v1/accounts/{accountId} and the account's routes under Mail, Identities, Calendar and Contacts (/v1/accounts/{accountId}/...).

Each operation names the scope it needs. See Authentication and API keys.

ErrorsCopy Anchor Link

Errors answer { defined, code, status, message, data? }:

• code is the stable reason, in snake_case (for example plan_limit_accounts). Each reason always answers with the same HTTP status.
• message is for people; data is present only for reasons that carry details (invalid_input lists data.issues).
• Each operation lists the reasons it answers with, each with the condition it is answered on.

Every operation can also answer invalid_input (400), unauthenticated and api_key_expired (401), missing_scope, role_forbidden, account_token_forbidden, account_scope_forbidden and mcp_only_key (403), payload_too_large (413), rate_limited and too_many_requests (429), internal_error (500) and overloaded (503).

Calendar routes answer calendar_disabled while the account's calendar sync is off (settings.calendarEnabled), and contacts routes answer contacts_disabled while its contacts sync is off (settings.contactsEnabled). IMAP accounts have calendar and contacts only through their CalDAV and CardDAV settings.

See Errors for handling and every reason by status.

Request idsCopy Anchor Link

Every answer carries X-Request-Id. Send your own (1 to 128 characters of A-Z a-z 0-9 . _ : -) and it is echoed back; otherwise, or when it does not fit, the API generates one. Quote it when you contact support: it names the request in Workwae's logs and in the audit log.

PaginationCopy Anchor Link

Paged lists answer { items, nextCursor }: pass nextCursor back as cursor until it is null. limit sets the page size (50 by default, at most 200, unless the operation says otherwise). See Pagination.

IdempotencyCopy Anchor Link

Authenticated POST operations take an Idempotency-Key header: 1 to 255 printable ASCII characters without spaces, such as a UUID. Other methods ignore it.

• The first answer to a key is kept for 24 hours for your tenant. The same key, method, path, query and body answers it again with Idempotent-Replayed: true instead of acting twice.
• The same key with another method, path, query or body answers idempotency_key_reused (422). While the first request still runs: idempotency_key_in_progress (409).
• A 5xx or 429 answer is not kept, so retrying with the same key runs the request again.

See Idempotency.

Rate limitsCopy Anchor Link

• Requests over the plan's API rate, counted per minute for the tenant and for each credential, answer rate_limited with Retry-After.
• Every counted call answers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window ends) for whichever window has fewer requests left.
• Past 16 requests in flight for one credential (a download counts until its body is sent), a request answers too_many_requests. When an API process is overloaded: overloaded. Both carry Retry-After and did nothing, so retrying after it is safe.
• A client address that fails authentication too often in a minute has its bearer tokens refused with rate_limited until the minute ends, except API keys that authenticated recently.

See Rate limits and plan limits.

Plans and modulesCopy Anchor Link

Every tenant runs under a plan; GET /v1/usage shows it.

• Creations beyond its limits answer plan_limit_accounts, plan_limit_sends, plan_limit_webhooks or plan_limit_storage. A connect flow stopped by the account limit returns to your redirectUri with status=error&error=plan_limit_accounts.
• Modules (plan.limits.modules): calendar, contacts, tracking, ai, meetings and sharedMailboxes; mail is always included.
• Routes of a module the plan lacks answer plan_module_unavailable: Calendar, Contacts, meeting apps and connections, shared mailboxes, AI drafts, and tracking asked for on a send.
• Without a module its settings have no effect: no calendar or contacts sync, no calendar or contacts scopes on connect, no tracking defaults on sends, no reply classification.
• Shared-mailbox accounts added before the plan lost sharedMailboxes keep syncing and sending; only adding new ones, and asking for the shared mailbox scope on connect, is refused.

See Plan limits and Modules.

DownloadsCopy Anchor Link

Downloads are sent chunked, without Content-Length. Sizes are in the message's size, each attachment's size and an export's bytes.

OAuth redirect URIsCopy Anchor Link

Register these callbacks with your own OAuth apps (one Microsoft app per cloud). The same callbacks serve the platform apps.

https://api.workwae.com/connect/callback/google
https://api.workwae.com/connect/callback/microsoft

After sign-in the user returns to your redirectUri, which must be listed in settings.redirectUris, with status=success&account_id=...&state=... or status=error&error=<code>&state=.... A hosted session without a redirectUri ends on Workwae's own confirmation page; read its outcome with GET /v1/connect-sessions/{sessionId}. See Connect accounts.

Reference sectionsCopy Anchor Link