Public API (beta)


The Rock public API is accessible via https://api.rock.so/webhook/bot with the authentication token passed in via an auth query parameter or via an Authorization: Bearer <token> header. The public API provides several methods, denoted by Method constants. The method has to be passed as a method query parameter to the request.


The Create and Send methods require HTTP POST, while the Get and List methods require GET. The Create and Send methods require and input denoted by a structure called after a method name + Request suffix. This structure has to be serialized to JSON and sent in the POST body. The successful invocation of a method returns either 200 or 204 status code, and the output in the latter case is returned in JSON format as defined by the structure called after the method name + Response suffix. In case of a 400 HTTP response the response body, if not empty, would contain a structure called after the method name + ErrorResponse suffix, providing the error details. Other HTTP status codes are to be interpreted according to their standard protocol meaning.


The List methods provide an unified way of pagination by accepting cursor and limit query parameters. The limit is the page size that should not exceed the corresponding Max* constant. The cursor is a pagination cursor: it has to be passed empty on the first invocation, then if the response hasMore property is true, the nextCursor from the response has to be passed as cursor to the next call. If hasMore is false / missing, the iteration is completed.



Examples:

Task creation using createTask:

URL:

https://api.rock.so/webhook/bot?method=createTask&auth=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Input:

{ "title": "Hello world", "body": [{"text":"Hi I am Jimmy", "attr":"bold"},{"text":"nice to meet you"}], "due":1628154301, "owners":["aaaabbbb"], "labels":["hello"], "listId":1, "priority":2 }

Output:

{"id": 3}



Methods

Name: 'sendMessage'
Type: 'POST'
Input: SendMessageRequest
Output: SendMessageResponse|SendMessageErrorResponse

Name: 'createNote'
Type: 'POST'
Input: CreateNoteRequest
Output: CreateNoteResponse|CreateNoteErrorResponse

Name: 'createTask'
Type: 'POST'
Input: CreateTaskRequest
Output: CreateTaskResponse|CreateTaskErrorResponse

Name: 'listSpaceMembers'
Type: 'GET'
Output: ListSpaceMembersResponse

Name: 'listSprints'
Type: 'GET'
Output: ListSprintsResponse

Name: 'listLabels'
Type: 'GET'
Output: ListLabelsResponse

Name: 'getTaskLists'
Type: 'GET'
Output: GetTaskListsResponse

Name: 'getCustomFields'
Type: 'GET'
Output: GetCustomFieldsResponse



Schema

SendMessageRequest {
text string
parentMsgId uint32
}

SendMessageResponse {
id uint32
}

SendMessageErrorResponse {
error string
}

SpaceMember {
userId string
id uint32
role string
state string
invitedAt uint32
joinedAt uint32
removedAt uint32
suspendedAt uint32
invitedBy string
name string
avatarBig string
avatarSmall string
tzOffset string
orgId string
email string
emailAliases []string
phone string
}

ListSpaceMembersResponse {
members []SpaceMember
hasMore bool
nextCursor string
}

Sprint {
id uint32
name string
start uint32
end uint32
}

ListSprintsResponse {
sprints []Sprint
hasMore bool
nextCursor string
}

ListLabelsResponse {
labels []string
hasMore bool
nextCursor string
}

TaskList {
id uint32
name string
color string
completed bool
}

GetTaskListsResponse []TaskList

CustomFieldOption {
option string
title string
}

CustomFieldType string

enum CustomFieldType [
'TEXT'
'NUMBER'
'SELECT'
]

CustomField {
id uint32
title string
required bool
type CustomFieldType
options []CustomFieldOption
}

GetCustomFieldsResponse []CustomField

TextFragmentAttributes {
bold bool
italic bool
strike bool
underlined bool
link string
heading uint32
block string
}

TextFragment {
text string
attr TextFragmentAttributes
}

CreateNoteRequest {
body []TextFragment
labels []string
watchers []string
}

CreateNoteResponse {
id uint32
}

CreateNoteErrorResponse {
error string
}

RecurringScheduleType string

enum RecurringScheduleType [
'DAILY'
'DAYS_OF_WEEK'
'DAY_OF_MONTH'
'LAST_DAY_OF_MONTH'
]

RecurringScheduleDaysOfWeek {
monday bool
tuesday bool
wednesday bool
thursday bool
friday bool
saturday bool
sunday bool
}

RecurringSchedule {
targetListId uint32
type RecurringScheduleType
workdaysOnly bool
dayOfMonth uint8
daysOfWeek RecurringScheduleDaysOfWeek
}

CreateTaskRequest {
title string
body []TextFragment
listId uint32
start uint32
due uint32
owners []string
priority int32
severity int32
sprint uint32
checkList []string
recurringSchedule RecurringSchedule
customFields map[string]string
labels []string
watchers []string
}

CreateTaskResponse {
id uint32
}

CreateTaskErrorResponse {
error string
}


If you have any questions, ping us in the Rock Team space on Rock, or send us an email at developer@rock.so.