Cord LogoDocs
Sign inStart now

Threads

Rest API /
Ask the Community

All available operations for listing and editing threads

List all threads #

This endpoint returns information about all threads in a project.

HTTP Request #

HTTP:
GET https://api.cord.com/v1/threads/
cURL:
curl https://api.cord.com/v1/threads/ \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread ls
GET https://api.cord.com/v1/threads/
Copy

Request Body #

This REST endpoint has no request body.

Request Parameters #

The endpoint supports an optional query request parameter. The filter parameter allows you to specify any/all of the multiple optional filters which the threads must match. This is a partial match where as long as the value you filter by is on the thread it will be returned.

filter
optional
ServerListThreadFilter
Threads will be matched against the filters specified. This is a partial match, which means any keys other than the ones you specify are ignored when checking for a match. Please note that because this is a query parameter in a REST API, this JSON object must be URI encoded before being sent.

This is an object with the following fields:

Show property details

limit
optional
number
Number of threads to return. Defaults to 1000.
token
optional
string
Pagination token. This is returned in the pagination object of a previous response.

Response #

The response is a JSON Array with objects with the following fields:

threads
CoreThreadData[]
Page containing threads.

This is an array of objects, each of which has the following fields:

Show property details

pagination
PaginationDetails
Data related to cursor-based pagination.

This is an object with the following fields:

Show property details

Create a thread #

This endpoint is used to create an empty thread. To create a thread with a message, please use our Message API.

HTTP Request #

HTTP:
POST https://api.cord.com/v1/threads
cURL:
curl https://api.cord.com/v1/threads \
              -X POST \
              -H 'Authorization: Bearer <ACCESS_TOKEN>'//
              -H 'Content-Type: application/json'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread create [ID]
POST https://api.cord.com/v1/threads
Copy

Request Body #

name
required
string
The name of the thread. This is shown to users when the thread is referenced, such as in notifications. This should generally be something like the page title.
url
required
string
A URL where the thread can be seen. This determines where a user is sent when they click on a reference to this thread, such as in a notification, or if they click on a reference to a message in the thread and the message doesn't have its own URL.
groupID
required
string
The group ID this thread is in.
location
required
Location
The location of this thread.
id
optional
string
The ID for this thread.
metadata
optional
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
extraClassnames
optional
string | null
An optional space separated list of classnames to add to the thread.
addSubscribers
optional
string[]
A list of subscribers to add to this thread.

Example Request #

cURL:
curl "https://api.cord.com/v1/threads" \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  --json '{
  "id": "abc123",
  "name": "my-awesome-thread",
  "groupID": "group123",
  "location": {"category": "sales"}
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread create abc123 --name=my-awesome-thread --group-id=group123 --location='{"category": "sales"}'
curl "https://api.cord.com/v1/threads" \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  --json '{
  "id": "abc123",
  "name": "my-awesome-thread",
  "groupID": "group123",
  "location": {"category": "sales"}
  }'
Copy

Response #

If successful, the response will be:

JSON:
{
  "success": true,
  "message": "Thread created.",
  "threadID": "abc123"
}
{
  "success": true,
  "message": "Thread created.",
  "threadID": "abc123"
}
Copy

Get a thread #

This endpoint gets information about a specific thread.

HTTP Request #

HTTP:
GET https://api.cord.com/v1/threads/<ID>
cURL:
curl https://api.cord.com/v1/threads/<ID> \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread get <ID>
GET https://api.cord.com/v1/threads/<ID>
Copy

Request Body #

This REST endpoint has no request body.

Response #

The response is a JSON object with the following fields:

id
string
The ID for this thread.
groupID
string
The group ID this thread is in.
total
number
The total number of messages in this thread. Equal to user messages + action messages. Deleted messages are excluded from this count.
userMessages
number
The number of messages in this thread that were sent by users (i.e., not action messages). Deleted messages are excluded from this count.
actionMessages
number
The number of action messages sent in this thread. An example is the message that appears when a thread is resolved. Deleted messages are excluded from this count.
deletedMessages
number
The number of deleted messages in this thread.
resolved
boolean
Whether this thread is resolved. This is equivalent to checking if resolvedTimestamp is null.
resolvedTimestamp
Date | null
The timestamp when this thread was resolved. Set to null if this thread is not resolved.
participants
ThreadParticipant[]
All of the users who are engaging in this thread. This includes both subscribed and unsubscribed users.

This is an array of objects, each of which has the following fields:

Show property details

subscribers
string[]
All of the users who are subscribed to this thread.
repliers
string[]
All of the users who have replied to this thread.
mentioned
string[]
All of the users who were mentioned in a message in this thread.
actionMessageRepliers
string[]
Authors of any message of type action_message in this thread's replies, including automatically generated messages from resolving or unresolving the thread.
typing
string[]
The users that are currently typing in this thread. Typing status is transient in nature, so the value is the set of users typing at a particular instant, but may change rapidly.
name
string
The name of the thread. This is shown to users when the thread is referenced, such as in notifications. This should generally be something like the page title.
url
string
A URL where the thread can be seen. This determines where a user is sent when they click on a reference to this thread, such as in a notification, or if they click on a reference to a message in the thread and the message doesn't have its own URL.
location
Location
The location of this thread.
metadata
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
extraClassnames
string | null
An optional space separated list of classnames to add to the thread.

Update a thread #

This endpoint updates an existing thread.

HTTP Request #

HTTP:
PUT https://api.cord.com/v1/threads/<ID>
cURL:
curl https://api.cord.com/v1/threads/<ID> \
  -X PUT \            
  -H 'Authorization: Bearer <ACCESS_TOKEN>'\
  -H 'Content-Type: application/json
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread update <ID>
PUT https://api.cord.com/v1/threads/<ID>
Copy

Request Body #

Listed below are the fields of the request body to be added as part of the HTTP PUT request.

name
optional
string
The name of the thread. This is shown to users when the thread is referenced, such as in notifications. This should generally be something like the page title.
id
optional
string
The ID for this thread.
metadata
optional
EntityMetadata
Arbitrary key-value pairs that can be used to store additional information.
url
optional
string
A URL where the thread can be seen. This determines where a user is sent when they click on a reference to this thread, such as in a notification, or if they click on a reference to a message in the thread and the message doesn't have its own URL.
groupID
optional
string
The group ID this thread is in.
extraClassnames
optional
string | null
An optional space separated list of classnames to add to the thread.
location
optional
Location
The location of this thread.
resolvedTimestamp
optional
Date | null
The timestamp when this thread was resolved. Set to null if this thread is not resolved.
userID
optional
string
Certain changes to the thread may post a message into the thread -- in particular, resolving or unresolving a thread posts a message into the thread saying "User un/resolved this thread". This parameter is the ID of the User who will be listed as the author of that message. It's optional -- if no user is specified, then those messages won't get posted.
typing
optional
string[]
Marks the specified users as typing in this thread. The typing indicator expires after 3 seconds, so to continually show the indicator it needs to be called on an interval. Pass an empty array to clear all users' typing indicators.
resolved
optional
boolean
Whether the thread is resolved. Setting this to true is equivalent to setting resolvedTimestamp to the current time, and setting this to false is equivalent to setting resolvedTimestamp to null.
seenByUsers
optional
ServerThreadSeenUser[]
Marks the specified users as having seen/not seen this thread. If a user is not included in this list, the seen status will not be changed.

This is an array of objects, each of which has the following fields:

Show property details

addSubscribers
optional
string[]
A list of subscribers to add to this thread.
removeSubscribers
optional
string[]
A list of subscribers to remove from this thread.

Response #

If successful, the response will be:

JSON:
{
  "success": true,
  "message": "✅ You successfully updated thread abc123"
}
{
  "success": true,
  "message": "✅ You successfully updated thread abc123"
}
Copy

Delete a thread #

This endpoint deletes a thread.

HTTP Request #

HTTP:
DELETE https://api.cord.com/v1/threads/<ID>
cURL:
curl https://api.cord.com/v1/threads/<ID> \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord thread delete <ID>
DELETE https://api.cord.com/v1/threads/<ID>
Copy

Request Body #

This REST endpoint has no request body.

Response #

If successful, the response will be:

JSON:
{
  "success": true,
  "message": "💀 You successfully deleted thread abc123"
}
{
  "success": true,
  "message": "💀 You successfully deleted thread abc123"
}
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy