Notifications - Zou (Kitsu API)

Kitsu’s notification system keeps users informed about comments, mentions, task assignments, and replies on tasks they’re involved with.

Notification Types

Notifications are created automatically for various events:

comment - New comment on a subscribed task
mention - User mentioned in a comment
reply - Reply to a comment thread
reply-mention - User mentioned in a reply
assignation - Task assigned to user
playlist-ready - Playlist ready for client review

Get User Notifications

Query Parameters

after

string

Filter notifications created after this date (ISO 8601 format)

before

string

Filter notifications created before this date (ISO 8601 format)

task_type_id

string

Filter by task type UUID

task_status_id

string

Filter by task status UUID

type

string

Filter by notification type (comment, mention, reply, assignation, etc.)

read

boolean

Filter by read status (true for read, false for unread)

watching

boolean

Filter by watching status

Example Requests

curl -X GET "https://your-kitsu-instance.com/api/data/user/notifications?read=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

notifications

array

Array of notification objects

string

Notification UUID

type

string

Notification type (comment, mention, reply, assignation, etc.)

read

boolean

Whether the notification has been read

change

boolean

Whether this notification represents a status change

author_id

string

UUID of the person who triggered the notification

person_id

string

UUID of the notification recipient

comment_id

string

UUID of the related comment (if applicable)

reply_id

string

UUID of the related reply (if applicable)

task_id

string

UUID of the related task

playlist_id

string

UUID of the related playlist (for playlist-ready notifications)

created_at

string

Notification creation timestamp (ISO 8601)

updated_at

string

Last update timestamp (ISO 8601)

Example Response

[
  {
    "id": "a24a6ea4-ce75-4665-a070-57453082c25",
    "type": "comment",
    "read": false,
    "change": false,
    "author_id": "b35b7fb5-df86-5776-b181-68564193d36",
    "person_id": "c46c8gc6-eg97-6887-c292-79675204e47",
    "comment_id": "d57d9hd7-fh08-7998-d403-80786315f58",
    "reply_id": null,
    "task_id": "e68e0ie8-gi19-8009-e514-91897426g69",
    "playlist_id": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  {
    "id": "f79f1jf9-hj20-9010-f625-a09008537h80",
    "type": "mention",
    "read": true,
    "change": false,
    "author_id": "g80g2kg0-ik31-0121-g736-b10119648i91",
    "person_id": "c46c8gc6-eg97-6887-c292-79675204e47",
    "comment_id": "h91h3lh1-jl42-1232-h847-c21220759j02",
    "reply_id": null,
    "task_id": "i02i4mi2-km53-2343-i958-d32331860k13",
    "playlist_id": null,
    "created_at": "2024-01-15T09:15:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

Get Specific Notification

Path Parameters

notification_id

string

required

UUID of the notification

Example Request

cURL

curl -X GET "https://your-kitsu-instance.com/api/data/user/notifications/a24a6ea4-ce75-4665-a070-57453082c25" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "id": "a24a6ea4-ce75-4665-a070-57453082c25",
  "type": "comment",
  "read": false,
  "change": false,
  "author_id": "b35b7fb5-df86-5776-b181-68564193d36",
  "person_id": "c46c8gc6-eg97-6887-c292-79675204e47",
  "comment_id": "d57d9hd7-fh08-7998-d403-80786315f58",
  "task_id": "e68e0ie8-gi19-8009-e514-91897426g69",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Update Notification

Path Parameters

notification_id

string

required

UUID of the notification

Request Body

read

boolean

required

Mark notification as read (true) or unread (false)

Example Requests

curl -X PUT "https://your-kitsu-instance.com/api/data/user/notifications/a24a6ea4-ce75-4665-a070-57453082c25" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read": true}'

Response

{
  "id": "a24a6ea4-ce75-4665-a070-57453082c25",
  "type": "comment",
  "read": true,
  "change": false,
  "author_id": "b35b7fb5-df86-5776-b181-68564193d36",
  "person_id": "c46c8gc6-eg97-6887-c292-79675204e47",
  "comment_id": "d57d9hd7-fh08-7998-d403-80786315f58",
  "task_id": "e68e0ie8-gi19-8009-e514-91897426g69",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Mark All Notifications as Read

Example Requests

curl -X POST "https://your-kitsu-instance.com/api/actions/user/notifications/mark-all-as-read" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "success": true
}

Task Subscriptions

Users can subscribe to tasks to receive notifications about comments and changes.

Check Task Subscription

Path Parameters

task_id

string

required

UUID of the task

cURL

curl -X GET "https://your-kitsu-instance.com/api/data/user/tasks/e68e0ie8-gi19-8009-e514-91897426g69/subscribed" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "subscribed": true
}

Path Parameters

task_id

string

required

UUID of the task to subscribe to

curl -X POST "https://your-kitsu-instance.com/api/actions/user/tasks/e68e0ie8-gi19-8009-e514-91897426g69/subscribe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "id": "j13j5nj3-ln64-3454-j069-e43442971l24",
  "person_id": "c46c8gc6-eg97-6887-c292-79675204e47",
  "task_id": "e68e0ie8-gi19-8009-e514-91897426g69",
  "entity_id": null,
  "task_type_id": null,
  "created_at": "2024-01-15T11:00:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Unsubscribe from Task

Path Parameters

task_id

string

required

UUID of the task to unsubscribe from

curl -X DELETE "https://your-kitsu-instance.com/api/actions/user/tasks/e68e0ie8-gi19-8009-e514-91897426g69/unsubscribe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

Returns HTTP 204 No Content on success.

Sequence Subscriptions

Subscribe to all tasks of a specific type within a sequence.

Check Sequence Subscription

Path Parameters

sequence_id

string

required

UUID of the sequence

task_type_id

string

required

UUID of the task type

cURL

curl -X GET "https://your-kitsu-instance.com/api/data/user/entities/k24k6ok4-mo75-4565-k170-f54553082m35/task-types/l35l7pl5-np86-5676-l281-g65664193n46/subscribed" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Path Parameters

sequence_id

string

required

UUID of the sequence

task_type_id

string

required

UUID of the task type

cURL

curl -X POST "https://your-kitsu-instance.com/api/actions/user/sequences/k24k6ok4-mo75-4565-k170-f54553082m35/task-types/l35l7pl5-np86-5676-l281-g65664193n46/subscribe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Unsubscribe from Sequence

cURL

curl -X DELETE "https://your-kitsu-instance.com/api/actions/user/sequences/k24k6ok4-mo75-4565-k170-f54553082m35/task-types/l35l7pl5-np86-5676-l281-g65664193n46/unsubscribe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Sequence Subscriptions

Path Parameters

project_id

string

required

UUID of the project

task_type_id

string

required

UUID of the task type

cURL

curl -X GET "https://your-kitsu-instance.com/api/data/user/projects/m46m8qm6-oq97-6787-m392-h76775204o57/task-types/l35l7pl5-np86-5676-l281-g65664193n46/sequence-subscriptions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

[
  "k24k6ok4-mo75-4565-k170-f54553082m35",
  "n57n9rn7-pr08-7898-n403-i87886315p68"
]

Real-time Notification Events

When a new notification is created, a real-time event is emitted through the WebSocket event stream:

import io from 'socket.io-client';

const socket = io('https://your-kitsu-instance.com', {
  path: '/socket.io',
  transports: ['websocket'],
  auth: { token: 'YOUR_JWT_TOKEN' }
});

socket.on('notification:new', (data) => {
  console.log('New notification:', data);
  // data contains: { notification_id, person_id }
  
  // Fetch full notification details
  fetchNotification(data.notification_id);
});

socket.on('notification:all-read', (data) => {
  console.log('All notifications marked as read for user:', data.person_id);
  // Update UI to reflect all notifications as read
});

See the Event Stream documentation for more details on WebSocket connections.

How Notifications Are Created

Comment Notifications

When a comment is posted on a task:

All users assigned to the task receive a notification
All users subscribed to the task receive a notification
All users subscribed to the parent sequence (if applicable) receive a notification
The comment author does not receive a notification

Mention Notifications

When a user is @mentioned in a comment or reply:

The mentioned user receives a mention or reply-mention notification
An email is sent to the mentioned user (if email notifications are enabled)

Assignment Notifications

When a task is assigned:

Each assigned user receives an assignation notification
An email is sent to the assigned users (if email notifications are enabled)
The assigner does not receive a notification for their own assignment

Playlist Ready Notifications

When a playlist is marked as ready for client review:

All clients with access to the project receive a playlist-ready notification
Optionally filtered by studio and/or department
An email is sent to notify clients

Best Practices

Poll for New Notifications: If not using WebSockets, poll the /data/user/notifications?read=false endpoint periodically (e.g., every 30-60 seconds) to check for new notifications.
Mark as Read Promptly: When a user views a notification or the related content, mark it as read to keep the notification list clean.
Use Bulk Operations: Use the mark-all-as-read endpoint when appropriate rather than updating notifications one by one.
Filter Intelligently: Use query parameters to fetch only relevant notifications based on context (e.g., only unread, specific task type).
Subscribe to Relevant Tasks: Encourage users to subscribe to tasks they’re interested in to stay informed without being overwhelmed.
WebSocket Integration: Use the WebSocket event stream for real-time notification delivery in the UI for the best user experience.

Authentication

Projects

Assets

Shots & Sequences

Tasks

Files & Previews

People & Teams

Comments & Playlists

Events & Notifications

Documentation Index

​Notification Types

​Get User Notifications

​Query Parameters

​Example Requests

​Response

​Get Specific Notification

​Path Parameters

​Example Request

​Response

​Update Notification

​Path Parameters

​Request Body

​Example Requests

​Response

​Mark All Notifications as Read

​Example Requests

​Response

​Task Subscriptions

​Check Task Subscription

​Path Parameters

​Subscribe to Task

​Path Parameters

​Response

​Unsubscribe from Task

​Path Parameters

​Response

​Sequence Subscriptions

​Check Sequence Subscription

​Path Parameters

​Subscribe to Sequence

​Path Parameters

​Unsubscribe from Sequence

​Get Sequence Subscriptions

​Path Parameters

​Real-time Notification Events

​How Notifications Are Created

​Comment Notifications

​Mention Notifications

​Assignment Notifications

​Playlist Ready Notifications

​Best Practices

Build docs developers (and LLMs) love

Notification Types

Get User Notifications

Query Parameters

Example Requests

Response

Get Specific Notification

Path Parameters

Example Request

Response

Update Notification

Path Parameters

Request Body

Example Requests

Response

Mark All Notifications as Read

Example Requests

Response

Task Subscriptions

Check Task Subscription

Path Parameters

Subscribe to Task

Path Parameters

Response

Unsubscribe from Task

Path Parameters

Response

Sequence Subscriptions

Check Sequence Subscription

Path Parameters

Subscribe to Sequence

Path Parameters

Unsubscribe from Sequence

Get Sequence Subscriptions

Path Parameters

Real-time Notification Events

How Notifications Are Created

Comment Notifications

Mention Notifications

Assignment Notifications

Playlist Ready Notifications

Best Practices