API reference

Notifications and protocols

Your notifications, and an organization's notification protocols.

See Notifications and the phone assistant for how events, channels, quiet hours and protocols work.

`GET /v1/me/notifications`

Your notifications, newest first (cursor, limit): title, body, link, read, and whether one waits for an acknowledgement (escalating alerts). People only.

Auth: user access token or platform agent key

Query parameter	Type	Required	Notes
`cursor`	`string`	No	up to 2,000 characters
`limit`	`integer`	No	1–100; coerced from a string

Response 200

{
  notices: {
    noticeId: string
    orgId?: string
    event: string
    title: string
    body?: string
    url?: string
    read?: boolean
    requireAck?: boolean
    ackedAt?: number
    createdAt?: number
  }[]
  cursor: null | string
}

Errors

Status	Message
`403`	Notifications belong to people.

`POST /v1/me/notifications/read`

Marks notifications read (noticeIds, up to 100).

Auth: user access token or platform agent key

Request body

Field	Type	Required	Notes
`noticeIds`	`string[]`	Yes	1–100 items; each up to 64 characters

Response 200

{
  ok: true
}

Errors

Status	Message
`403`	Notifications belong to people.

`POST /v1/me/notifications/:noticeId/ack`

Acknowledges a notification: its escalation (later texts or calls) stops. acked: false when it already was.

Auth: user access token or platform agent key

Path parameter	Description
`:noticeId`	Notification id (`nte_…`).

Response 200

{
  acked: boolean
}

Errors

Status	Message
`403`	Notifications belong to people.

`GET /v1/orgs/:orgId/notify/protocols/templates`

Ready-made notification protocols (production on-call, meeting guard, invitation chaser, VIP mail, service desk SLA, agent jobs).

Auth: user access token or platform agent key

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  templates: {
    id: string
    name: string
    description: string
    rules: {
      events: ("issue.sla_breached" | "deployment.ready" | "deployment.failed" | "account.new_sign_in" | "domain.verified" | "domain.failed" | "issue.assigned" | "issue.mentioned" | "calendar.invite_unanswered" | "calendar.meeting_soon" | "mail.vip" | "agent.job_done" | "agent.job_failed" | "ops.alarm")[]
      match?: {
        [key: string]: string[]
      }
      steps: {
        afterMinutes: number
        channels: object
      }[]
      beforeEvent?: boolean
      roles?: ("owner" | "admin" | "developer" | "viewer")[]
      userIds?: string[]
      overrideQuietHours?: boolean
    }[]
  }[]
}

`GET /v1/orgs/:orgId/notify/protocols`

The organization's notification protocols with their rules and what each is attached to.

Auth: user access token or platform agent key · Scope: org:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  protocols: {
    protocolId: string
    orgId: string
    name: string
    description?: string
    enabled: boolean
    rules: {
      events: ("issue.sla_breached" | "deployment.ready" | "deployment.failed" | "account.new_sign_in" | "domain.verified" | "domain.failed" | "issue.assigned" | "issue.mentioned" | "calendar.invite_unanswered" | "calendar.meeting_soon" | "mail.vip" | "agent.job_done" | "agent.job_failed" | "ops.alarm")[]
      match?: {
        [key: string]: string[]
      }
      steps: {
        afterMinutes: number
        channels: object
      }[]
      beforeEvent?: boolean
      roles?: ("owner" | "admin" | "developer" | "viewer")[]
      userIds?: string[]
      overrideQuietHours?: boolean
    }[]
    createdBy: string
    updatedAt?: number
    attachments: {
      resourceType: "org" | "project" | "agent" | "mailbox" | "calendar" | "space"
      resourceId: string
      resourceLabel?: string
    }[]
  }[]
}

`POST /v1/orgs/:orgId/notify/protocols`

Creates a protocol from { template } or { name, description?, enabled?, rules } (rules: events, optional match on event attributes, steps with minutes and channels, roles, overrideQuietHours, beforeEvent). Owners and admins.

Auth: user access token or platform agent key · Scope: org:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 201

{
  protocol: {
    attachments: []
    protocolId: string
    orgId: string
    name: string
    description?: string
    enabled: boolean
    rules: {
      events: ("issue.sla_breached" | "deployment.ready" | "deployment.failed" | "account.new_sign_in" | "domain.verified" | "domain.failed" | "issue.assigned" | "issue.mentioned" | "calendar.invite_unanswered" | "calendar.meeting_soon" | "mail.vip" | "agent.job_done" | "agent.job_failed" | "ops.alarm")[]
      match?: {
        [key: string]: string[]
      }
      steps: {
        afterMinutes: number
        channels: ("email" | "voice" | "sms" | "inapp")[]
      }[]
      beforeEvent?: boolean
      roles?: ("owner" | "admin" | "developer" | "viewer")[]
      userIds?: string[]
      overrideQuietHours?: boolean
    }[]
    createdBy: string
    updatedAt?: number
  }
}

`GET /v1/orgs/:orgId/notify/protocols/:protocolId`

One protocol with its attachments.

Auth: user access token or platform agent key · Scope: org:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:protocolId`	Notification protocol id (`npr_…`).

Response 200

{
  protocol: {
    protocolId: string
    orgId: string
    name: string
    description?: string
    enabled: boolean
    rules: {
      events: ("issue.sla_breached" | "deployment.ready" | "deployment.failed" | "account.new_sign_in" | "domain.verified" | "domain.failed" | "issue.assigned" | "issue.mentioned" | "calendar.invite_unanswered" | "calendar.meeting_soon" | "mail.vip" | "agent.job_done" | "agent.job_failed" | "ops.alarm")[]
      match?: {
        [key: string]: string[]
      }
      steps: {
        afterMinutes: number
        channels: ("email" | "voice" | "sms" | "inapp")[]
      }[]
      beforeEvent?: boolean
      roles?: ("owner" | "admin" | "developer" | "viewer")[]
      userIds?: string[]
      overrideQuietHours?: boolean
    }[]
    createdBy: string
    updatedAt?: number
    attachments: {
      resourceType: "org" | "project" | "agent" | "mailbox" | "calendar" | "space"
      resourceId: string
      resourceLabel?: string
    }[]
  }
}

`PUT /v1/orgs/:orgId/notify/protocols/:protocolId`

Replaces a protocol's name, description, on/off and rules. Owners and admins.

Auth: user access token or platform agent key · Scope: org:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:protocolId`	Notification protocol id (`npr_…`).

Request body

Field	Type	Required	Notes
`name`	`string`	Yes	1–80 characters; trimmed
`description`	`string`	No	up to 300 characters
`enabled`	`boolean`	No
`rules`	`object[]`	Yes	1–20 items
`rules[].events`	`[]`	Yes	at least 1 item
`rules[].match`	`object`	No	values: string[] (up to 20 items, each up to 200 characters)
`rules[].steps`	`object[]`	Yes	1–6 items
`rules[].steps[].afterMinutes`	`integer`	Yes	0–10080
`rules[].steps[].channels`	`("inapp" \| "email" \| "sms" \| "voice")[]`	Yes	at least 1 item
`rules[].beforeEvent`	`boolean`	No
`rules[].roles`	`("owner" \| "admin" \| "developer" \| "viewer")[]`	No
`rules[].userIds`	`string[]`	No	up to 50 items; each up to 64 characters
`rules[].overrideQuietHours`	`boolean`	No

Response 200

{
  protocol: {
    protocolId: string
    orgId: string
    name: string
    description?: string
    enabled: boolean
    rules: {
      events: ("issue.sla_breached" | "deployment.ready" | "deployment.failed" | "account.new_sign_in" | "domain.verified" | "domain.failed" | "issue.assigned" | "issue.mentioned" | "calendar.invite_unanswered" | "calendar.meeting_soon" | "mail.vip" | "agent.job_done" | "agent.job_failed" | "ops.alarm")[]
      match?: {
        [key: string]: string[]
      }
      steps: {
        afterMinutes: number
        channels: ("email" | "voice" | "sms" | "inapp")[]
      }[]
      beforeEvent?: boolean
      roles?: ("owner" | "admin" | "developer" | "viewer")[]
      userIds?: string[]
      overrideQuietHours?: boolean
    }[]
    createdBy: string
    updatedAt?: number
    attachments: {
      resourceType: "org" | "project" | "agent" | "mailbox" | "calendar" | "space"
      resourceId: string
      resourceLabel?: string
    }[]
  }
}

`DELETE /v1/orgs/:orgId/notify/protocols/:protocolId`

Deletes a protocol and its attachments. Owners and admins.

Auth: user access token or platform agent key · Scope: org:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:protocolId`	Notification protocol id (`npr_…`).

Response 204 with no body.

`POST /v1/orgs/:orgId/notify/protocols/:protocolId/attachments`

Attaches the protocol to { type, id, label? }: the whole organization (org) or a project, Issues space, calendar, mailbox or agent. Events about it then follow the protocol. Owners and admins.

Auth: user access token or platform agent key · Scope: org:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:protocolId`	Notification protocol id (`npr_…`).

Request body

Field	Type	Required	Notes
`type`	`"org" \| "project" \| "space" \| "calendar" \| "mailbox" \| "agent"`	Yes
`id`	`string`	Yes	1–128 characters
`label`	`string`	No	up to 120 characters

Response 201

{
  ok: true
}

`DELETE /v1/orgs/:orgId/notify/protocols/:protocolId/attachments/:resourceType/:targetId`

Detaches the protocol from that resource. Owners and admins.

Auth: user access token or platform agent key · Scope: org:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:protocolId`	Notification protocol id (`npr_…`).
`:resourceType`	What the protocol is attached to: `org`, `project`, `space`, `calendar`, `mailbox` or `agent`.
`:targetId`	Id of what it's attached to (the org's own id for `org`, else `prj_…`, `spc_…`, `cal_…`, `mbx_…`, `dev_…`).

Response 204 with no body.

Errors

Status	Message
`400`	Unknown resource type.

Notifications and protocols

On this page