Skip to main content
Docs
Browse documentation

OpenAPI 0.2.0

Moira Connect API reference

Generated from the checked-in OpenAPI contract at build time. Paths, methods, authentication, parameters, request shapes, and responses stay tied to the same source as the SDK.

bash
curl https://api.moiraconnect.com/v1/accounts \
  -H "Authorization: Bearer $MOIRA_API_KEY"

/accounts

get

GET /accounts

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "q",
    "schema": {
      "maxLength": 100,
      "type": "string"
    }
  },
  {
    "description": "Narrow the page to one registry provider name; an unknown name is a 422",
    "in": "query",
    "name": "provider",
    "schema": {
      "maxLength": 40,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "after",
    "schema": {
      "description": "Opaque account cursor",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Account-scoped cursor page with next_cursor. Each item carries status_reason (superseded_by_reconnect when a newer connection took over this account's provider binding, else null) and superseded_by_account_id
422
Unknown provider name
post

POST /accounts

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "auth_mode": {
            "default": "qr",
            "enum": [
              "qr",
              "phone"
            ]
          },
          "external_reference": {
            "maxLength": 255,
            "type": "string"
          },
          "provider": {
            "enum": [
              "whatsapp",
              "telegram"
            ]
          }
        },
        "required": [
          "provider"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Account assigned and authentication requested
409
Idempotency conflict

/accounts/{accountId}

get

GET /accounts/{accountId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Account and current authentication challenge. status_reason is superseded_by_reconnect when the account is logged_out because a newer connection in the same project took over its provider binding (GitHub: the same App installation was connected again), with superseded_by_account_id naming that connection; null otherwise
404
Account not found
delete

Permanently erase a provider connection and its retained data

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Provider logout, volume cleanup, object deletion, and relational erasure queued
Response schema
{
  "$ref": "#/components/schemas/AccountErasureResponse"
}

/accounts/{accountId}/activity

get

Per-connection activity log (lifecycle, sync runs, failures, warnings)

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "severity",
    "schema": {
      "enum": [
        "info",
        "success",
        "warning",
        "error"
      ]
    }
  },
  {
    "in": "query",
    "name": "category",
    "schema": {
      "enum": [
        "connection",
        "sync",
        "command",
        "webhook",
        "provider",
        "security"
      ]
    }
  },
  {
    "in": "query",
    "name": "type",
    "schema": {
      "maxLength": 128,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "since",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "before_id",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Activity rows newest-first with next_cursor id pagination

/accounts/{accountId}/api-calls

get

Bounded outbound provider API call log (errors always; successes sampled; 30-day retention)

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "outcome",
    "schema": {
      "enum": [
        "success",
        "http_error",
        "network_error",
        "timeout"
      ]
    }
  },
  {
    "in": "query",
    "name": "before_id",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Provider HTTP call rows with latency

/accounts/{accountId}/authentication

post

POST /accounts/{accountId}/authentication

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "type": {
            "enum": [
              "phone",
              "code",
              "password"
            ]
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "type",
          "value"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Encrypted authentication challenge queued
422
Unsupported challenge or provider

/accounts/{accountId}/capabilities

get

GET /accounts/{accountId}/capabilities

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Effective provider and account capabilities; LinkedIn and productivity accounts report scoped states (granted | pending_consent | not_selected | not_granted | unsupported)

/accounts/{accountId}/commands/replay

post

Re-queue this connection's dead-letter commands for another delivery attempt

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Count of dead_letter commands re-queued ({ replayed }); safe no-op when none remain
404
Account not found

/accounts/{accountId}/connect

post

POST /accounts/{accountId}/connect

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable connect or reauthentication command queued

/accounts/{accountId}/disconnect

post

POST /accounts/{accountId}/disconnect

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable disconnect command queued

/accounts/{accountId}/external-reference/rebind

post

Compare-and-swap a WhatsApp Business account correlation reference

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "expected_external_reference": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "new_external_reference": {
            "maxLength": 255,
            "minLength": 1,
            "type": "string"
          },
          "reason": {
            "description": "Operator ticket or reason",
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "expected_external_reference",
          "new_external_reference",
          "reason"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Reference rebound or already at the requested value
403
API key or accounts:write scope required
409
Provider

/accounts/{accountId}/health

get

GET /accounts/{accountId}/health

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Connection

/accounts/{accountId}/logout

post

POST /accounts/{accountId}/logout

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable provider logout command queued

/accounts/{accountId}/reconsent

post

Create a hosted reconnect session requesting scopes for the current selections (incremental consent)

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

201
Hosted portal URL for the re-authorization journey

/accounts/{accountId}/sync

post

POST /accounts/{accountId}/sync

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable synchronization command queued

/accounts/{accountId}/sync-status

get

Per-connection sync depth and freshness (status, last inbound event, latest run per kind, per-resource cursors)

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
status, status_detail, last_inbound_event_at, latest sync_run per kind (initial/incremental/backfill/reconcile), and sanitized per-resource sync cursors (opaque tokens redacted)
404
Account not found

/accounts/{accountId}/test-actions

post

Emit a synthetic test event through the delivery pipeline without contacting the provider

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "action": {
            "default": "ping",
            "enum": [
              "ping"
            ]
          }
        },
        "type": "object"
      }
    }
  }
}

Responses

202
Test event emitted (visible on realtime

/activity

get

Project-wide connection/sync/webhook/provider activity log (90-day retention)

apiKey

Parameters
[
  {
    "in": "query",
    "name": "severity",
    "schema": {
      "enum": [
        "info",
        "success",
        "warning",
        "error"
      ]
    }
  },
  {
    "in": "query",
    "name": "category",
    "schema": {
      "enum": [
        "connection",
        "sync",
        "command",
        "webhook",
        "provider",
        "security"
      ]
    }
  },
  {
    "in": "query",
    "name": "type",
    "schema": {
      "maxLength": 128,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "since",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "description": "Return rows with id below this cursor",
    "in": "query",
    "name": "before_id",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Activity rows newest-first with next_cursor id pagination

/admin/accounts

get

GET /admin/accounts

adminToken

Responses

200
Cross-project account health and ownership inventory

/admin/api-keys

get

GET /admin/api-keys

adminToken

Responses

200
API key metadata without secrets
post

POST /admin/api-keys

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "project_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
API key metadata and one-time plaintext token

/admin/api-keys/{apiKeyId}

delete

DELETE /admin/api-keys/{apiKeyId}

adminToken

Parameters
[
  {
    "in": "path",
    "name": "apiKeyId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
API key revoked
404
API key not found

/admin/audit-logs

get

GET /admin/audit-logs

adminToken

Responses

200
Recent privileged audit records

/admin/bootstrap

post

Create the first tenant, project, and API key

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "environment": {
            "enum": [
              "test",
              "production"
            ]
          },
          "project_name": {
            "type": "string"
          },
          "tenant_name": {
            "type": "string"
          }
        },
        "required": [
          "tenant_name",
          "project_name",
          "environment"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Bootstrap resources and one-time plaintext API key

/admin/commands

get

GET /admin/commands

adminToken

Parameters
[
  {
    "in": "query",
    "name": "status",
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Cross-tenant command inventory

/admin/commands/{commandId}/redrive

post

POST /admin/commands/{commandId}/redrive

adminToken

Parameters
[
  {
    "in": "path",
    "name": "commandId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Failed non-send command safely returned to its durable queue
409
Command is unsafe or ineligible for redrive

/admin/entitlements

get

List partner-programme capability grants

adminToken

Parameters
[
  {
    "in": "query",
    "name": "project_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Entitlement grants
post

Record or update a partner capability grant for a project

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "capability": {
            "description": "A registry capability such as connections.list or message.send",
            "maxLength": 100,
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "granted_scopes": {
            "description": "OAuth scopes LinkedIn assigned; defaults to the registry scopes",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "programme": {
            "description": "The partner programme that granted the capability",
            "maxLength": 100,
            "type": "string"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "provider": {
            "enum": [
              "linkedin"
            ]
          },
          "rate_limit": {
            "description": "Provider-imposed limits recorded for operations",
            "type": "object"
          },
          "retention_days": {
            "maximum": 3650,
            "minimum": 1,
            "type": "integer"
          },
          "review_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "project_id",
          "provider",
          "capability",
          "enabled"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Audited entitlement; connected accounts receive account.capabilities_updated events

/admin/maintenance-jobs

get

GET /admin/maintenance-jobs

adminToken

Responses

200
Recent maintenance jobs and outcomes
post

POST /admin/maintenance-jobs

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "kind": {
            "enum": [
              "reencrypt_credentials",
              "retention",
              "reconcile",
              "webhook_replay",
              "account_erasure"
            ]
          },
          "payload": {
            "additionalProperties": true,
            "type": "object"
          },
          "project_id": {
            "format": "uuid",
            "type": "string"
          },
          "tenant_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "kind"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Audited maintenance job queued

/admin/maintenance-schedules

get

GET /admin/maintenance-schedules

adminToken

Responses

200
Durable recurring retention and account reconciliation schedules

/admin/projects

get

GET /admin/projects

adminToken

Responses

200
Project list
post

POST /admin/projects

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "environment": {
            "enum": [
              "test",
              "production"
            ]
          },
          "name": {
            "maxLength": 200,
            "type": "string"
          },
          "tenant_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "name",
          "environment"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Project created
404
Tenant not found

/admin/provider-controls

get

List provider kill switches

adminToken

Responses

200
Provider controls ordered by latest change
post

Enable or disable a provider scope

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "disabled": {
            "type": "boolean"
          },
          "provider": {
            "enum": [
              "whatsapp",
              "telegram",
              "gmail",
              "outlook",
              "imap",
              "linkedin"
            ]
          },
          "reason": {
            "maxLength": 500,
            "type": "string"
          },
          "scope_id": {
            "description": "Use * for global scope, whatsapp/telegram/gmail/outlook/imap/linkedin for provider scope, or a tenant/account UUID.",
            "type": "string"
          },
          "scope_type": {
            "enum": [
              "global",
              "provider",
              "tenant",
              "account"
            ]
          }
        },
        "required": [
          "scope_type",
          "scope_id",
          "provider",
          "disabled"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Audited provider control

/admin/schema

get

GET /admin/schema

adminToken

Responses

200
Applied schema migrations in version order

/admin/telegram-migrations

get

GET /admin/telegram-migrations

adminToken

Responses

200
Telegram shard migration inventory and checkpoints
post

POST /admin/telegram-migrations

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "target_shard_id": {
            "type": "string"
          }
        },
        "required": [
          "account_id",
          "target_shard_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Source account placed into migration drain

/admin/telegram-migrations/{migrationId}/{action}

post

POST /admin/telegram-migrations/{migrationId}/{action}

adminToken

Parameters
[
  {
    "in": "path",
    "name": "migrationId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "action",
    "required": true,
    "schema": {
      "enum": [
        "source-drained",
        "copy-verified",
        "cutover",
        "resume",
        "complete",
        "abort"
      ]
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Verified migration checkpoint applied
409
Preconditions or state transition not satisfied

/admin/tenants

get

GET /admin/tenants

adminToken

Responses

200
Tenant list
post

POST /admin/tenants

adminToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "name": {
            "maxLength": 200,
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Tenant created
409
Idempotency conflict

/admin/workers

get

GET /admin/workers

adminToken

Responses

200
Worker health

/admin/workers/{workerId}/drain

post

POST /admin/workers/{workerId}/drain

adminToken

Parameters
[
  {
    "in": "path",
    "name": "workerId",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Worker marked draining
404
Worker not found

/audit-logs

get

List project-scoped audit records using an API key with the admin scope

apiKey

Parameters
[
  {
    "in": "query",
    "name": "before",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Cursor-paginated project audit records
403
Missing admin scope

/capabilities

get

Customer-facing capability catalog with required scopes per capability

apiKey

Parameters
[
  {
    "in": "query",
    "name": "provider",
    "required": true,
    "schema": {
      "enum": [
        "google",
        "microsoft"
      ]
    }
  }
]

Responses

200
Catalog entries with scope requirements

/capability-scope-preview

post

Preview the deduplicated OAuth scope set a capability selection requires

apiKey

Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "also reports missing scopes vs the recorded grant (reconsent preview)": null,
            "description": "When present",
            "format": "uuid",
            "type": "string"
          },
          "capabilities": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "provider": {
            "enum": [
              "google",
              "microsoft"
            ]
          }
        },
        "required": [
          "provider",
          "capabilities"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Scopes with per-scope capability reasons; reconsent_required and missing_scopes when account_id given

/capability-selections

get

Project-default and per-account capability selections

apiKey

Parameters
[
  {
    "in": "query",
    "name": "provider",
    "required": true,
    "schema": {
      "enum": [
        "google",
        "microsoft"
      ]
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Selection rows
put

Replace capability selections (project default or one account)

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "provider": {
            "enum": [
              "google",
              "microsoft"
            ]
          },
          "selections": {
            "items": {
              "properties": {
                "capability": {
                  "type": "string"
                },
                "enabled": {
                  "type": "boolean"
                }
              },
              "required": [
                "capability",
                "enabled"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "provider",
          "selections"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Updated selections

/chats

get

GET /chats

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "q",
    "schema": {
      "maxLength": 100,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "after",
    "schema": {
      "description": "Opaque null-aware chat cursor",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Chat cursor page with normalized last_message summaries
post

Resolve and start a provider chat

apiKey or clientAccessToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "target": {
            "properties": {
              "type": {
                "enum": [
                  "phone",
                  "username",
                  "provider_id"
                ]
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "value"
            ],
            "type": "object"
          }
        },
        "required": [
          "account_id",
          "target"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Provider recipient resolution queued
422
Target type is unsupported for the provider

/chats/{chatId}

get

GET /chats/{chatId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Chat metadata and native state
patch

PATCH /chats/{chatId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "archived": {
            "type": "boolean"
          },
          "mute_until": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "pinned": {
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  }
}

Responses

202
Durable provider chat-setting command queued

/chats/{chatId}/action

post

POST /chats/{chatId}/action

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "action": {
            "enum": [
              "typing",
              "recording_voice",
              "uploading",
              "paused",
              "cancelled"
            ]
          }
        },
        "required": [
          "action"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Durable chat action command queued

/chats/{chatId}/actions

post

Compatibility alias for the singular chat action route

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "action": {
            "enum": [
              "typing",
              "recording_voice",
              "uploading",
              "paused",
              "cancelled"
            ]
          }
        },
        "required": [
          "action"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Durable chat action command queued

/chats/{chatId}/messages

get

GET /chats/{chatId}/messages

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "before",
    "schema": {
      "description": "Opaque account-scoped message cursor",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Cursor-paginated messages with reply state and matched outgoing client_correlation_id
Response schema
{
  "$ref": "#/components/schemas/MessagePageResponse"
}

/chats/{chatId}/participants

get

GET /chats/{chatId}/participants

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Provider-normalized group participants scoped to the chat

/chats/{chatId}/read

post

POST /chats/{chatId}/read

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable mark-read command queued

/client-sessions

post

Mint a rotating, account-scoped application session

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "access_ttl_seconds": {
            "default": 300,
            "maximum": 900,
            "minimum": 30,
            "type": "integer"
          },
          "account_ids": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "maxItems": 100,
            "minItems": 1,
            "type": "array"
          },
          "allowed_origins": {
            "items": {
              "format": "uri",
              "type": "string"
            },
            "maxItems": 20,
            "minItems": 1,
            "type": "array"
          },
          "client_id": {
            "maxLength": 128,
            "type": "string"
          },
          "external_session_id": {
            "maxLength": 255,
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": "object"
          },
          "refresh_ttl_seconds": {
            "default": 2592000,
            "maximum": 2592000,
            "minimum": 300,
            "type": "integer"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "session_ttl_seconds": {
            "default": 7776000,
            "maximum": 7776000,
            "minimum": 300,
            "type": "integer"
          },
          "subject_id": {
            "maxLength": 255,
            "type": "string"
          }
        },
        "required": [
          "client_id",
          "subject_id",
          "external_session_id",
          "account_ids",
          "allowed_origins"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
One-time access and rotating refresh token pair
409
External application session already exists

/client-sessions/{sessionId}

delete

DELETE /client-sessions/{sessionId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "sessionId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Application session and token family revoked
404
Session not found or not owned

/client-sessions/current

get

GET /client-sessions/current

clientAccessToken

Responses

200
Current application session identity

/client-sessions/refresh

post

Atomically rotate an application refresh token

No authentication declared

Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "refresh_token": {
            "type": "string",
            "writeOnly": true
          }
        },
        "required": [
          "refresh_token"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Replacement access and refresh token pair
401
Invalid

/commands/{commandId}

get

GET /commands/{commandId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "commandId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Scoped command state
404
Command not found in project

/commands/{commandId}/cancel

post

POST /commands/{commandId}/cancel

apiKey

Parameters
[
  {
    "in": "path",
    "name": "commandId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Queued command cancelled
409
Command was already claimed or executed

/contacts

get

GET /contacts

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "q",
    "schema": {
      "maxLength": 100,
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "after",
    "schema": {
      "description": "Opaque contact cursor",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Account-authorized normalized contact cursor page

/email/accounts

post

Connect a Gmail, Outlook, or IMAP account

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "auth_mode": {
            "enum": [
              "oauth",
              "app_password"
            ]
          },
          "external_reference": {
            "description": "The account's email address",
            "maxLength": 255,
            "type": "string"
          },
          "provider": {
            "enum": [
              "gmail",
              "outlook",
              "imap"
            ]
          }
        },
        "required": [
          "provider"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Email account created and awaiting authentication

/email/accounts/{accountId}/authorization-url

post

Build the OAuth consent URL for an email account

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Authorization URL for the end user to visit

/email/attachments/{attachmentId}

get

Get a signed download URL for an email attachment

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "attachmentId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Signed download URL
202
Attachment not yet downloaded
404
Attachment not found

/email/drafts

post

Create a draft email

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "attachments": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "body": {
            "type": "object"
          },
          "in_reply_to_message_id": {
            "format": "uuid",
            "type": "string"
          },
          "recipients": {
            "type": "object"
          },
          "subject": {
            "maxLength": 500,
            "type": "string"
          },
          "thread_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "account_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Draft created

/email/drafts/{draftId}

patch

PATCH /email/drafts/{draftId}

apiKey

Parameters
[
  {
    "in": "path",
    "name": "draftId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Draft updated
404
Draft not found
delete

DELETE /email/drafts/{draftId}

apiKey

Parameters
[
  {
    "in": "path",
    "name": "draftId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Draft deleted
404
Draft not found

/email/folders

get

List an email account's folders

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Folders for the account

/email/messages

get

List email messages by thread or folder

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "thread_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "folder_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Messages matching the filter
post

Send an email

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "attachment_ids": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "type": "array"
          },
          "bcc": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "body": {
            "properties": {
              "html": {
                "type": "string"
              },
              "text": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "cc": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "reply_to_message_id": {
            "format": "uuid",
            "type": "string"
          },
          "subject": {
            "maxLength": 500,
            "type": "string"
          },
          "to": {
            "items": {
              "properties": {
                "address": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "account_id",
          "to"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Send command queued

/email/messages/{messageId}

get

GET /email/messages/{messageId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Message detail with recipients
404
Message not found

/email/messages/{messageId}/flags

post

POST /email/messages/{messageId}/flags

apiKey

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "read": {
            "type": "boolean"
          },
          "starred": {
            "type": "boolean"
          }
        },
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Flag command queued

/email/messages/{messageId}/forward

post

POST /email/messages/{messageId}/forward

apiKey

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "comment": {
            "type": "string"
          },
          "to": {
            "items": {
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "to"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Forward command queued

/email/messages/{messageId}/move

post

POST /email/messages/{messageId}/move

apiKey

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "folder_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "required": [
          "folder_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Move command queued
404
Target folder not found

/email/messages/search

get

Hybrid full-text and semantic search across connected mailboxes

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "q",
    "required": true,
    "schema": {
      "maxLength": 400,
      "type": "string"
    }
  },
  {
    "description": "Comma-separated account UUIDs (also accepted as account_ids).",
    "in": "query",
    "name": "account_id",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_ids",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "mode",
    "schema": {
      "default": "hybrid",
      "enum": [
        "hybrid",
        "lexical",
        "semantic"
      ],
      "type": "string"
    }
  },
  {
    "description": "'provider' allows one live Gmail/Graph query as a supplement when local results are sparse and no structural filter is set; defaults to 'none' since a live round-trip is a real cost per request.",
    "in": "query",
    "name": "fallback",
    "schema": {
      "default": "none",
      "enum": [
        "none",
        "provider"
      ],
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "offset",
    "schema": {
      "default": 0,
      "maximum": 200,
      "minimum": 0,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "highlight",
    "schema": {
      "default": true,
      "type": "boolean"
    }
  },
  {
    "in": "query",
    "name": "since",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "until",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "from",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "participant",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "has_attachments",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "in": "query",
    "name": "is_read",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "in": "query",
    "name": "direction",
    "schema": {
      "enum": [
        "incoming",
        "outgoing"
      ],
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "thread_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Ranked results with degraded-mode and fallback metadata
422
Validation error
post

Hybrid full-text and semantic search across connected mailboxes (JSON body form)

apiKey or clientAccessToken

Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "description": "Comma-separated account UUIDs (also accepted as account_ids).",
            "type": "string"
          },
          "account_ids": {
            "type": "string"
          },
          "direction": {
            "enum": [
              "incoming",
              "outgoing"
            ],
            "type": "string"
          },
          "fallback": {
            "default": "none",
            "description": "'provider' allows one live Gmail/Graph query as a supplement when local results are sparse and no structural filter is set; defaults to 'none' since a live round-trip is a real cost per request.",
            "enum": [
              "none",
              "provider"
            ],
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "has_attachments": {
            "type": "boolean"
          },
          "highlight": {
            "default": true,
            "type": "boolean"
          },
          "is_read": {
            "type": "boolean"
          },
          "limit": {
            "maximum": 50,
            "minimum": 1,
            "type": "integer"
          },
          "mode": {
            "default": "hybrid",
            "enum": [
              "hybrid",
              "lexical",
              "semantic"
            ],
            "type": "string"
          },
          "offset": {
            "maximum": 200,
            "minimum": 0,
            "type": "integer"
          },
          "participant": {
            "type": "string"
          },
          "q": {
            "maxLength": 400,
            "type": "string"
          },
          "since": {
            "format": "date-time",
            "type": "string"
          },
          "thread_id": {
            "format": "uuid",
            "type": "string"
          },
          "until": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "q",
          "account_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Ranked results with degraded-mode and fallback metadata
422
Validation error

/email/threads

get

List email threads

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "folder_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Threads for the account

/email/threads/{threadId}

get

GET /email/threads/{threadId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "threadId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Thread detail
404
Thread not found

/events

get

GET /events

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "after",
    "schema": {
      "minimum": 0,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Ordered durable event replay page

/events/replay

post

Request an ordered durable replay page using the events:replay scope

apiKey or clientAccessToken

Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "after": {
            "oneOf": [
              {
                "minimum": 0,
                "type": "integer"
              },
              {
                "pattern": "^[0-9]+$",
                "type": "string"
              }
            ]
          },
          "limit": {
            "default": 50,
            "maximum": 100,
            "minimum": 1,
            "type": "integer"
          }
        },
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
Ordered durable event replay page
403
Missing events:replay scope

/github/actions

post

Enqueue a GitHub mutation

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/GitHubActionRequest"
      }
    }
  },
  "required": true
}

Responses

202
Command queued
Response schema
{
  "$ref": "#/components/schemas/CommandAcceptedResponse"
}
403
capability_not_granted — the installation lacks the permission this action needs
409
account_not_ready
422
validation_error or provider_mismatch

/github/checks

get

List projected check runs and check suites

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind check_run or check_suite
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/comments

get

List projected comments

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind comment
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/commits

get

List projected commits

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind commit
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/dispatches/{commandId}

get

Correlate a workflow dispatch with the run it produced

apiKey

Parameters
[
  {
    "in": "path",
    "name": "commandId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Dispatch state and the correlated run
Response schema
{
  "$ref": "#/components/schemas/GitHubDispatchStatusResponse"
}
404
command_not_found
422
That command is not a workflow dispatch

/github/installation-tokens

post

Mint a repository-scoped GitHub App installation token

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/GitHubInstallationTokenRequest"
      }
    }
  },
  "required": true
}

Responses

201
A repository-scoped token that expires within the hour
Response schema
{
  "$ref": "#/components/schemas/GitHubInstallationTokenResponse"
}
409
provider_credentials_missing, or the account carries no installation
422
validation_error, or provider_rejected when the installation does not hold a requested permission

/github/installations

get

List the GitHub App installations recorded for an account

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Installations, newest first
Response schema
{
  "$ref": "#/components/schemas/GitHubInstallationListResponse"
}
403
capability_not_granted — the installation lacks metadata:read

/github/issues

get

List projected issues

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind issue
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/pull-requests

get

List projected pull requests

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind pull_request
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/releases

get

List projected releases

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "kind",
    "schema": {
      "$ref": "#/components/schemas/GitHubWorkItemKind"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Work items of kind release
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkItemListResponse"
}

/github/repos/{owner}/{repo}/actions/runs/{runId}

get

Get one workflow run

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "runId",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
One run, not a list
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkflowRunResponse"
}
403
capability_not_granted

/github/repos/{owner}/{repo}/actions/workflows/{workflowId}/runs

get

List the runs of one workflow

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "description": "Workflow file name or numeric id",
    "in": "path",
    "name": "workflowId",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "branch",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "event",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "created_after",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Workflow runs, filtered server-side
Response schema
{
  "$ref": "#/components/schemas/GitHubWorkflowRunListResponse"
}
403
capability_not_granted — the installation lacks actions:read
422
created_after is not an ISO timestamp

/github/repos/{owner}/{repo}/branches

get

List branches

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Branches
Response schema
{
  "$ref": "#/components/schemas/GitHubBranchListResponse"
}
403
capability_not_granted

/github/repos/{owner}/{repo}/commits/{ref}/check-runs

get

List the check runs for a ref

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "ref",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Check runs
Response schema
{
  "$ref": "#/components/schemas/GitHubCheckRunListResponse"
}
403
capability_not_granted — the installation lacks checks:read

/github/repos/{owner}/{repo}/commits/{sha}

get

Get one commit

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "sha",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Commit
Response schema
{
  "$ref": "#/components/schemas/GitHubCommitResponse"
}
403
capability_not_granted
404
provider_resource_not_found

/github/repos/{owner}/{repo}/contents

get

Read a file or list a directory

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "ref",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "raw",
    "schema": {
      "type": "boolean"
    }
  }
]

Responses

200
File contents or directory listing
Response schema
{
  "$ref": "#/components/schemas/GitHubFileContentsResponse"
}
403
capability_not_granted — the installation lacks contents:read
404
provider_resource_not_found
422
raw was asked for a directory

/github/repos/{owner}/{repo}/pulls/{number}

get

Get one pull request

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "number",
    "required": true,
    "schema": {
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Pull request
Response schema
{
  "$ref": "#/components/schemas/GitHubPullRequestResponse"
}
403
capability_not_granted — the installation lacks pull_requests:read
404
provider_resource_not_found

/github/repos/{owner}/{repo}/pulls/{number}/files

get

List the files a pull request changes

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "number",
    "required": true,
    "schema": {
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Changed files; patch is present only where GitHub sent one
Response schema
{
  "$ref": "#/components/schemas/GitHubPullRequestFileListResponse"
}
403
capability_not_granted

/github/repos/{owner}/{repo}/search/code

get

Search code inside one repository

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "q",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "path",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Code matches
Response schema
{
  "$ref": "#/components/schemas/GitHubCodeSearchResponse"
}
403
capability_not_granted
429
provider_throttled

/github/repos/{owner}/{repo}/tree

get

Read the git tree

apiKey

Parameters
[
  {
    "in": "path",
    "name": "owner",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "repo",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "ref",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "recursive",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "in": "query",
    "name": "path_prefix",
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Tree entries, capped at 10 000; truncated says when the cap or GitHub's own truncation applied
Response schema
{
  "$ref": "#/components/schemas/GitHubTreeResponse"
}
403
capability_not_granted

/github/repositories

get

List repositories the installation can reach

apiKey

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "source",
    "schema": {
      "default": "projection",
      "enum": [
        "projection",
        "live"
      ]
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Repository projection rows
Response schema
{
  "$ref": "#/components/schemas/GitHubRepositoryListResponse"
}
403
capability_not_granted
429
provider_throttled

/health/live

get

live

No authentication declared

Responses

200
Service is alive

/health/ready

get

ready

No authentication declared

Responses

200
Service is ready
503
Dependency unavailable

/hosted-connect-sessions

post

Create or recover a team-scoped hosted WhatsApp or Telegram connection

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "anyOf": [
              {
                "required": [
                  "provider",
                  "external_reference"
                ]
              },
              {
                "required": [
                  "account_id"
                ]
              }
            ]
          },
          {
            "anyOf": [
              {
                "required": [
                  "success_redirect_url"
                ]
              },
              {
                "required": [
                  "webhook_id"
                ]
              },
              {
                "required": [
                  "opener_origin"
                ]
              }
            ]
          }
        ],
        "properties": {
          "account_id": {
            "description": "Reconnect an existing account in place (mode=reconnect); provider and external_reference are resolved from the account",
            "format": "uuid",
            "type": "string"
          },
          "allowed_success_redirect_origin": {
            "format": "uri",
            "type": "string"
          },
          "auth_mode": {
            "description": "Defaults per provider - qr for socket messaging, oauth for gmail/outlook/linkedin/instagram_business/google/microsoft/github, meta_signup for whatsapp_business, credentials for unofficial instagram, api_token for sentry, managed_session for linkedin_session; browser_session remains its fallback. github's oauth lane is a GitHub App installation redirect rather than an authorization-code exchange.",
            "enum": [
              "qr",
              "phone",
              "oauth",
              "meta_signup",
              "credentials",
              "managed_session",
              "browser_session",
              "api_token"
            ]
          },
          "capabilities": {
            "description": "Productivity providers only - the capability set to request OAuth scopes for; defaults to project capability_selections",
            "items": {
              "maxLength": 100,
              "type": "string"
            },
            "maxItems": 100,
            "type": "array"
          },
          "client_state": {
            "maxLength": 2048,
            "type": "string"
          },
          "expires_in_seconds": {
            "default": 900,
            "maximum": 3600,
            "minimum": 60,
            "type": "integer"
          },
          "external_reference": {
            "description": "Stable caller/team connection identity used for recovery instead of duplication; required unless account_id is provided",
            "maxLength": 255,
            "type": "string"
          },
          "failure_redirect_url": {
            "description": "Optional destination used only after a terminal hosted-connect failure",
            "format": "uri",
            "type": "string"
          },
          "opener_origin": {
            "format": "uri",
            "type": "string"
          },
          "provider": {
            "description": "Required unless account_id is provided. This is the whole set the route accepts - a provider is listed only once the hosted portal can complete its journey, so a name absent here is a 422.",
            "enum": [
              "whatsapp",
              "telegram",
              "gmail",
              "outlook",
              "linkedin",
              "linkedin_session",
              "whatsapp_business",
              "instagram_business",
              "instagram",
              "google",
              "microsoft",
              "github",
              "sentry"
            ]
          },
          "success_redirect_url": {
            "format": "uri",
            "type": "string"
          },
          "webhook_id": {
            "description": "Existing signed Kairos webhook; arbitrary callback URLs are rejected",
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Hosted URL and recovered or newly-created account identity

/hosted-connect-sessions/public/{publicToken}

get

GET /hosted-connect-sessions/public/{publicToken}

No authentication declared

Parameters
[
  {
    "in": "path",
    "name": "publicToken",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Secret-free hosted connection state and challenge metadata
410
Hosted link expired

/hosted-connect-sessions/public/{publicToken}/authentication

post

POST /hosted-connect-sessions/public/{publicToken}/authentication

No authentication declared

Parameters
[
  {
    "in": "path",
    "name": "publicToken",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "submission_id": {
            "format": "uuid",
            "type": "string"
          },
          "type": {
            "enum": [
              "phone",
              "code",
              "password"
            ]
          },
          "value": {
            "type": "string",
            "writeOnly": true
          }
        },
        "required": [
          "type",
          "value",
          "submission_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Encrypted Telegram challenge queued

/hosted-connect-sessions/public/{publicToken}/meta-signup

get

Embedded Signup client configuration for a whatsapp_business session

No authentication declared

Parameters
[
  {
    "in": "path",
    "name": "publicToken",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
app_id, config_id, and graph_version for the FB JS SDK popup
410
Session no longer active
post

Complete WhatsApp Business Embedded Signup (server-side code exchange)

No authentication declared

Parameters
[
  {
    "in": "path",
    "name": "publicToken",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "code": {
            "type": "string",
            "writeOnly": true
          },
          "phone_number_id": {
            "maxLength": 64,
            "type": "string"
          },
          "pin": {
            "description": "Optional two-step verification PIN for number registration",
            "pattern": "^\\d{6}$",
            "type": "string",
            "writeOnly": true
          },
          "waba_id": {
            "maxLength": 64,
            "type": "string"
          }
        },
        "required": [
          "code",
          "waba_id",
          "phone_number_id"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

200
WABA token stored

/linkedin/accounts

post

Connect a LinkedIn account through official OAuth

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "auth_mode": {
            "default": "oauth",
            "enum": [
              "oauth"
            ]
          },
          "external_reference": {
            "description": "Stable caller/team connection identity used for recovery instead of duplication",
            "maxLength": 255,
            "type": "string"
          },
          "provider": {
            "default": "linkedin",
            "enum": [
              "linkedin"
            ]
          }
        },
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
LinkedIn account created and awaiting authorization

/linkedin/accounts/{accountId}/authorization-url

post

Build the LinkedIn OAuth consent URL for an account

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Top-level LinkedIn authorization URL; scopes follow the project's granted entitlements
409
No active authentication session
503
LinkedIn OAuth not configured

/linkedin/entitlements

get

Show which LinkedIn capabilities are granted for this project

apiKey or clientAccessToken

Responses

200
Capability grant states with their partner programmes

/linkedin/invitations

get

List synchronized invitations

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "direction",
    "schema": {
      "enum": [
        "sent",
        "received"
      ]
    }
  }
]

Responses

200
Invitations
403
capability_not_granted
post

Send one explicit, human-confirmed invitation

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "invitee_urn": {
            "description": "Immutable LinkedIn member URN",
            "maxLength": 255,
            "type": "string"
          },
          "message": {
            "maxLength": 1900,
            "type": "string"
          }
        },
        "required": [
          "account_id",
          "invitee_urn"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Invitation command queued
403
capability_not_granted

/linkedin/invitations/{invitationId}

delete

Withdraw a pending invitation

apiKey

Parameters
[
  {
    "in": "path",
    "name": "invitationId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Withdrawal command queued
403
capability_not_granted
409
Invitation is not pending

/linkedin/organizations

get

List Company Pages the member administers

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Organization roles
403
capability_not_granted

/linkedin/people-search

post

Run an approved people search; results arrive as a linkedin.people_search_completed event

apiKey or clientAccessToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_id": {
            "format": "uuid",
            "type": "string"
          },
          "keywords": {
            "maxLength": 200,
            "type": "string"
          }
        },
        "required": [
          "account_id",
          "keywords"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Search command queued
403
capability_not_granted

/linkedin/profile

get

Get the synchronized LinkedIn profile for an account

apiKey or clientAccessToken

Parameters
[
  {
    "in": "query",
    "name": "account_id",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Member profile with immutable URN
403
capability_not_granted
404
Profile not synchronized yet

/mcp/context

get

Resolve the single project bound to an MCP-purpose API key

apiKey

Responses

200
Project identity
403
The credential was not created for MCP

/media/{mediaId}

get

GET /media/{mediaId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "mediaId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Media metadata

/media/{mediaId}/complete

post

POST /media/{mediaId}/complete

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "mediaId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Uploaded object verified
409
Size mismatch or missing reservation
422
Signature mismatch

/media/{mediaId}/download-url

get

GET /media/{mediaId}/download-url

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "mediaId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Short-lived signed download URL
202
Lazy provider download queued

/media/upload-url

post

POST /media/upload-url

apiKey or clientAccessToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

201
Reserved media and signed PUT URL

/messages

post

POST /messages

apiKey or clientAccessToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/MessageSendRequest"
      }
    }
  },
  "required": true
}

Responses

202
Durable send command queued with client_correlation_id
Response schema
{
  "$ref": "#/components/schemas/MessageCommandAckResponse"
}

/messages/{messageId}

get

GET /messages/{messageId}

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Message detail with reactions, receipts, revision history, and matched outgoing client_correlation_id
Response schema
{
  "$ref": "#/components/schemas/MessageResponse"
}
404
Message not found

/messages/{messageId}/delete

post

POST /messages/{messageId}/delete

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable delete command queued

/messages/{messageId}/edit

post

POST /messages/{messageId}/edit

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable edit command queued

/messages/{messageId}/forward

post

POST /messages/{messageId}/forward

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Telegram forward command queued
422
Unsupported provider capability

/messages/{messageId}/react

post

POST /messages/{messageId}/react

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable reaction command queued
delete

DELETE /messages/{messageId}/react

apiKey or clientAccessToken

Parameters
[
  {
    "in": "path",
    "name": "messageId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "emoji",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Durable reaction-removal command queued

/rate-limit-policy

get

GET /rate-limit-policy

apiKey

Responses

200
Effective project rate limit; production minimum is 10

/realtime-tokens

post

POST /realtime-tokens

apiKey or clientAccessToken

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "account_ids": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "maxItems": 100,
            "type": "array"
          },
          "expires_in_seconds": {
            "default": 300,
            "maximum": 900,
            "minimum": 30,
            "type": "integer"
          },
          "origin": {
            "description": "Exact browser origin bound to the WebSocket upgrade",
            "format": "uri",
            "type": "string"
          }
        },
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Short-lived scoped WebSocket token
409
Idempotency conflict

/telemetry/accounts

post

Connect a Sentry organization server-to-server

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TelemetryAccountCreate"
      }
    }
  },
  "required": true
}

Responses

201
The account, its authentication session, and the webhook URL to paste into Sentry
Response schema
{
  "$ref": "#/components/schemas/TelemetryAccountResponse"
}
409
idempotency_conflict — the same key was replayed with a different credential
422
validation_error — provider is not sentry, or credentials lack auth_token or organization_slug

/telemetry/actions

post

Enqueue a Sentry mutation

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/TelemetryActionRequest"
      }
    }
  },
  "required": true
}

Responses

202
Command queued
Response schema
{
  "$ref": "#/components/schemas/TelemetryActionAcceptedResponse"
}
403
capability_not_granted — the message names the Sentry scope the token lacks
404
account_not_found
409
account_not_ready — the account must be ready or degraded
422
validation_error, or provider_mismatch when the account is not a Sentry account

/telemetry/issues

get

List issues, newest activity first

apiKey

Parameters
[
  {
    "description": "Omit to span every Sentry account in the project",
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "description": "Sentry's numeric project id or its slug; a slug is resolved through this account's own projects",
    "in": "query",
    "name": "project",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "status",
    "schema": {
      "enum": [
        "unresolved",
        "resolved",
        "ignored"
      ],
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "level",
    "schema": {
      "enum": [
        "fatal",
        "error",
        "warning",
        "info",
        "debug"
      ],
      "type": "string"
    }
  },
  {
    "description": "Issues whose last_seen is at or after this instant",
    "in": "query",
    "name": "since",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "culprit or short_id; % and _ are escaped": null,
    "description": "Substring of title",
    "in": "query",
    "name": "q",
    "schema": {
      "maxLength": 200,
      "type": "string"
    }
  },
  {
    "description": "The previous page's next_after; anything this endpoint did not issue is a 422",
    "in": "query",
    "name": "after",
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
One page of issues and the cursor for the next, or null at the end
Response schema
{
  "$ref": "#/components/schemas/TelemetryIssueListResponse"
}
403
capability_not_granted
404
account_not_found
422
validation_error — an unparseable since, an over-long q, or an after this endpoint did not issue

/telemetry/issues/{issueId}

get

Get one issue with the stack frames of its latest event

apiKey

Parameters
[
  {
    "description": "The Moira row id or Sentry's own issue id",
    "in": "path",
    "name": "issueId",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "description": "Refetch the latest event from Sentry before answering",
    "in": "query",
    "name": "fresh",
    "schema": {
      "type": "boolean"
    }
  }
]

Responses

200
The issue and its latest event, or latest_event null when none has been fetched
Response schema
{
  "$ref": "#/components/schemas/TelemetryIssueDetailResponse"
}
403
capability_not_granted, or provider_permission_denied when Sentry refused the live fetch for the token's scopes
404
issue_not_found, or account_not_found
409
account_not_ready or account_authentication_required — fresh=true only; a projection read is unaffected
429
provider_throttled — Sentry is rate limiting this organization; retry-after carries the interval
502
provider_unavailable — Sentry could not be reached or did not answer

/telemetry/projects

get

List the Sentry projects this organization exposes

apiKey

Parameters
[
  {
    "description": "Omit to span every Sentry account in the project",
    "in": "query",
    "name": "account_id",
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 100,
      "maximum": 500,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Projects ordered by organization slug then slug
Response schema
{
  "$ref": "#/components/schemas/TelemetryProjectListResponse"
}
403
capability_not_granted — the token's reported scopes do not cover telemetry.project.read
404
account_not_found — this project has no connected Sentry account
422
validation_error, or provider_mismatch when account_id names a non-Sentry account

/usage

get

GET /usage

apiKey

Parameters
[
  {
    "in": "query",
    "name": "from",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "to",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  }
]

Responses

200
Project usage totals by durable metric

/webhook-deliveries

get

GET /webhook-deliveries

apiKey

Responses

200
Recent delivery attempts

/webhook-deliveries/{deliveryId}

get

GET /webhook-deliveries/{deliveryId}

apiKey

Parameters
[
  {
    "in": "path",
    "name": "deliveryId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Delivery status
404
Delivery not found

/webhook-deliveries/{deliveryId}/replay

post

POST /webhook-deliveries/{deliveryId}/replay

apiKey

Parameters
[
  {
    "in": "path",
    "name": "deliveryId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Delivery queued for replay

/webhooks

get

GET /webhooks

apiKey

Responses

200
Webhook endpoint list without signing secrets
post

POST /webhooks

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "event_filters": {
            "default": [
              "*"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

201
Endpoint and one-time signing secret

/webhooks/{webhookId}

get

GET /webhooks/{webhookId}

apiKey

Responses

200
Webhook endpoint
404
Not found
patch

PATCH /webhooks/{webhookId}

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Updated endpoint
delete

DELETE /webhooks/{webhookId}

apiKey

Parameters
[
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

200
Endpoint disabled and removed from listings

/webhooks/{webhookId}/deliveries

get

Delivery history for a webhook endpoint with response inspection

apiKey

Parameters
[
  {
    "in": "path",
    "name": "webhookId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "status",
    "schema": {
      "enum": [
        "pending",
        "retrying",
        "delivering",
        "succeeded",
        "dead_letter"
      ]
    }
  },
  {
    "in": "query",
    "name": "before",
    "schema": {
      "format": "date-time",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Deliveries newest-first including attempt count

/whatsapp-business/accounts/{accountId}/chats/{chatId}/service-window

get

Read the WhatsApp Business customer service window

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "chatId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  }
]

Responses

200
Service-window state
Response schema
{
  "$ref": "#/components/schemas/WhatsAppServiceWindowResponse"
}

/whatsapp-business/accounts/{accountId}/messages

post

Send text, media, or an approved WhatsApp Business template

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/WhatsAppBusinessMessageSendRequest"
      }
    }
  },
  "required": true
}

Responses

202
Message command queued
Response schema
{
  "$ref": "#/components/schemas/MessageCommandAckResponse"
}
422
Validation

/whatsapp-business/accounts/{accountId}/templates

get

List WhatsApp Business templates with an opaque cursor

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "after",
    "schema": {
      "description": "Opaque template cursor",
      "type": "string"
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "default": 50,
      "maximum": 100,
      "minimum": 1,
      "type": "integer"
    }
  }
]

Responses

200
Approved and pending templates visible to the account
Response schema
{
  "$ref": "#/components/schemas/WhatsAppTemplatePageResponse"
}
post

Create a WhatsApp Business template

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
Request body
{
  "content": {
    "application/json": {
      "schema": {
        "properties": {
          "category": {
            "enum": [
              "MARKETING",
              "UTILITY",
              "AUTHENTICATION"
            ]
          },
          "components": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          "language": {
            "type": "string"
          },
          "name": {
            "pattern": "^[a-z0-9_]+$",
            "type": "string"
          }
        },
        "required": [
          "name",
          "language",
          "category",
          "components"
        ],
        "type": "object"
      }
    }
  },
  "required": true
}

Responses

202
Template creation command queued

/whatsapp-business/accounts/{accountId}/templates/{templateName}

delete

Delete a WhatsApp Business template

apiKey

Parameters
[
  {
    "in": "path",
    "name": "accountId",
    "required": true,
    "schema": {
      "format": "uuid",
      "type": "string"
    }
  },
  {
    "in": "path",
    "name": "templateName",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "in": "header",
    "name": "Idempotency-Key",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]

Responses

202
Template deletion command queued