The Notifications API from Zeplin — 2 operation(s) for notifications.
openapi: 3.0.2
info:
title: Zeplin Authorization Notifications API
description: Access your resources in Zeplin
version: 1.38.0
contact:
name: Zeplin
url: https://zeplin.io
email: support@zeplin.io
servers:
- url: https://api.zeplin.dev
security:
- PersonalAccessToken: []
- OAuth2: []
tags:
- name: Notifications
paths:
/v1/users/me/notifications:
get:
tags:
- Notifications
summary: Get user notifications
description: List all notifications of the user
operationId: GetUserNotifications
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/is_read'
- $ref: '#/components/parameters/notification_type'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Notification'
examples:
Notifications:
value:
- $ref: '#/components/examples/notification/value'
patch:
tags:
- Notifications
summary: Bulk update user notifications
description: 'Updates all user notifications unless `type` or `id` parameter is given.
If `type` parameter is provided, updates notifications with matching type.
Similarly, updates notifications with matching identifiers if `id` parameter is provided.
☝️ `type` and `id` should not be used in conjunction.
'
operationId: UpdateUserNotifications
parameters:
- $ref: '#/components/parameters/notification_type'
- name: id
in: query
description: 'Filter by id
Example: `?id=5fbe387f8c72ef23659fb500&id=602281f4783f72fccc045484`
'
required: false
schema:
type: array
items:
type: string
pattern: /^[0-9a-f]{24}$/i
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationUpdateBody'
responses:
'204':
$ref: '#/components/responses/noContent'
/v1/users/me/notifications/{notification_id}:
get:
tags:
- Notifications
summary: Get a notification of user
description: Get a notification by id
operationId: GetUserNotification
parameters:
- $ref: '#/components/parameters/notification_id'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Notification'
examples:
response:
$ref: '#/components/examples/notification'
'404':
$ref: '#/components/responses/notificationNotFound'
patch:
tags:
- Notifications
summary: Update user notification
description: Update a notification for the user
operationId: UpdateUserNotification
parameters:
- $ref: '#/components/parameters/notification_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationUpdateBody'
responses:
'204':
$ref: '#/components/responses/noContent'
'404':
$ref: '#/components/responses/notificationNotFound'
components:
schemas:
NotificationTypeEnum:
title: Notification Type
type: string
enum:
- workspace.project
- workspace.styleguide
- project.extension
- styleguide.extension
- user.project_membership
- user.styleguide_membership
- project.component
- styleguide.component
- project.color
- styleguide.color
- project.screen.note
- project.screen.note.comment
- project.screen
- project.text_style
- styleguide.text_style
- project.spacing_token
- styleguide.spacing_token
- project.jira_attachment
- project.screen_section.jira_attachment
- project.screen.jira_attachment
- workspace.organization.member
- project.slack_integration
- styleguide.slack_integration
- project.member
- styleguide.member
- project.flow_board
NotificationUpdateBody:
title: Notifications Update Body
type: object
required:
- is_read
properties:
is_read:
type: boolean
description: New is_read status for notifications
Notification:
title: Notification
description: 'Notification objects have a polymorphic structure. They can be of various types and each type has a certain set of actions that describe the notification further.
Notification content (specifically `resource` and `context` fields) varies based on the value of type field. These variations and their details are described in the table below.
Type | Actions | Context | Resource | Description
--| --| --| --| --
`workspace.project` | `activated`<br />`archived`<br />`deleted`<br />`ownership_transferred` | - | `Project (extra: { name, platform })` | Used for changes related to projects in a workspace.
`workspace.styleguide` | `activated`<br />`archived`<br />`deleted`<br />`ownership_transferred` | - | `Styleguide (extra: { name, platform })` | Used for changes related to styleguides in a workspace.
`workspace.organization.member` | `role_updated`<br />`invited` | `Organization (extra: { name })` | `OrganizationMember (extra: { role })` | Used for changes related to members of a workspace.
`project.screen` | `created`<br />`version_created`<br />`deleted` | `Project (extra: { name, platform })`<br />`ScreenVersion (extra: { image_url, thumbnails, width, height })` | `Screen (extra: { name })` | Used for changes related to screens in a project.
`project.screen.note` | `created`<br />`mentioned` | `Project (extra: { name, platform })`<br />`Screen (extra: { name })`<br />`ScreenNoteComment (extra: { content })` | `Screen (extra: { order, color, status })` | Used for changes related to notes.
`project.screen.note.comment` | `created`<br />`mentioned` | `Project (extra: { name, platform })`<br />`Screen (extra: { name })`<br />`Screen (extra: { order, color, status })` | `ScreenNoteComment (extra: { content })` | Used for changes related to note comments.
`project.color` | `created`<br />`updated`<br />`deleted` | `Project (extra: { name, platform })` | `Color (extra: { name, r, g, b, a })` | Used for changes related to colors in a project.
`project.text_style` | `created`<br />`updated`<br />`deleted` | `Project (extra: { name, platform })` | `TextStyle (extra: { name })` | Used for changes related to text styles in a project.
`project.component` | `created`<br />`version_created`<br />`deleted` | `Project (extra: { name, platform })` | `Component (extra: { name })` | Used for changes related to components in a project.
`project.spacing_token` | `created`<br />`updated`<br />`deleted` | `Project (extra: { name, platform })` | `SpacingToken (extra: { name, value })` | Used for changes related to spacing tokens in a project.
`project.member` | `joined` | `Project (extra: { name, platform })` | | Used for changes related to members of a project.
`project.extension` | `added`<br />`removed` | `Project (extra: { name, platform })` | `Extension (extra: { name })` | Used for changes related to extensions in a project.
`project.slack_integration` | `added` | `Project (extra: { name, platform })` | `SlackIntegration (extra: { channel })` | Used for changes related to slack intgrations in a project.
`project.jira_attachment` | `added`<br />`removed` | `Project (extra: { name, platform })` | `JiraIntegration (extra: { issue })` | Used for changes related to jira attachments in a project.
`project.screen.jira_attachment` | `added`<br />`removed` | `Project (extra: { name, platform })`<br />`Screen (extra: { name })` | `JiraIntegration (extra: { issue })` | Used for changes related to jira attachments in a screen.
`project.screen_section.jira_attachment` | `added`<br />`removed` | `Project (extra: { name, platform })`<br />`ScreenSection (extra: { name })` | `JiraIntegration (extra: { issue })` | Used for changes related to jira attachments in a screen section.
`project.flow_board` | `added` | `Project (extra: { name, platform })` | `FlowBoard (extra: {})` | Used for changes related to flow boards in a project.
`styleguide.color` | `created`<br />`updated`<br />`deleted` | `Styleguide (extra: { name, platform })` | `Color (extra: { name, r, g, b, a })` | Used for changes related to colors in a styleguide.
`styleguide.text_style` | `created`<br />`updated`<br />`deleted` | `Styleguide (extra: { name, platform })` | `TextStyle (extra: { name })` | Used for changes related to text styles in a styleguide.
`styleguide.component` | `created`<br />`version_created`<br />`deleted` | `Styleguide (extra: { name, platform })` | `Component (extra: { name })` | Used for changes related to components in a styleguide.
`styleguide.spacing_token` | `created`<br />`updated`<br />`deleted` | `Styleguide (extra: { name, platform })` | `SpacingToken (extra: { name, value })` | Used for changes related to spacing tokens in a styleguide.
`styleguide.member` | `joined` | `Styleguide (extra: { name, platform })` | `User (extra: { username })` | Used for changes related to members of a styleguide.
`styleguide.extension` | `added`<br />`removed` | `Styleguide (extra: { name, platform })` | `Extension (extra: { name })` | Used for changes related to extensions in a styleguide.
`styleguide.slack_integration` | `added` | `Styleguide (extra: { name, platform })` | `SlackIntegration (extra: { channel })` | Used for changes related to slack intgrations in a styleguide.
`user.project_membership` | `invited`<br />`role_updated`<br />`removed` | - | `Project (extra: { name, platform })` | Used for changes related to notified user''s membership to projects.
`user.styleguide_membership` | `invited`<br />`role_updated`<br />`removed` | - | `Styleguide (extra: { name, platform })` | Used for changes related to notified user''s membership to styleguides.
'
type: object
required:
- id
- type
- is_read
- action
- created
- updated
- context
- actor
properties:
id:
type: string
description: The unique id of the notification
type:
allOf:
- $ref: '#/components/schemas/NotificationTypeEnum'
- description: Type of the notification
is_read:
type: boolean
description: Whether the notification is read or not
action:
type: string
description: Action that causes the notification
created:
type: integer
format: timestamp
description: The unix timestamp when the screen was created
updated:
type: integer
format: timestamp
description: The unix timestamp when the screen was updated
resource:
$ref: '#/components/schemas/NotificationResource'
context:
type: object
description: 'Additional objects which are related to the main resource object. The content of this object changes depending on the `type` field (e.g. `{ project: { ... }, screen: { ... } }` for a screen related notification).'
actor:
$ref: '#/components/schemas/NotificationActor'
example:
$ref: '#/components/examples/notification'
ErrorResponse:
title: Error Response
type: object
required:
- message
properties:
message:
type: string
description: A user readable descriptive message for the error
detail:
type: string
description: A detailed message describing the error
code:
type: string
description: The unique code for the error
example:
$ref: '#/components/examples/error'
User:
title: User
description: 'Basic info about Zeplin users.
Zeplin API does not expose any personal information to third-party clients. For this reason, the `email` field is a Zeplin-only alias by default.
You can get the original email addresses of members of your workspace by using a personal access token created with admin rights. Third-party (OAuth) applications are not allowed to access this information.
☝️*Only organization admins (or higher) can retrieve the original email addresses using an admin token.*
'
type: object
required:
- id
- email
- username
properties:
id:
type: string
description: User's unique id
email:
type: string
description: Zeplin-only alias for the user's email (original)
username:
type: string
description: Username of the user
emotar:
type: string
format: emoji
description: Emotar of the user
avatar:
type: string
description: Avatar of the user
last_seen:
type: number
description: The unix timestamp when the user was last seen
example:
$ref: '#/components/examples/user'
x-examples:
User:
$ref: '#/components/examples/user'
My User:
$ref: '#/components/examples/me'
NotificationResource:
title: Notification Resource
type: object
description: The main object that this notification is related. It contains the ID of the object along with its type and partial data. The content of this object varies between notification types.
required:
- id
- type
- extra
properties:
id:
type: string
description: The unique id of the resource (e.g. `"5ed05ecf3356a7967b21f12b"`)
type:
type: string
description: Type of the object, which is one of the API models (e.g. `"ScreenVersion"`)
extra:
type: object
description: Partial data of the resource, whose content changes depending on the `type` field
example:
$ref: '#/components/examples/notificationResource'
NotificationActor:
title: Notification Actor
type: object
description: The actor of the change triggering this notification
required:
- user
properties:
user:
$ref: '#/components/schemas/User'
description: User object
example:
$ref: '#/components/examples/notificationActor'
parameters:
notification_id:
name: notification_id
in: path
description: Notification id
required: true
schema:
type: string
pattern: /^[0-9a-f]{24}$/i
limit:
name: limit
in: query
description: Pagination limit
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 30
offset:
name: offset
in: query
description: Pagination offset
required: false
schema:
type: integer
minimum: 0
default: 0
notification_type:
name: type
in: query
description: 'Filter by type
Example: `?type=project.extension&type=styleguide.extension`
'
required: false
schema:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/NotificationTypeEnum'
is_read:
name: is_read
in: query
description: Whether the notification is read or not
required: false
schema:
type: boolean
examples:
user:
summary: User
value:
id: 5d9caaecb4a3fa9bc9718686
email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
username: zozo
emotar: 🍎
avatar: http://placekitten.com/200/300
last_seen: 1616739240
notificationResource:
summary: Notification Resource
value:
id: 5dbad85a76ea51c1f35b6f69
type: Color
extra:
name: baby poop green
r: 143
g: 152
b: 5
a: 1
notification:
summary: Notification
value:
id: 5fbe387f8c72ef23659fb500
timestamp: 1586852836
type: project.color
action: created
is_read: false
resource:
$ref: '#/components/examples/notificationResource/value'
context:
project:
id: 5db81e73e1e36ee19f138c1a
type: Project
extra:
name: HAL 9000
platform: web
actor:
$ref: '#/components/examples/notificationActor/value'
notificationActor:
summary: Notification Actor
value:
user:
$ref: '#/components/examples/user/value'
error:
summary: Error
value:
message: Project is not found
me:
summary: My user
value:
id: 5d9caaecb4a3fa9bc9718686
email: zo@zeplin.io
username: zozo
emotar: 🍎
avatar: http://placekitten.com/200/300
last_seen: 1616739240
responses:
noContent:
description: Successful response
notificationNotFound:
description: Notification not found response
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Notification not found response:
value:
message: Notification not found
securitySchemes:
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: /v1/oauth/authorize
tokenUrl: /v1/oauth/token
refreshUrl: /v1/oauth/token
scopes: {}
PersonalAccessToken:
type: http
scheme: bearer
bearerFormat: JWT