{ "openapi": "3.1.0", "info": { "title": "Notify Agent API", "version": "1.0.0", "description": "Scoped bearer-token API for agents and scripts (`Authorization: Bearer ntf_…`). Requests act as the token's account and require the listed scopes plus each route's ownership, membership, and role checks. Shared team and family resources follow the route-specific access rules; inaccessible resources are concealed with 404 where documented. App sharing and family service sharing are available through the documented scoped routes. Human-only actions are deliberately absent: answering prompts, approving app sign-in or issuing Notify passes, changing personal name/email disclosure preferences, creating API tokens, registering devices, accepting team invites, and acknowledging or escalating on-call pages." }, "servers": [ { "url": "/api/agent" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A Notify agent token from `notify auth login` or the dashboard." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "issues": {}, "required": { "type": "array", "items": { "type": "string" } } }, "required": [ "error" ] }, "Ok": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] }, "TokenStatus": { "type": "object", "properties": { "authenticated": { "const": true }, "token": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "prefix", "scopes", "createdAt", "lastUsedAt", "expiresAt" ] } }, "required": [ "authenticated", "token" ] }, "Scope": { "type": "string", "enum": [ "notifications:send", "interactions:create", "interactions:read", "activities:read", "activities:write", "services:read", "services:write", "devices:read", "events:read", "apps:read", "apps:write", "devices:write", "inbox:read", "inbox:write", "billing:read", "tokens:manage", "teams:read", "teams:write", "oncall:read", "oncall:write", "connectors:read", "connectors:write" ] }, "ApiToken": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "Identifying prefix only; secrets are never returned." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "kind": { "enum": [ "token", "oauth" ], "description": "`oauth` is the grant behind a connected MCP/OAuth client." }, "oauthClient": { "anyOf": [ { "type": "object", "properties": { "clientId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "clientId", "name" ] }, { "type": "null" } ], "description": "The connected client for `kind: oauth`." } }, "required": [ "id", "name", "prefix", "scopes", "expiresAt", "lastUsedAt", "createdAt", "revokedAt" ] }, "Device": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "enum": [ "ios", "android" ] }, "deviceName": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "liveActivitiesCapable": { "type": "boolean" }, "liveActivityTokenEnvironment": { "enum": [ "sandbox", "production", null ] }, "liveActivityTokenUpdatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "interactiveLiveActivitiesCapable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lastSeenAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "platform", "deviceName", "active", "liveActivitiesCapable", "liveActivityTokenEnvironment", "liveActivityTokenUpdatedAt", "interactiveLiveActivitiesCapable", "createdAt", "lastSeenAt" ] }, "AgentService": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "familyId": { "type": [ "string", "null" ] }, "defaultReplyWebhookId": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "imageUrl", "url", "createdAt", "updatedAt", "familyId", "defaultReplyWebhookId" ] }, "ServiceCreated": { "type": "object", "properties": { "service": { "allOf": [ { "$ref": "#/components/schemas/AgentService" }, { "type": "object", "properties": { "webhookUrl": { "type": [ "string", "null" ] } }, "required": [ "webhookUrl" ] } ] }, "webhookUrl": { "type": "string", "description": "Full webhook URL containing the plaintext token. Returned once." } }, "required": [ "service", "webhookUrl" ] }, "ReplyWebhook": { "type": "object", "properties": { "isDefault": { "type": "boolean" }, "id": { "type": "string", "description": "Saved Reply webhook ID (whk_…)." }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "HTTPS destination for signed reply events." }, "preset": { "enum": [ "generic", "grok", "slack" ] }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string", "description": "Redacted stored header value." } }, "required": [ "name", "value" ] } }, "events": { "type": "array", "items": { "enum": [ "interaction.answered", "interaction.expired", "interaction.canceled" ] } }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "isDefault", "id", "name", "url", "preset", "headers", "events", "enabled", "createdAt", "updatedAt" ] }, "ReplyWebhookCreated": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/ReplyWebhook" }, "signingSecret": { "type": "string", "description": "Plaintext signing secret. Returned only on creation or rotation; store securely." } }, "required": [ "webhook", "signingSecret" ] }, "ReplyWebhookDelivery": { "type": "object", "properties": { "attemptLog": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "attemptedAt": { "type": "string", "format": "date-time" }, "status": { "enum": [ "delivered", "retrying", "failed" ] }, "latencyMs": { "type": "integer" }, "responseCode": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "attemptedAt", "status", "latencyMs", "responseCode", "error" ] } }, "id": { "type": "string" }, "type": { "enum": [ "interaction.answered", "interaction.expired", "interaction.canceled" ] }, "status": { "enum": [ "pending", "retrying", "delivered", "failed", "canceled" ] }, "attempts": { "type": "integer" }, "responseCode": { "type": [ "integer", "null" ] }, "latencyMs": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "attemptLog", "id", "type", "status", "attempts", "responseCode", "latencyMs", "error", "createdAt", "deliveredAt", "nextAttemptAt" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "serviceId": { "type": "string" }, "serviceTitle": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "deliveredCount": { "type": "integer" }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "serviceId", "serviceTitle", "title", "body", "imageUrl", "url", "status", "deliveredCount", "error", "createdAt" ] }, "AgentNotification": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "body": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "projectId": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "bodyFormat": { "enum": [ "text", "markdown" ] }, "appId": { "type": "string" } }, "required": [ "id", "title", "body", "imageUrl", "url", "createdAt" ] }, "AgentNotificationCreated": { "type": "object", "properties": { "notification": { "$ref": "#/components/schemas/AgentNotification" }, "accepted": { "type": "integer" }, "idempotent": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "notification", "accepted" ] }, "AgentNotificationWithdrawn": { "type": "object", "properties": { "ok": { "const": true }, "notificationId": { "type": "string" }, "status": { "enum": [ "withdrawn", "withdraw_partial" ] }, "accepted": { "type": "integer" } }, "required": [ "ok", "notificationId", "status", "accepted" ] }, "Interaction": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "prompt": { "type": "string" }, "kind": { "enum": [ "approval", "yes_no", "reply" ] }, "presentation": { "enum": [ "notification", "live_activity" ] }, "status": { "enum": [ "pending", "approved", "denied", "yes", "no", "replied", "canceled", "expired" ] }, "choices": { "type": "array", "items": { "type": "string" } }, "response": { "type": [ "string", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "actionDigest": { "type": "string" }, "primaryLabel": { "type": [ "string", "null" ] }, "secondaryLabel": { "type": [ "string", "null" ] }, "accepted": { "type": "integer" }, "respondingDeviceId": { "type": [ "string", "null" ] }, "respondingUserId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "title", "prompt", "kind", "presentation", "status", "choices", "response", "imageUrl", "url", "actionDigest", "primaryLabel", "secondaryLabel", "accepted", "respondingDeviceId", "respondingUserId", "expiresAt", "createdAt", "respondedAt", "canceledAt" ] }, "InboxInteraction": { "allOf": [ { "$ref": "#/components/schemas/Interaction" }, { "type": "object", "properties": { "sourceName": { "type": "string" }, "sourceImageUrl": { "type": [ "string", "null" ] }, "projectId": { "type": [ "string", "null" ] } }, "required": [ "sourceName", "sourceImageUrl" ] } ] }, "InteractionCreated": { "type": "object", "properties": { "interaction": { "$ref": "#/components/schemas/Interaction" }, "accepted": { "type": "integer" }, "idempotent": { "type": "boolean" }, "liveActivityId": { "type": "string" }, "queued": { "type": "integer", "description": "Durably queued device attempts; not provider acceptance or device receipt." }, "message": { "type": "string" } }, "required": [ "interaction", "accepted" ] }, "LiveActivity": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": [ "string", "null" ] }, "props": { "type": "object", "description": "LiveActivityProps (title, optional subtitle, status, detail, progress, …)." }, "status": { "enum": [ "starting", "active", "partial", "failed", "ended", "expired" ] }, "sequence": { "type": "integer" }, "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "readiness": { "type": "object", "properties": { "ready": { "type": "integer" }, "queuedStarts": { "type": "integer" }, "awaitingUpdateToken": { "type": "integer" }, "warnings": { "type": "array", "items": { "enum": [ "update_token_delayed" ] } }, "nextStartAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "ready", "queuedStarts", "awaitingUpdateToken", "warnings", "nextStartAt" ] } }, "required": [ "id", "key", "props", "status", "sequence", "accepted", "failed", "expiresAt", "createdAt", "updatedAt", "endedAt", "readiness" ] }, "LiveActivityMutation": { "type": "object", "properties": { "apnsPriority": { "type": "integer", "enum": [ 5, 10 ], "description": "Selected iOS APNs transport priority. Queued work has not yet been sent; Android delivery is unchanged." }, "priorityReason": { "type": "string", "enum": [ "routine", "milestone", "budget_exhausted", "start", "end", "interaction" ] }, "activity": { "$ref": "#/components/schemas/LiveActivity" }, "accepted": { "type": "integer" }, "failed": { "type": "integer" }, "queued": { "type": "integer", "description": "Durably queued device operations awaiting a paced start, iOS update token, or provider retry. Separate from accepted, failed, and superseded outcomes." }, "superseded": { "type": "integer", "description": "Unsent routine progress replaced by a newer queued snapshot; never counted as accepted." }, "replaced": { "type": "integer" }, "idempotent": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "activity", "accepted", "failed" ] }, "AppSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string" }, "iconUrl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "origin", "iconUrl" ] }, "App": { "allOf": [ { "$ref": "#/components/schemas/AppSummary" }, { "type": "object", "properties": { "storageScope": { "type": "string", "description": "Opaque browser-storage generation, scoped to the viewer, app, origin and workspace membership. Changes require a fresh local partition." }, "url": { "type": "string" }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": [ "string", "null" ] }, "shareName": { "type": "boolean" }, "shareEmail": { "type": "boolean" }, "consentedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastOpenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "team": { "anyOf": [ { "$ref": "#/components/schemas/TeamSummary" }, { "type": "null" } ], "description": "Owning team; null for personal apps. Sharing and consent fields then describe the calling account only." }, "addedBy": { "type": [ "string", "null" ] } }, "required": [ "storageScope", "url", "projectId", "projectName", "shareName", "shareEmail", "consentedAt", "lastOpenedAt", "createdBy", "createdAt", "updatedAt", "team", "addedBy" ] } ] }, "InboxProjects": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "projectId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "unreadCount": { "type": "integer" }, "totalCount": { "type": "integer" }, "latestTitle": { "type": [ "string", "null" ] }, "latestPreview": { "type": [ "string", "null" ] }, "latestImageUrl": { "type": [ "string", "null" ] }, "latestAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "projectId", "name", "unreadCount", "totalCount", "latestTitle", "latestPreview", "latestImageUrl", "latestAt" ] } }, "totalUnread": { "type": "integer" } }, "required": [ "projects", "totalUnread" ] }, "InboxNotificationSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Composite ID: `event:` or `notification:`." }, "origin": { "enum": [ "event", "notification" ] }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": [ "string", "null" ] }, "sourceName": { "type": "string" }, "sourceImageUrl": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "preview": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "bodyFormat": { "enum": [ "text", "markdown" ] }, "readAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "app": { "anyOf": [ { "$ref": "#/components/schemas/AppSummary" }, { "type": "null" } ] } }, "required": [ "id", "origin", "projectId", "projectName", "sourceName", "sourceImageUrl", "title", "preview", "url", "bodyFormat", "readAt", "createdAt", "app" ] }, "InboxNotificationPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InboxNotificationSummary" } }, "nextCursor": { "type": [ "string", "null" ] }, "readThroughToken": { "type": "string" } }, "required": [ "items", "nextCursor", "readThroughToken" ] }, "InboxNotificationDetail": { "allOf": [ { "$ref": "#/components/schemas/InboxNotificationSummary" }, { "type": "object", "properties": { "body": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "pushReceipts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "deviceId": { "type": "string" }, "status": { "enum": [ "pending", "accepted", "error", "unknown" ] }, "errorCode": { "type": [ "string", "null" ] }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "deviceId", "status", "errorCode", "checkedAt" ] } } }, "required": [ "body", "summary", "status" ] } ] }, "ReadMark": { "type": "object", "properties": { "ok": { "const": true }, "readAt": { "type": [ "string", "null" ], "format": "date-time" }, "idempotent": { "type": "boolean" } }, "required": [ "ok", "readAt" ] }, "ActivityFeedPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "enum": [ "notification", "live_activity", "response" ] }, "sourceName": { "type": "string" }, "sourceImageUrl": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "result": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "sourceName", "sourceImageUrl", "title", "detail", "url", "result", "createdAt" ] } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "items", "page", "pageSize", "total" ] }, "TeamSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "Team": { "type": "object", "properties": { "kind": { "enum": [ "family", "team" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/TeamRole" }, "memberCount": { "type": "integer" }, "appCount": { "type": "integer" }, "oncallGroupCount": { "type": "integer" }, "deviceGroupCount": { "type": "integer" }, "verifiedDomain": { "type": [ "string", "null" ] }, "pendingDomain": { "type": [ "string", "null" ] }, "domainVerification": { "anyOf": [ { "type": "object", "properties": { "host": { "type": "string" }, "value": { "type": "string" } }, "required": [ "host", "value" ] }, { "type": "null" } ], "description": "TXT challenge; returned only to the owner while a domain is pending." }, "autoJoinVerifiedDomain": { "type": "boolean" }, "retentionDays": { "type": [ "integer", "null" ] }, "seats": { "type": "object", "properties": { "used": { "type": "integer" }, "available": { "type": [ "integer", "null" ] }, "billable": { "type": "integer" } }, "required": [ "used", "available", "billable" ] }, "plan": { "enum": [ "free", "team" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "role", "memberCount", "appCount", "oncallGroupCount", "deviceGroupCount", "verifiedDomain", "pendingDomain", "domainVerification", "autoJoinVerifiedDomain", "retentionDays", "seats", "plan", "createdAt" ] }, "TeamRole": { "type": "string", "enum": [ "owner", "admin", "member" ] }, "TeamMember": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/TeamRole" }, "joinedAt": { "type": "string", "format": "date-time" } }, "required": [ "userId", "name", "email", "image", "role", "joinedAt" ] }, "TeamInvite": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/TeamRole" }, "invitedBy": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "email", "domain", "role", "invitedBy", "expiresAt", "acceptedAt", "revokedAt", "createdAt" ] }, "TeamInviteCreated": { "type": "object", "properties": { "invite": { "$ref": "#/components/schemas/TeamInvite" }, "code": { "type": "string", "description": "Plaintext join code, returned once." }, "url": { "type": "string", "description": "Join link a person opens to accept (accepting is human-only)." } }, "required": [ "invite", "code", "url" ] }, "DeviceGroupMember": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": [ "string", "null" ] } }, "required": [ "userId", "name", "email", "image" ] }, "DeviceGroupDevice": { "type": "object", "properties": { "id": { "type": "string" }, "deviceName": { "type": [ "string", "null" ] }, "userId": { "type": "string" }, "userName": { "type": "string" } }, "required": [ "id", "deviceName", "userId", "userName" ] }, "DeviceGroup": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "name": { "type": "string" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceGroupMember" } }, "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceGroupDevice" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "name", "members", "devices", "createdAt", "updatedAt" ] }, "AuditLogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "actorUserId": { "type": [ "string", "null" ] }, "actorName": { "type": [ "string", "null" ] }, "actorTokenId": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "targetType": { "type": [ "string", "null" ] }, "targetId": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ] }, "ip": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "actorUserId", "actorName", "actorTokenId", "action", "targetType", "targetId", "metadata", "ip", "userAgent", "createdAt" ] }, "AuditLogPage": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLogEntry" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "entries", "nextCursor" ] }, "OncallPerson": { "type": "object", "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "image": { "type": [ "string", "null" ] } }, "required": [ "userId", "name", "image" ] }, "OncallShift": { "type": "object", "properties": { "person": { "$ref": "#/components/schemas/OncallPerson" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "override": { "type": "boolean" }, "overrideId": { "type": "string" } }, "required": [ "person", "startsAt", "endsAt", "override" ] }, "OncallGroup": { "type": "object", "properties": { "id": { "type": "string" }, "teamId": { "type": "string" }, "name": { "type": "string" }, "rotation": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/OncallPerson" } }, "period": { "enum": [ "daily", "weekly" ] }, "handoffAt": { "type": "string" }, "timezone": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" } }, "required": [ "members", "period", "handoffAt", "timezone", "startsAt" ] }, "escalation": { "type": "array", "items": { "type": "object", "properties": { "afterMinutes": { "type": "integer" }, "target": { "enum": [ "next", "group" ] } }, "required": [ "afterMinutes", "target" ] } }, "current": { "anyOf": [ { "$ref": "#/components/schemas/OncallShift" }, { "type": "null" } ] }, "upcoming": { "type": "array", "items": { "$ref": "#/components/schemas/OncallShift" } }, "overrides": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "person": { "$ref": "#/components/schemas/OncallPerson" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "person", "startsAt", "endsAt" ] } }, "openPageCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "teamId", "name", "rotation", "escalation", "current", "upcoming", "openPageCount", "createdAt", "updatedAt" ] }, "OncallPage": { "type": "object", "properties": { "id": { "type": "string" }, "groupId": { "type": "string" }, "groupName": { "type": "string" }, "teamId": { "type": "string" }, "title": { "type": "string" }, "body": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "app": { "anyOf": [ { "$ref": "#/components/schemas/AppSummary" }, { "type": "null" } ] }, "status": { "enum": [ "triggered", "acknowledged", "resolved" ] }, "dedupKey": { "type": [ "string", "null" ] }, "repeatCount": { "type": "integer" }, "notified": { "type": "array", "items": { "$ref": "#/components/schemas/OncallPerson" } }, "escalationStep": { "type": "integer" }, "nextEscalationAt": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledgedBy": { "anyOf": [ { "$ref": "#/components/schemas/OncallPerson" }, { "type": "null" } ] }, "acknowledgedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedBy": { "anyOf": [ { "$ref": "#/components/schemas/OncallPerson" }, { "type": "null" } ] }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "groupId", "groupName", "teamId", "title", "body", "url", "app", "status", "dedupKey", "repeatCount", "notified", "escalationStep", "nextEscalationAt", "acknowledgedBy", "acknowledgedAt", "resolvedBy", "resolvedAt", "source", "createdAt" ] }, "OncallPageCreated": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/OncallPage" }, "deduplicated": { "type": "boolean" }, "accepted": { "type": "integer" } }, "required": [ "page", "deduplicated", "accepted" ] }, "Billing": { "type": "object", "properties": { "configured": { "type": "boolean" }, "plan": { "const": "free", "description": "Individuals and Families are free. Teams signup is not available yet." }, "priceMonthly": { "type": "number" }, "features": { "type": "object", "properties": { "deviceRouting": { "type": "boolean" } }, "required": [ "deviceRouting" ] }, "limits": { "type": "object", "properties": { "devices": { "type": [ "integer", "null" ] }, "notificationsPerMonth": { "type": [ "integer", "null" ] }, "servicePerMinute": { "type": "integer" }, "accountPerMinute": { "type": "integer" } }, "required": [ "devices", "notificationsPerMonth", "servicePerMinute", "accountPerMinute" ] }, "usage": { "type": "object", "properties": { "notificationsRemaining": { "type": [ "integer", "null" ] } }, "required": [ "notificationsRemaining" ] } }, "required": [ "configured", "plan", "priceMonthly", "features", "limits", "usage" ] }, "ConnectorRoute": { "type": "object", "properties": { "name": { "type": "string" }, "target": { "type": "string" }, "url": { "type": "string" }, "appId": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "name", "target", "url" ] }, "Connector": { "type": "object", "properties": { "id": { "type": "string" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "tunnelId": { "type": "string" }, "hostname": { "type": "string" }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectorRoute" } }, "status": { "enum": [ "online", "offline", "unknown" ] }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "teamId": { "type": [ "string", "null" ] }, "oncallGroupId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "enabled", "name", "tunnelId", "hostname", "routes", "status", "lastSeenAt", "teamId", "oncallGroupId", "createdAt", "updatedAt" ] }, "ConnectorCreated": { "type": "object", "properties": { "connector": { "$ref": "#/components/schemas/Connector" }, "callbackSecret": { "type": "string", "description": "HMAC secret for verifying callback signatures. Returned once on create." }, "reused": { "type": "boolean" } }, "required": [ "connector" ] } } }, "paths": { "/auth/status": { "get": { "summary": "Describe the calling token", "operationId": "getAuthStatus", "security": [ { "bearer": [] } ], "x-notify-scopes": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenStatus" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/revoke": { "post": { "summary": "Revoke the calling token", "operationId": "postAuthRevoke", "security": [ { "bearer": [] } ], "x-notify-scopes": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens": { "get": { "summary": "List the account's API tokens (never secrets)", "description": "Connected MCP/OAuth clients appear as `kind: \"oauth\"`; revoking one signs that client out (access and refresh tokens). There is no create route: an agent token cannot mint tokens, so it can never escalate its own scopes or outlive its revocation. Create tokens from a signed-in session or `notify auth login`.", "operationId": "getTokens", "security": [ { "bearer": [ "tokens:manage" ] } ], "x-notify-scopes": [ "tokens:manage" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ApiToken" } } }, "required": [ "tokens" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tokens/{id}": { "delete": { "summary": "Revoke another token of the same account", "operationId": "deleteTokensId", "security": [ { "bearer": [ "tokens:manage" ] } ], "x-notify-scopes": [ "tokens:manage" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices": { "get": { "summary": "List registered devices", "description": "Registration is phone-only: only the Notify app holds a push token.", "operationId": "getDevices", "security": [ { "bearer": [ "devices:read" ] } ], "x-notify-scopes": [ "devices:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } }, "required": [ "devices" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/devices/{id}": { "delete": { "summary": "Remove a device; it registers again when Notify next opens on it", "operationId": "deleteDevicesId", "security": [ { "bearer": [ "devices:write" ] } ], "x-notify-scopes": [ "devices:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services": { "get": { "summary": "List webhook services (without webhook URLs)", "operationId": "getServices", "security": [ { "bearer": [ "services:read" ] } ], "x-notify-scopes": [ "services:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/AgentService" } } }, "required": [ "services" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a webhook service; the webhook URL is returned once", "operationId": "postServices", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultReplyWebhookId": { "anyOf": [ { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]{1,100}$" }, { "type": "null" } ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] } }, "required": [ "title" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}": { "get": { "summary": "Get a webhook service", "operationId": "getServicesId", "security": [ { "bearer": [ "services:read" ] } ], "x-notify-scopes": [ "services:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/AgentService" } }, "required": [ "service" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a webhook service's title, avatar, or tap URL", "operationId": "patchServicesId", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "defaultReplyWebhookId": { "anyOf": [ { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]{1,100}$" }, { "type": "null" } ] }, "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "imageUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/AgentService" } }, "required": [ "service" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a webhook service", "operationId": "deleteServicesId", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}/share": { "post": { "summary": "Share a webhook service with your family, or unshare it", "description": "Only the original creator can share or unshare. Set familyId to your family ID, or null to unshare. Accepted family members receive shared alerts with independent inbox read state. Family owners can rename or delete shared services, but only the original creator can rotate or see the webhook token. A creator leaving the family automatically unshares their services.", "operationId": "postServicesIdShare", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "familyId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "familyId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/AgentService" } }, "required": [ "service" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/services/{id}/rotate": { "post": { "summary": "Rotate the webhook token; the new URL is returned once", "operationId": "postServicesIdRotate", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks": { "get": { "summary": "List the account's saved Reply webhooks", "description": "Signing secrets and stored header values are never returned by read operations.", "operationId": "getWebhooks", "security": [ { "bearer": [ "services:read" ] } ], "x-notify-scopes": [ "services:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhooks": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyWebhook" } } }, "required": [ "webhooks" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a Reply webhook; its signing secret is returned once", "description": "Save an HTTPS endpoint with a generic, Grok, or Slack payload preset. Pass its whk_ ID as webhookId when creating a prompt, set a service's defaultReplyWebhookId, or set isDefault:true for account replies including MCP/API prompts without services. Account and selected endpoints each receive one event, deduplicated by endpoint ID. Store the signingSecret securely to verify signed deliveries.", "operationId": "postWebhooks", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "preset": { "default": "generic", "type": "string", "enum": [ "generic", "grok", "slack" ] }, "headers": { "default": [], "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "name", "value" ] } }, "events": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "interaction.answered", "interaction.expired", "interaction.canceled" ] } }, "enabled": { "default": true, "type": "boolean" }, "isDefault": { "default": false, "type": "boolean" } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyWebhookCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}": { "get": { "summary": "Get a Reply webhook and its recent deliveries", "operationId": "getWebhooksId", "security": [ { "bearer": [ "services:read" ] } ], "x-notify-scopes": [ "services:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/ReplyWebhook" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/ReplyWebhookDelivery" } } }, "required": [ "webhook", "deliveries" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a Reply webhook's endpoint, preset, headers, events, or enabled state", "operationId": "patchWebhooksId", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "preset": { "type": "string", "enum": [ "generic", "grok", "slack" ] }, "headers": { "maxItems": 16, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" }, "value": { "type": "string", "minLength": 1, "maxLength": 4096 } }, "required": [ "name", "value" ] } }, "events": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "interaction.answered", "interaction.expired", "interaction.canceled" ] } }, "enabled": { "type": "boolean" }, "isDefault": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "webhook": { "$ref": "#/components/schemas/ReplyWebhook" } }, "required": [ "webhook" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a Reply webhook", "operationId": "deleteWebhooksId", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/test": { "post": { "summary": "Send a signed sample event to a Reply webhook", "description": "Makes an outbound HTTPS request using the saved endpoint, headers, and preset.", "operationId": "postWebhooksIdTest", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/ReplyWebhookDelivery" } }, "required": [ "delivery" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/webhooks/{id}/rotate-secret": { "post": { "summary": "Rotate a Reply webhook signing secret; the replacement is returned once", "description": "Subsequent deliveries use the new secret. Update your receiver's signature verifier.", "operationId": "postWebhooksIdRotateSecret", "security": [ { "bearer": [ "services:write" ] } ], "x-notify-scopes": [ "services:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyWebhookCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/events": { "get": { "summary": "Recent webhook deliveries", "operationId": "getEvents", "security": [ { "bearer": [ "events:read" ] } ], "x-notify-scopes": [ "events:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } }, "required": [ "events" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activity-feed": { "get": { "summary": "Merged account activity history, newest first (20 per page)", "operationId": "getActivityFeed", "security": [ { "bearer": [ "events:read" ] } ], "x-notify-scopes": [ "events:read" ], "parameters": [ { "name": "filter", "in": "query", "schema": { "enum": [ "all", "notification", "live_activity", "response" ] }, "required": false }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityFeedPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications": { "post": { "summary": "Send a one-shot push", "description": "With `oncall` (which also needs `oncall:write`), the push pages that on-call group instead (the token owner must be on its team) and returns the page; the Idempotency-Key becomes the page's dedup key.", "operationId": "postNotifications", "security": [ { "bearer": [ "notifications:send" ] } ], "x-notify-scopes": [ "notifications:send" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 8000 }, "title": { "default": "Notify", "type": "string", "minLength": 1, "maxLength": 80 }, "imageUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "deviceIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "project": { "type": "string", "minLength": 1, "maxLength": 80 }, "summary": { "type": "string", "minLength": 1, "maxLength": 500 }, "bodyFormat": { "type": "string", "enum": [ "text", "markdown" ] }, "appId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]{8,64}$" }, "oncall": { "type": "string", "pattern": "^ocg_[A-Za-z0-9_-]{8,64}$" }, "group": { "type": "string", "pattern": "^dgrp_[A-Za-z0-9_-]{8,64}$" } }, "required": [ "body" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/AgentNotificationCreated" }, { "$ref": "#/components/schemas/OncallPageCreated" } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications/{id}/withdraw": { "post": { "summary": "Withdraw an agent notification from the account's devices", "description": "Sends a silent command that removes the push from Notification Center and marks the inbox copy read. Accepts `anot_…` or `notification:anot_…`. Returns 502 when no device accepted the command.", "operationId": "postNotificationsIdWithdraw", "security": [ { "bearer": [ "notifications:send" ] } ], "x-notify-scopes": [ "notifications:send" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentNotificationWithdrawn" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interactions": { "get": { "summary": "List the account's pending prompts from every source", "description": "There is deliberately no agent route that answers a prompt: approvals come only from a human on the phone or a signed-in session.", "operationId": "getInteractions", "security": [ { "bearer": [ "interactions:read" ] } ], "x-notify-scopes": [ "interactions:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interactions": { "type": "array", "items": { "$ref": "#/components/schemas/InboxInteraction" } } }, "required": [ "interactions" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Ask a question (approval, yes/no, or reply)", "description": "Set webhookId to a saved Reply webhook (whk_…) to receive answered, expired, or canceled events using its configured subscriptions. Live Activity presentations return immediately with accepted: 0 and queued device attempts; subsequent reads report provider acceptance. Queued work is not delivery or a human answer.", "operationId": "postInteractions", "security": [ { "bearer": [ "interactions:create", "notifications:send" ] } ], "x-notify-scopes": [ "interactions:create", "notifications:send" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80 }, "prompt": { "type": "string", "minLength": 1, "maxLength": 2000 }, "kind": { "type": "string", "enum": [ "approval", "yes_no", "reply" ] }, "imageUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "deviceIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "group": { "type": "string", "pattern": "^dgrp_[A-Za-z0-9_-]{8,64}$" }, "expiresInSeconds": { "default": 900, "type": "integer", "minimum": 30, "maximum": 86400 }, "presentation": { "type": "string", "enum": [ "notification", "live_activity" ] }, "style": { "type": "string", "enum": [ "approval", "shell", "verdict", "signal" ] }, "primaryLabel": { "type": "string", "minLength": 1, "maxLength": 24 }, "secondaryLabel": { "type": "string", "minLength": 1, "maxLength": 24 }, "callback": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "token": { "type": "string", "minLength": 16, "maxLength": 512 }, "target": { "type": "object", "properties": { "connectorId": { "type": "string", "pattern": "^conn_[A-Za-z0-9_-]{8,64}$" }, "route": { "type": "string", "pattern": "^(@|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$" }, "path": { "type": "string", "maxLength": 2048, "pattern": "^\\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$" } }, "required": [ "connectorId", "route", "path" ] } } }, "webhookId": { "type": "string", "pattern": "^whk_[A-Za-z0-9_-]{1,100}$" } }, "required": [ "title", "prompt", "kind" ], "allOf": [ { "not": { "required": [ "group", "deviceIds" ] } }, { "if": { "properties": { "presentation": { "const": "live_activity" } }, "required": [ "presentation" ] }, "then": { "properties": { "kind": { "enum": [ "approval", "yes_no" ] }, "prompt": { "maxLength": 240 }, "expiresInSeconds": { "maximum": 28800 } }, "not": { "anyOf": [ { "required": [ "url" ] }, { "required": [ "imageUrl" ] } ] } }, "else": { "not": { "anyOf": [ { "required": [ "style" ] }, { "required": [ "primaryLabel" ] }, { "required": [ "secondaryLabel" ] } ] } } } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interactions/{id}": { "get": { "summary": "Get a prompt created by this token", "operationId": "getInteractionsId", "security": [ { "bearer": [ "interactions:read" ] } ], "x-notify-scopes": [ "interactions:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interaction": { "$ref": "#/components/schemas/Interaction" } }, "required": [ "interaction" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interactions/{id}/wait": { "get": { "summary": "Long-poll a prompt created by this token until it is answered", "operationId": "getInteractionsIdWait", "security": [ { "bearer": [ "interactions:read" ] } ], "x-notify-scopes": [ "interactions:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "timeout", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 25 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interaction": { "$ref": "#/components/schemas/Interaction" }, "timedOut": { "type": "boolean" } }, "required": [ "interaction", "timedOut" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/interactions/{id}/cancel": { "post": { "summary": "Cancel a pending prompt created by this token", "operationId": "postInteractionsIdCancel", "security": [ { "bearer": [ "interactions:create" ] } ], "x-notify-scopes": [ "interactions:create" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interaction": { "$ref": "#/components/schemas/Interaction" } }, "required": [ "interaction" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activities": { "get": { "summary": "List Live Activities started by this token", "operationId": "getActivities", "security": [ { "bearer": [ "activities:read" ] } ], "x-notify-scopes": [ "activities:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "activities": { "type": "array", "items": { "$ref": "#/components/schemas/LiveActivity" } } }, "required": [ "activities" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Start a Live Activity", "description": "Up to five concurrent activities per device, including interactive activities. Distinct keys coexist. An active key owned by this requester conflicts unless replace is true; replacement affects only that key. Device capacity returns 422 ACTIVITY_CAPACITY_EXCEEDED with limit: 5. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status. Expanded budgets (title/line 2/detail): standard 32/36/100; ring 32/30/80; hero 24/36/100; terminal 36/40/100; steps 32/36/100. Compact title/subtitle/detail are hidden; status budget is 8 without progress, except terminal 0.", "operationId": "postActivities", "security": [ { "bearer": [ "activities:write" ] } ], "x-notify-scopes": [ "activities:write" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "replace": { "default": false, "type": "boolean" }, "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Task title on line 1. Suggested character budgets: standard: compact 0, expanded 32; ring: compact 0, expanded 32; hero: compact 0, expanded 24; terminal: compact 0, expanded 36; steps: compact 0, expanded 32. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "subtitle": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional full-word summary used instead of status on expanded Dynamic Island and Lock Screen line 2 only; compact and small banners retain status. Omit to use status; null clears it on update/end. Suggested character budgets: standard: compact 0, expanded 36; ring: compact 0, expanded 30; hero: compact 0, expanded 36; terminal: compact 0, expanded 40; steps: compact 0, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "status": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Required task state; displayed on line 2 when subtitle is absent. Full status remains available to accessibility. Suggested character budgets: standard: compact 8, expanded 36; ring: compact 8, expanded 30; hero: compact 8, expanded 36; terminal: compact 0, expanded 40; steps: compact 8, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "detail": { "type": "string", "minLength": 1, "maxLength": 240, "description": "Additional context in the two-line detail area, sharing space with line 2 overflow. Suggested character budgets: standard: compact 0, expanded 100; ring: compact 0, expanded 80; hero: compact 0, expanded 100; terminal: compact 0, expanded 100; steps: compact 0, expanded 100. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "progress": { "type": "number", "minimum": 0, "maximum": 1 }, "symbol": { "default": "terminal", "type": "string", "enum": [ "terminal", "code", "build", "success", "warning" ] }, "privacyMode": { "default": "standard", "type": "string", "enum": [ "standard", "private" ] }, "accentColor": { "default": "#246BEB", "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "style": { "default": "standard", "type": "string", "enum": [ "standard", "ring", "hero", "terminal", "steps" ] }, "deviceIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "group": { "type": "string", "pattern": "^dgrp_[A-Za-z0-9_-]{8,64}$" }, "expiresInSeconds": { "default": 28800, "type": "integer", "minimum": 60, "maximum": 28800 }, "staleAfterSeconds": { "default": 14400, "type": "integer", "minimum": 0, "maximum": 28800 } }, "required": [ "title", "status" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveActivityMutation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activities/{identifier}": { "get": { "summary": "Get a Live Activity by ID or key", "operationId": "getActivitiesIdentifier", "security": [ { "bearer": [ "activities:read" ] } ], "x-notify-scopes": [ "activities:read" ], "parameters": [ { "name": "identifier", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "activity": { "$ref": "#/components/schemas/LiveActivity" } }, "required": [ "activity" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a Live Activity", "description": "Use priority: \"high\" for user-visible milestones (APNs 10), bounded to 4 per rolling minute and 20 per rolling hour per activity. Excess requests use APNs 5 with priorityReason: \"budget_exhausted\". Granted milestones remain queue barriers. Default routine updates use APNs 5. These are Notify admission limits, not Apple's unpublished device budget; iOS may still delay or skip states. Updates are accepted durably before an iOS update token is registered, and transient provider rejection remains queued for retry. queued counts pending device operations separately from accepted provider requests and permanent failures. Pending operations expire at the original activity deadline. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status. Expanded budgets (title/line 2/detail): standard 32/36/100; ring 32/30/80; hero 24/36/100; terminal 36/40/100; steps 32/36/100. Compact title/subtitle/detail are hidden; status budget is 8 without progress, except terminal 0.", "operationId": "patchActivitiesIdentifier", "security": [ { "bearer": [ "activities:write" ] } ], "x-notify-scopes": [ "activities:write" ], "parameters": [ { "name": "identifier", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Task title on line 1. Suggested character budgets: standard: compact 0, expanded 32; ring: compact 0, expanded 32; hero: compact 0, expanded 24; terminal: compact 0, expanded 36; steps: compact 0, expanded 32. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "subtitle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional full-word summary used instead of status on expanded Dynamic Island and Lock Screen line 2 only; compact and small banners retain status. Omit to use status; null clears it on update/end. Suggested character budgets: standard: compact 0, expanded 36; ring: compact 0, expanded 30; hero: compact 0, expanded 36; terminal: compact 0, expanded 40; steps: compact 0, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, { "type": "null" } ] }, "status": { "type": "string", "minLength": 1, "maxLength": 60, "description": "Required task state; displayed on line 2 when subtitle is absent. Full status remains available to accessibility. Suggested character budgets: standard: compact 8, expanded 36; ring: compact 8, expanded 30; hero: compact 8, expanded 36; terminal: compact 0, expanded 40; steps: compact 8, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "detail": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240, "description": "Additional context in the two-line detail area, sharing space with line 2 overflow. Suggested character budgets: standard: compact 0, expanded 100; ring: compact 0, expanded 80; hero: compact 0, expanded 100; terminal: compact 0, expanded 100; steps: compact 0, expanded 100. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "symbol": { "type": "string", "enum": [ "terminal", "code", "build", "success", "warning" ] }, "privacyMode": { "type": "string", "enum": [ "standard", "private" ] }, "accentColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "style": { "type": "string", "enum": [ "standard", "ring", "hero", "terminal", "steps" ] }, "staleAfterSeconds": { "type": "integer", "minimum": 0, "maximum": 28800 }, "priority": { "description": "Use high for a user-visible milestone (APNs 10). Limited to 4 per rolling minute and 20 per rolling hour per activity; excess requests use APNs 5. Routine updates default to normal (5). iOS may still delay or skip states.", "type": "string", "enum": [ "normal", "high" ] }, "ifSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveActivityMutation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/activities/{identifier}/end": { "post": { "summary": "End a Live Activity", "description": "Ends the logical activity immediately and accepts device end operations durably, including before an iOS update token arrives. HTTP 200 may have accepted: 0, failed: 0, queued: N. Late token registration flushes pending operations in sequence; queued is not provider acceptance or confirmed device removal. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status. Expanded budgets (title/line 2/detail): standard 32/36/100; ring 32/30/80; hero 24/36/100; terminal 36/40/100; steps 32/36/100. Compact title/subtitle/detail are hidden; status budget is 8 without progress, except terminal 0.", "operationId": "postActivitiesIdentifierEnd", "security": [ { "bearer": [ "activities:write" ] } ], "x-notify-scopes": [ "activities:write" ], "parameters": [ { "name": "identifier", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" }, "required": false } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subtitle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional full-word summary used instead of status on expanded Dynamic Island and Lock Screen line 2 only; compact and small banners retain status. Omit to use status; null clears it on update/end. Suggested character budgets: standard: compact 0, expanded 36; ring: compact 0, expanded 30; hero: compact 0, expanded 36; terminal: compact 0, expanded 40; steps: compact 0, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, { "type": "null" } ] }, "status": { "default": "Complete", "type": "string", "minLength": 1, "maxLength": 60, "description": "Required task state; displayed on line 2 when subtitle is absent. Full status remains available to accessibility. Suggested character budgets: standard: compact 8, expanded 36; ring: compact 8, expanded 30; hero: compact 8, expanded 36; terminal: compact 0, expanded 40; steps: compact 8, expanded 36. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, "detail": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 240, "description": "Additional context in the two-line detail area, sharing space with line 2 overflow. Suggested character budgets: standard: compact 0, expanded 100; ring: compact 0, expanded 80; hero: compact 0, expanded 100; terminal: compact 0, expanded 100; steps: compact 0, expanded 100. Suggested visible-character budgets, not guaranteed fit or API hard limits: proportional glyphs, device width and accessibility text size change fit. 0 means hidden. Expanded and Lock Screen subtitle replaces status on line 2; compact and small banners retain status. Omitted subtitle uses status. Overflow shares the two-line detail area with explicit detail. Compact percentage takes precedence over status when progress is supplied; terminal shows percentage or its prompt icon and never status." }, { "type": "null" } ] }, "progress": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "null" } ] }, "symbol": { "default": "success", "type": "string", "enum": [ "terminal", "code", "build", "success", "warning" ] }, "accentColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "dismissAfterSeconds": { "default": 0, "type": "integer", "minimum": 0, "maximum": 14400 }, "ifSequence": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LiveActivityMutation" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Sequence conflict or activity already terminal" } } } }, "/apps": { "get": { "summary": "List web apps", "operationId": "getApps", "security": [ { "bearer": [ "apps:read" ] } ], "x-notify-scopes": [ "apps:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "$ref": "#/components/schemas/App" } } }, "required": [ "apps" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register a web app (an existing URL is updated)", "operationId": "postApps", "security": [ { "bearer": [ "apps:write" ] } ], "x-notify-scopes": [ "apps:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "iconUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "project": { "type": "string", "minLength": 1, "maxLength": 80 }, "teamId": { "type": "string", "pattern": "^team_[A-Za-z0-9_-]{8,64}$", "description": "Team or free Family ID (team_…) returned by teams_create or teams_list" } }, "required": [ "name", "url" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" }, "created": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "app", "created" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/apps/{id}": { "get": { "summary": "Get a web app", "operationId": "getAppsId", "security": [ { "bearer": [ "apps:read" ] } ], "x-notify-scopes": [ "apps:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" } }, "required": [ "app" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a web app's name, URL, icon, or project", "description": "Personal name/email disclosure preferences and sign-in consent require a signed-in session and cannot be changed here. Moving the URL to a new origin clears consent.", "operationId": "patchAppsId", "security": [ { "bearer": [ "apps:write" ] } ], "x-notify-scopes": [ "apps:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "iconUrl": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "project": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" }, "message": { "type": "string" } }, "required": [ "app" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a web app", "operationId": "deleteAppsId", "security": [ { "bearer": [ "apps:write" ] } ], "x-notify-scopes": [ "apps:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/apps/{id}/revoke": { "post": { "summary": "Revoke this account's sign-in consent; approve again on next open", "description": "Agents can revoke the calling account's consent but cannot grant consent or issue Notify passes. Those actions require a signed-in session.", "operationId": "postAppsIdRevoke", "security": [ { "bearer": [ "apps:write" ] } ], "x-notify-scopes": [ "apps:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" } }, "required": [ "app" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/apps/{id}/share": { "post": { "summary": "Move an app into a team or family, or (teamId null) back to your own apps", "description": "Only the person who added the app can move it. Other members are notified unless `notify` is false, and each approves sign-in for themselves.", "operationId": "postAppsIdShare", "security": [ { "bearer": [ "apps:write" ] } ], "x-notify-scopes": [ "apps:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "teamId": { "anyOf": [ { "type": "string", "pattern": "^team_[A-Za-z0-9_-]{8,64}$", "description": "Team or free Family ID (team_…) returned by teams_create or teams_list" }, { "type": "null" } ] }, "notify": { "type": "boolean" } }, "required": [ "teamId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "app": { "$ref": "#/components/schemas/App" } }, "required": [ "app" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams": { "get": { "summary": "List the teams you belong to", "operationId": "getTeams", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } }, "required": [ "teams" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a family; you become its owner", "description": "Use kind \"family\". New Teams creation (kind \"team\" or omitted) returns 403; existing teams continue operating.", "operationId": "postTeams", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "kind": { "type": "string", "const": "family" } }, "required": [ "name", "kind" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } }, "required": [ "team" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}": { "get": { "summary": "A team and its members", "operationId": "getTeamsId", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } } }, "required": [ "team", "members" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a team (name: admin; auto-join and retention: owner)", "operationId": "patchTeamsId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "autoJoinVerifiedDomain": { "type": "boolean" }, "retentionDays": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 7 }, { "type": "number", "const": 30 }, { "type": "number", "const": 90 }, { "type": "number", "const": 365 } ] }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } }, "required": [ "team" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a team (owner); its apps return to the members who added them", "operationId": "deleteTeamsId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/leave": { "post": { "summary": "Leave a team (the owner must transfer ownership first)", "operationId": "postTeamsIdLeave", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/members/{userId}": { "patch": { "summary": "Change a member's role; `owner` transfers ownership (owner only)", "operationId": "patchTeamsIdMembersUserId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "userId", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "owner", "admin", "member" ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/TeamMember" } }, "required": [ "member" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a member (admin or owner); the owner cannot be removed", "operationId": "deleteTeamsIdMembersUserId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "userId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/invites": { "get": { "summary": "List invites (admin or owner)", "operationId": "getTeamsIdInvites", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "invites": { "type": "array", "items": { "$ref": "#/components/schemas/TeamInvite" } } }, "required": [ "invites" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a 7-day join link (admin or owner)", "description": "Family capacity and administrative member limits apply. Accepting an invite is human-only: there is no agent route for it.", "operationId": "postTeamsIdInvites", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "domain": { "type": "string", "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$" }, "role": { "default": "member", "type": "string", "enum": [ "admin", "member" ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamInviteCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/invites/{inviteId}": { "delete": { "summary": "Revoke an invite", "operationId": "deleteTeamsIdInvitesInviteId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "inviteId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/apps": { "get": { "summary": "The team's shared apps", "operationId": "getTeamsIdApps", "security": [ { "bearer": [ "teams:read", "apps:read" ] } ], "x-notify-scopes": [ "teams:read", "apps:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "items": { "$ref": "#/components/schemas/App" } } }, "required": [ "apps" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/groups": { "get": { "summary": "The team's device groups", "operationId": "getTeamsIdGroups", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceGroup" } } }, "required": [ "groups" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create a device group (admin or owner)", "operationId": "postTeamsIdGroups", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "memberIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "deviceIds": { "default": [], "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/DeviceGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/groups/{groupId}": { "get": { "summary": "A device group", "operationId": "getTeamsIdGroupsGroupId", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/DeviceGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a device group (admin or owner)", "operationId": "patchTeamsIdGroupsGroupId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "memberIds": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "deviceIds": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/DeviceGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete a device group (admin or owner)", "operationId": "deleteTeamsIdGroupsGroupId", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/devices": { "get": { "summary": "Devices belonging to team members (admin or owner)", "operationId": "getTeamsIdDevices", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceGroupDevice" } } }, "required": [ "devices" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/domain": { "post": { "summary": "Request a DNS TXT challenge for an email domain (owner)", "description": "Stores a pending domain (not unique). Publish a TXT record at `_notify-verification.` with value `notify-verify=`, then POST `/teams/{id}/domain/verify`. Public mailbox domains are rejected.", "operationId": "postTeamsIdDomain", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,}$" } }, "required": [ "domain" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" }, "challenge": { "type": "object", "properties": { "domain": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" } }, "required": [ "domain", "host", "value" ] } }, "required": [ "team", "challenge" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Clear the pending or verified domain (owner)", "operationId": "deleteTeamsIdDomain", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } }, "required": [ "team" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/domain/verify": { "post": { "summary": "Verify the pending domain's DNS TXT record (owner)", "description": "Resolves the TXT challenge with a timeout. Resolver errors are cached at most a minute; TXT mismatches are not cached. Rate-limited per team. The verified domain is unique once this succeeds.", "operationId": "postTeamsIdDomainVerify", "security": [ { "bearer": [ "teams:write" ] } ], "x-notify-scopes": [ "teams:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "$ref": "#/components/schemas/Team" } }, "required": [ "team" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/audit": { "get": { "summary": "Audit log (admin or owner); members receive 403", "description": "`from` is inclusive. CSV (`format=csv`) paginates up to 50,000 rows and sets `X-Audit-Truncated: true` when more exist. Formula-like cells are prefixed with a quote.", "operationId": "getTeamsIdAudit", "security": [ { "bearer": [ "teams:read" ] } ], "x-notify-scopes": [ "teams:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "action", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "actor", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "required": false }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "required": false }, { "name": "format", "in": "query", "schema": { "enum": [ "json", "csv" ] }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditLogPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/oncall": { "get": { "summary": "The team's on-call groups with current and upcoming shifts", "operationId": "getTeamsIdOncall", "security": [ { "bearer": [ "oncall:read" ] } ], "x-notify-scopes": [ "oncall:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/OncallGroup" } } }, "required": [ "groups" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create an on-call group (admin or owner)", "operationId": "postTeamsIdOncall", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "rotation": { "type": "object", "properties": { "memberIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "period": { "type": "string", "enum": [ "daily", "weekly" ] }, "handoffAt": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "memberIds", "period", "handoffAt", "timezone" ], "additionalProperties": false }, "escalation": { "default": [ { "afterMinutes": 5, "target": "next" }, { "afterMinutes": 10, "target": "group" } ], "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "afterMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "target": { "type": "string", "enum": [ "next", "group" ] } }, "required": [ "afterMinutes", "target" ], "additionalProperties": false } } }, "required": [ "name", "rotation" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/OncallGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/teams/{id}/pages": { "get": { "summary": "The team's pages, newest first", "operationId": "getTeamsIdPages", "security": [ { "bearer": [ "oncall:read" ] } ], "x-notify-scopes": [ "oncall:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "status", "in": "query", "schema": { "enum": [ "open", "all" ] }, "required": false }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "required": false }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "$ref": "#/components/schemas/OncallPage" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "pages", "nextCursor" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oncall/me": { "get": { "summary": "Your upcoming shifts and the open pages that notified you", "operationId": "getOncallMe", "security": [ { "bearer": [ "oncall:read" ] } ], "x-notify-scopes": [ "oncall:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "shifts": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/OncallShift" }, { "type": "object", "properties": { "groupId": { "type": "string" }, "groupName": { "type": "string" }, "teamId": { "type": "string" }, "teamName": { "type": "string" } }, "required": [ "groupId", "groupName", "teamId", "teamName" ] } ] } }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/OncallPage" } } }, "required": [ "shifts", "pages" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oncall/{groupId}": { "get": { "summary": "An on-call group", "operationId": "getOncallGroupId", "security": [ { "bearer": [ "oncall:read" ] } ], "x-notify-scopes": [ "oncall:read" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/OncallGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Edit a group's name, rotation, or escalation (admin or owner)", "operationId": "patchOncallGroupId", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "rotation": { "type": "object", "properties": { "memberIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "period": { "type": "string", "enum": [ "daily", "weekly" ] }, "handoffAt": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64 }, "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "memberIds", "period", "handoffAt", "timezone" ], "additionalProperties": false }, "escalation": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "afterMinutes": { "type": "integer", "minimum": 1, "maximum": 1440 }, "target": { "type": "string", "enum": [ "next", "group" ] } }, "required": [ "afterMinutes", "target" ], "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/OncallGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete an on-call group (admin or owner)", "operationId": "deleteOncallGroupId", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oncall/{groupId}/overrides": { "post": { "summary": "Put someone on call for a window (admins: anyone; members: themselves)", "operationId": "postOncallGroupIdOverrides", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "userId": { "type": "string", "minLength": 1, "maxLength": 100 }, "startsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "endsAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "userId", "startsAt", "endsAt" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/OncallGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oncall/{groupId}/overrides/{overrideId}": { "delete": { "summary": "Remove an override", "operationId": "deleteOncallGroupIdOverridesOverrideId", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true }, { "name": "overrideId", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "$ref": "#/components/schemas/OncallGroup" } }, "required": [ "group" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oncall/{groupId}/pages": { "post": { "summary": "Page the group: whoever is on call first, then escalation", "description": "Returns 200 with `deduplicated: true` when an open page with the same `dedupKey` absorbed it. Pages have no monthly notification cap.", "operationId": "postOncallGroupIdPages", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "groupId", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "body": { "type": "string", "maxLength": 2000 }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "appId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]{8,64}$" }, "dedupKey": { "type": "string", "minLength": 1, "maxLength": 200 }, "group": { "type": "string", "pattern": "^dgrp_[A-Za-z0-9_-]{8,64}$" } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OncallPageCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pages/{id}": { "get": { "summary": "A page", "description": "There is deliberately no agent route to acknowledge or escalate: an acknowledgement tells the team a person is on it, so only a human can give it (on the phone or in a signed-in session).", "operationId": "getPagesId", "security": [ { "bearer": [ "oncall:read" ] } ], "x-notify-scopes": [ "oncall:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/OncallPage" } }, "required": [ "page" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors": { "get": { "summary": "List tunnel connectors", "operationId": "getConnectors", "security": [ { "bearer": [ "connectors:read" ] } ], "x-notify-scopes": [ "connectors:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/Connector" } } }, "required": [ "connectors" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register a tunnel connector; the callback HMAC secret is returned once", "operationId": "postConnectors", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "tunnelId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+$" }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "routes": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^(@|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$" }, "target": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._[\\]:-]+:\\d{1,5}$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "appId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]{8,64}$" }, "enabled": { "type": "boolean" } }, "required": [ "name", "target", "url" ] } }, "teamId": { "type": "string", "pattern": "^team_[A-Za-z0-9_-]{8,64}$", "description": "Team or free Family ID (team_…) returned by teams_create or teams_list" }, "oncallGroupId": { "type": "string", "pattern": "^ocg_[A-Za-z0-9_-]{8,64}$" } }, "required": [ "name", "tunnelId", "hostname" ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors/{id}": { "get": { "summary": "A tunnel connector", "operationId": "getConnectorsId", "security": [ { "bearer": [ "connectors:read" ] } ], "x-notify-scopes": [ "connectors:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector": { "$ref": "#/components/schemas/Connector" } }, "required": [ "connector" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update a connector's name, routes, or on-call group", "operationId": "patchConnectorsId", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "tunnelId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+$" }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "routes": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^(@|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$" }, "target": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._[\\]:-]+:\\d{1,5}$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "appId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]{8,64}$" }, "enabled": { "type": "boolean" } }, "required": [ "name", "target", "url" ] } }, "oncallGroupId": { "anyOf": [ { "type": "string", "pattern": "^ocg_[A-Za-z0-9_-]{8,64}$" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "online", "offline", "unknown" ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector": { "$ref": "#/components/schemas/Connector" } }, "required": [ "connector" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a tunnel connector", "operationId": "deleteConnectorsId", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true } }, "required": [ "ok" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors/{id}/heartbeat": { "post": { "summary": "Mark a connector online and refresh its last-seen time", "operationId": "postConnectorsIdHeartbeat", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tunnelId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+$" }, "hostname": { "type": "string", "minLength": 1, "maxLength": 253 }, "routes": { "maxItems": 32, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^(@|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)$" }, "target": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._[\\]:-]+:\\d{1,5}$" }, "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "appId": { "type": "string", "pattern": "^app_[A-Za-z0-9_-]{8,64}$" }, "enabled": { "type": "boolean" } }, "required": [ "name", "target", "url" ] } }, "status": { "type": "string", "enum": [ "online", "offline", "unknown" ] }, "graceful": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "connector": { "$ref": "#/components/schemas/Connector" } }, "required": [ "connector" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors/{id}/access": { "post": { "summary": "Connector gateway: consume a one-time Notify pass or revalidate its bound session on every request", "operationId": "postConnectorsIdAccess", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "routeName": { "type": "string" }, "pass": { "type": "string", "minLength": 1, "maxLength": 16384 }, "consume": { "type": "boolean" } }, "required": [ "routeName", "pass", "consume" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "identity": { "type": "object", "properties": { "subject": { "type": "string" }, "appId": { "type": "string" }, "teamId": { "type": [ "string", "null" ] }, "teamRole": { "type": [ "string", "null" ] }, "expiresAt": { "type": "integer" } }, "required": [ "subject", "appId", "teamId", "teamRole", "expiresAt" ] } }, "required": [ "identity" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors/{id}/callback-access": { "post": { "summary": "Connector gateway: authorize one signed, recorded callback delivery and return its saved destination path", "operationId": "postConnectorsIdCallbackAccess", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "routeName": { "type": "string" }, "body": { "type": "string", "minLength": 1, "maxLength": 65536 }, "timestamp": { "type": "string" }, "signature": { "type": "string" } }, "required": [ "routeName", "body", "timestamp", "signature" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" } }, "required": [ "path" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/connectors/{id}/rotate-secret": { "post": { "summary": "Rotate a connector callback HMAC secret; the new secret is returned once", "operationId": "postConnectorsIdRotateSecret", "security": [ { "bearer": [ "connectors:write" ] } ], "x-notify-scopes": [ "connectors:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreated" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pages/{id}/resolve": { "post": { "summary": "Resolve a page; anyone still being paged is cleared", "operationId": "postPagesIdResolve", "security": [ { "bearer": [ "oncall:write" ] } ], "x-notify-scopes": [ "oncall:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "type": "string", "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "$ref": "#/components/schemas/OncallPage" } }, "required": [ "page" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/projects": { "get": { "summary": "Inbox projects with unread counts", "operationId": "getInboxProjects", "security": [ { "bearer": [ "inbox:read" ] } ], "x-notify-scopes": [ "inbox:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxProjects" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/notifications": { "get": { "summary": "Inbox notifications, newest first, with cursor pagination", "operationId": "getInboxNotifications", "security": [ { "bearer": [ "inbox:read" ] } ], "x-notify-scopes": [ "inbox:read" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "required": false }, { "name": "project", "in": "query", "schema": { "type": "string", "description": "Project ID, or `unfiled`." }, "required": false }, { "name": "unread", "in": "query", "schema": { "enum": [ "1", "true" ] }, "required": false }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "required": false } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InboxNotificationPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/notifications/{id}": { "get": { "summary": "One inbox notification with its full body", "operationId": "getInboxNotificationsId", "security": [ { "bearer": [ "inbox:read" ] } ], "x-notify-scopes": [ "inbox:read" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "notification": { "$ref": "#/components/schemas/InboxNotificationDetail" } }, "required": [ "notification" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/notifications/read-all": { "post": { "summary": "Mark everything up to a list response's readThroughToken read", "operationId": "postInboxNotificationsReadAll", "security": [ { "bearer": [ "inbox:write" ] } ], "x-notify-scopes": [ "inbox:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "readThrough": { "type": "string", "minLength": 1, "maxLength": 200 }, "project": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "readThrough" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "const": true }, "updated": { "type": "integer" } }, "required": [ "ok", "updated" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/notifications/{id}/read": { "post": { "summary": "Mark one notification read", "operationId": "postInboxNotificationsIdRead", "security": [ { "bearer": [ "inbox:write" ] } ], "x-notify-scopes": [ "inbox:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMark" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/notifications/{id}/unread": { "post": { "summary": "Mark one notification unread", "operationId": "postInboxNotificationsIdUnread", "security": [ { "bearer": [ "inbox:write" ] } ], "x-notify-scopes": [ "inbox:write" ], "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string" }, "required": true } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadMark" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/billing": { "get": { "summary": "Plan, limits, and remaining usage", "description": "Read-only Free entitlements, unlimited notifications and devices, and per-minute rate limits.", "operationId": "getBilling", "security": [ { "bearer": [ "billing:read" ] } ], "x-notify-scopes": [ "billing:read" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Billing" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown, revoked, or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The token lacks a required scope or the account lacks permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found for this account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "x-notify-scopes": [ "notifications:send", "interactions:create", "interactions:read", "activities:read", "activities:write", "services:read", "services:write", "devices:read", "events:read", "apps:read", "apps:write", "devices:write", "inbox:read", "inbox:write", "billing:read", "tokens:manage", "teams:read", "teams:write", "oncall:read", "oncall:write", "connectors:read", "connectors:write" ] }