Skip to content
Sayr

API Reference V1
Updated on

Tommy Lundy Tommy Lundy

Version:1.0.0OpenAPI 3.1.0

Sayr.io public API v1 documentation.

Base URL:https://api.sayr.io/v1

Organization

Section titled "Organization"
GET /organization/{org_slug}

Get organization

Retrieve public information for an organization identified by its slug.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string Organization UUID
data.slug * string Organization slug used in URLs
data.name * string Organization name
data.logo * string | null Organization logo URL
data.bannerImg * string | null Organization banner image URL
data.eventsUrl * string Public: URL to fetch organization events for live updates
data.members * object[] List of organization members with public info
data.members[].id * string User ID
data.members[].name * string member name
data.members[].image * string | null avatar URL
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}
KeyValue
org_slug*
GET /organization/{org_slug}/labels

List organization labels

Retrieve all public labels associated with an organization.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -

Responses

200 Success
Field Type Description
success * true -
data * object[] -
data[].id * string Label UUID
data[].organizationId * string ID of the organization this label belongs to
data[].name * string Label name
data[].color * string Label color in hsla code
data[].visible * "public" | "private" Label visibility
data[].createdAt * string Label creation timestamp in ISO format
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/labels
KeyValue
org_slug*
GET /organization/{org_slug}/categories

List organization categories

Retrieve all public categories associated with an organization.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -

Query Parameters

Name Type Required Description
order "asc" | "desc" No Specifies the sort order by creation date. Use asc for ascending or desc for descending.

Responses

200 Success
Field Type Description
success * true -
data * object[] -
data[].id * string Category UUID
data[].organizationId * string ID of the organization this category belongs to
data[].name * string Category name
data[].color * string Category color in hsla code
data[].icon * string | null Category icon URL or identifier
data[].createdAt * string Category creation timestamp in ISO format
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/categories
KeyValue
org_slug*
order
GET /organization/{org_slug}/tasks

List organization tasks

Retrieve a paginated list of public tasks for an organization.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -

Query Parameters

Name Type Required Description
order "asc" | "desc" No Specifies the sort order by creation date. Use asc for ascending or desc for descending.
limit integer No Number of items per page
page integer No Page number (starting from 1)

Responses

200 Paginated list
Field Type Description
success * true -
data * object[] -
data[].id * string Task UUID
data[].organizationId * string ID of the organization this task belongs to
data[].shortId * number Short numeric ID unique within the organization
data[].visible * "public" Task visibility
data[].createdAt * string Task creation timestamp in ISO format
data[].updatedAt * string Task last update timestamp in ISO format
data[].title * string Task title
data[].description * string Task description in blocknote JSON format
data[].status * "backlog" | "todo" | "in-progress" | "done" | "cancelled" Task status
data[].priority * "none" | "low" | "medium" | "high" | "urgent" Task priority
data[].createdBy * object | null User who created the task
data[].category * object | null Category associated with the task
data[].labels * object[] List of labels associated with the task
data[].labels[].id * string Label UUID
data[].labels[].organizationId * string ID of the organization this label belongs to
data[].labels[].name * string Label name
data[].labels[].color * string Label color in hsla code
data[].labels[].visible * "public" | "private" Label visibility
data[].labels[].createdAt * string Label creation timestamp in ISO format
data[].releaseId * string | null ID of the release this task is associated with
data[].voteCount * number Number of votes the task has received
data[].parentId * string | null ID of the parent task if this is a subtask
data[].descriptionHtml * string Task description rendered as HTML
data[].descriptionMarkdown * string Task description rendered as Markdown
pagination * object -
pagination.limit * number -
pagination.page * number -
pagination.totalPages * number -
pagination.totalItems * number -
pagination.hasMore * boolean -
400 Invalid pagination parameters
Field Type Description
success * false -
error * string -
message string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
500 Server error
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/tasks
KeyValue
org_slug*
order
limit
page
GET /organization/{org_slug}/tasks/{task_short_id}

Get task

Retrieve a public task by its short identifier.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
task_short_id integer Yes -

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string Task UUID
data.organizationId * string ID of the organization this task belongs to
data.shortId * number Short numeric ID unique within the organization
data.visible * "public" Task visibility
data.createdAt * string Task creation timestamp in ISO format
data.updatedAt * string Task last update timestamp in ISO format
data.title * string Task title
data.description * string Task description in blocknote JSON format
data.status * "backlog" | "todo" | "in-progress" | "done" | "cancelled" Task status
data.priority * "none" | "low" | "medium" | "high" | "urgent" Task priority
data.createdBy * object | null User who created the task
data.category * object | null Category associated with the task
data.labels * object[] List of labels associated with the task
data.labels[].id * string Label UUID
data.labels[].organizationId * string ID of the organization this label belongs to
data.labels[].name * string Label name
data.labels[].color * string Label color in hsla code
data.labels[].visible * "public" | "private" Label visibility
data.labels[].createdAt * string Label creation timestamp in ISO format
data.releaseId * string | null ID of the release this task is associated with
data.voteCount * number Number of votes the task has received
data.parentId * string | null ID of the parent task if this is a subtask
data.descriptionHtml * string Task description rendered as HTML
data.descriptionMarkdown * string Task description rendered as Markdown
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/tasks/{task_short_id}
KeyValue
org_slug*
task_short_id*
GET /organization/{org_slug}/tasks/{task_short_id}/comments

List task comments

Retrieve a paginated list of public comments for a task.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
task_short_id integer Yes -

Query Parameters

Name Type Required Description
order "asc" | "desc" No Specifies the sort order by creation date. Use asc for ascending or desc for descending.
limit integer No Number of items per page
page integer No Page number (starting from 1)

Responses

200 Paginated list
Field Type Description
success * true -
data * object[] -
data[].id * string Comment UUID
data[].organizationId * string ID of the organization this comment belongs to
data[].taskId * string ID of the task this comment is associated with
data[].createdAt * string Comment creation timestamp in ISO format
data[].updatedAt * string Comment last update timestamp in ISO format
data[].content * unknown Comment content in BlockNote JSON format
data[].contentHtml * string Comment content rendered as HTML
data[].contentMarkdown * string Comment content rendered as Markdown
data[].createdBy * object | null User who created the comment, or null if user data is not available
data[].visibility * "public" | "internal" Comment visibility level
data[].source * "sayr" | "github" Source of the comment
data[].parentId * string | null ID of the parent comment if this is a reply, null if top-level
data[].reactions object -
data[].reactions.total * number -
data[].reactions.reactions * object -
pagination * object -
pagination.limit * number -
pagination.page * number -
pagination.totalPages * number -
pagination.totalItems * number -
pagination.hasMore * boolean -
400 Invalid pagination parameters
Field Type Description
success * false -
error * string -
message string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
500 Server error
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/tasks/{task_short_id}/comments
KeyValue
org_slug*
task_short_id*
order
limit
page
GET /organization/{org_slug}/releases

Get Organization Releases

Retrieve paginated releases for the specified organization.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -

Query Parameters

Name Type Required Description
limit integer No Number of items per page
page integer No Page number (starting from 1)

Responses

200 Paginated list
Field Type Description
success * true -
data * object[] -
data[].id * string Release UUID
data[].organizationId * string ID of the organization this release belongs to
data[].name * string Release name
data[].slug * string Release slug used in URLs
data[].description * string Release description in blocknote JSON format
data[].descriptionHtml * string Release description rendered as HTML
data[].descriptionMarkdown * string Release description rendered as Markdown
data[].status * "planned" | "in-progress" | "released" | "archived" Release status
data[].targetDate * string Release target date in ISO format
data[].releasedAt * string | null Release date in ISO format, null if not released yet
data[].color * string Release color in hsla code
data[].icon * string | null Release icon URL or identifier
data[].createdBy * object | null User who created the release, or null if user data is not available
data[].createdAt * string Release creation timestamp in ISO format
data[].updatedAt * string Release last update timestamp in ISO format
pagination * object -
pagination.limit * number -
pagination.page * number -
pagination.totalPages * number -
pagination.totalItems * number -
pagination.hasMore * boolean -
400 Invalid pagination parameters
Field Type Description
success * false -
error * string -
message string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
500 Server error
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/releases
KeyValue
limit
page
org_slug*
GET /organization/{org_slug}/releases/{release_slug}

Get Release

Retrieve the specified release for the organization.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
release_slug string Yes -

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string Release UUID
data.organizationId * string ID of the organization this release belongs to
data.name * string Release name
data.slug * string Release slug used in URLs
data.description * string Release description in blocknote JSON format
data.descriptionHtml * string Release description rendered as HTML
data.descriptionMarkdown * string Release description rendered as Markdown
data.status * "planned" | "in-progress" | "released" | "archived" Release status
data.targetDate * string Release target date in ISO format
data.releasedAt * string | null Release date in ISO format, null if not released yet
data.color * string Release color in hsla code
data.icon * string | null Release icon URL or identifier
data.createdBy * object | null User who created the release, or null if user data is not available
data.createdAt * string Release creation timestamp in ISO format
data.updatedAt * string Release last update timestamp in ISO format
data.tasks * object[] -
data.tasks[].id * string Task UUID
data.tasks[].organizationId * string ID of the organization this task belongs to
data.tasks[].shortId * number Short numeric ID unique within the organization
data.tasks[].visible * "public" Task visibility
data.tasks[].createdAt * string Task creation timestamp in ISO format
data.tasks[].updatedAt * string Task last update timestamp in ISO format
data.tasks[].title * string Task title
data.tasks[].description * string Task description in blocknote JSON format
data.tasks[].status * "backlog" | "todo" | "in-progress" | "done" | "cancelled" Task status
data.tasks[].priority * "none" | "low" | "medium" | "high" | "urgent" Task priority
data.tasks[].createdBy * object | null User who created the task
data.tasks[].category * object | null Category associated with the task
data.tasks[].labels * object[] List of labels associated with the task
data.tasks[].labels[].id * string Label UUID
data.tasks[].labels[].organizationId * string ID of the organization this label belongs to
data.tasks[].labels[].name * string Label name
data.tasks[].labels[].color * string Label color in hsla code
data.tasks[].labels[].visible * "public" | "private" Label visibility
data.tasks[].labels[].createdAt * string Label creation timestamp in ISO format
data.tasks[].releaseId * string | null ID of the release this task is associated with
data.tasks[].voteCount * number Number of votes the task has received
data.tasks[].parentId * string | null ID of the parent task if this is a subtask
data.tasks[].descriptionHtml * string Task description rendered as HTML
data.tasks[].descriptionMarkdown * string Task description rendered as Markdown
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/releases/{release_slug}
KeyValue
org_slug*
release_slug*
GET /organization/{org_slug}/releases/{release_slug}/status-updates

Get Release Status Updates

Retrieve public status updates for the specified release.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
release_slug string Yes -

Responses

200 Success
Field Type Description
success * true -
data * object -
data.updates * object[] -
data.updates[].id * string Status update UUID
data.updates[].releaseId * string ID of the release this status update belongs to
data.updates[].organizationId * string ID of the organization this status update belongs to
data.updates[].content * unknown | null Content of the status update in BlockNote JSON format
data.updates[].contentHtml * string | null Content of the status update rendered as HTML
data.updates[].contentMarkdown * string | null Content of the status update rendered as Markdown
data.updates[].health * "on_track" | "at_risk" | "off_track" Health status of the release
data.updates[].visibility * "public" | "internal" Visibility of the status update
data.updates[].createdAt * string Timestamp when the status update was created
data.updates[].updatedAt * string Timestamp when the status update was last updated
data.updates[].author * object | null -
data.updates[].commentCount * number Number of comments on the status update
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/releases/{release_slug}/status-updates
KeyValue
org_slug*
release_slug*
GET /organization/{org_slug}/releases/{release_slug}/comments

Get Release Comments

Retrieve paginated public comments for the specified release.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
release_slug string Yes -

Query Parameters

Name Type Required Description
limit integer No Number of items per page
page integer No Page number (starting from 1)

Responses

200 Paginated list
Field Type Description
success * true -
data * object[] -
data[].comments * object[] -
data[].comments[].id * string Comment UUID
data[].comments[].releaseId * string ID of the release this comment belongs to
data[].comments[].organizationId * string ID of the organization this comment belongs to
data[].comments[].createdBy * object | null -
data[].comments[].content * unknown Content of the comment in BlockNote JSON format
data[].comments[].contentHtml * string Content of the comment rendered as HTML
data[].comments[].contentMarkdown * string Content of the comment rendered as Markdown
data[].comments[].visibility * "public" | "internal" Visibility of the comment
data[].comments[].parentId * string | null ID of the parent comment, if this is a reply
data[].comments[].statusUpdateId * string | null ID of the status update this comment belongs to
data[].comments[].replyCount * number Number of replies to this comment
data[].comments[].reactions * object | null -
data[].comments[].createdAt * string Timestamp when the comment was created
data[].comments[].updatedAt * string Timestamp when the comment was last updated
pagination * object -
pagination.limit * number -
pagination.page * number -
pagination.totalPages * number -
pagination.totalItems * number -
pagination.hasMore * boolean -
400 Invalid pagination parameters
Field Type Description
success * false -
error * string -
message string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
500 Server error
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/releases/{release_slug}/comments
KeyValue
limit
page
org_slug*
release_slug*
GET /organization/{org_slug}/releases/{release_slug}/comments/{commentId}/replies

Get Comment Replies

Retrieve public replies for the specified comment.

Parameters

Path Parameters

Name Type Required Description
org_slug string Yes -
release_slug string Yes -
commentId string Yes -

Responses

200 Success
Field Type Description
success * true -
data * object -
data.replies * object[] -
data.replies[].id * string Reply UUID
data.replies[].releaseId * string ID of the release this reply belongs to
data.replies[].organizationId * string ID of the organization this reply belongs to
data.replies[].createdBy * object | null -
data.replies[].content * unknown Content of the reply in BlockNote JSON format
data.replies[].contentHtml * string Content of the reply rendered as HTML
data.replies[].contentMarkdown * string Content of the reply rendered as Markdown
data.replies[].visibility * "public" | "internal" Visibility of the reply
data.replies[].parentId * string | null ID of the parent comment, if this is a reply
data.replies[].statusUpdateId * string | null ID of the status update this reply belongs to
data.replies[].replyCount * number Number of replies to this comment
data.replies[].reactions * object | null -
data.replies[].createdAt * string Timestamp when the reply was created
data.replies[].updatedAt * string Timestamp when the reply was last updated
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/organization/{org_slug}/releases/{release_slug}/comments/{commentId}/replies
KeyValue
org_slug*
release_slug*
commentId*

User

Section titled "User"
GET /me

Get User Info

Retrieve information about the authenticated user.

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string -
data.name * string -
data.email * string -
data.image * string | null -
data.createdAt * string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/me
GET /me/organizations

Get Users Organizations

Retrieve organizations associated with the authenticated user.

Responses

200 Success
Field Type Description
success * true -
data * object[] -
data[].id * string -
data[].name * string -
data[].slug * string -
data[].logo * string | null -
data[].bannerImg * string | null -
data[].description * string -
data[].settings * string | number | boolean | null | object | unknown[] -
data[].createdAt * string -
data[].updatedAt * string -
data[].plan * string | null -
data[].shortId * string -
data[].eventsUrl * string -
data[].members * object[] -
data[].members[].id * string -
data[].members[].userId * string -
data[].members[].organizationId * string -
data[].members[].createdAt * string -
data[].members[].user * object -
data[].members[].user.id * string -
data[].members[].user.name * string -
data[].members[].user.image * string | null -
data[].members[].user.createdAt * string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
GET/me/organizations

Tasks

Section titled "Tasks"
POST /me/task

Create Task

Create a new task in the organization.

Request Body

Name Type Required
title string Yes
description string No
status "backlog" | "todo" | "in-progress" | "done" | "canceled" No
priority "none" | "low" | "medium" | "high" | "urgent" No
category string No
orgId string Yes
integration object | null No
createdBy object | null No

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string -
data.title * string -
data.shortId * string -
data.orgSlug * string -
data.publicPortalUrl * string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
POST/me/task
POST /me/timeline_event

Create Timeline Event

Create a new timeline event for a task.

Request Body

Name Type Required
taskId string Yes
orgId string Yes
type string Yes
id string Yes
name string Yes
data object No
createdBy object | null No

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
POST/me/timeline_event
POST /me/create_comment

Create Task Comment

Create a new comment on a task.

Request Body

Name Type Required
taskId string Yes
orgId string Yes
content string Yes
visibility "public" | "internal" No
createdBy object | null No

Responses

200 Success
Field Type Description
success * true -
data * object -
data.id * string -
404 Not found
Field Type Description
success * false -
error * string -
message string -
POST/me/create_comment