Cord LogoDocs
Sign inStart now

Threads

Rest API /

All available operations for listing and editing threads

List all threads #

This endpoint returns information about all threads in an application.

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
Omit<FilterParameters, "organizationID">
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:

metadata
optional
EntityMetadata
Arbitrary key-value pairs of data associated with the object.
location
optional
Location
The location for the thread.
firstMessageTimestamp
optional
TimestampRange
Timestamp when the first message in a thread was created.

This is an object with the following fields:

from
optional
Date
Timestamp from where to start the interval. If not present, the interval will have no start date and any data will include everything up to the provided to timestamp.
to
optional
Date
Timestamp where to end the interval. If not present, the interval will have no end date and any data will include everything from the provided from timestamp.
mostRecentMessageTimestamp
optional
TimestampRange
Timestamp when a message in a thread was last created or updated.

This is an object with the following fields:

from
optional
Date
Timestamp from where to start the interval. If not present, the interval will have no start date and any data will include everything up to the provided to timestamp.
to
optional
Date
Timestamp where to end the interval. If not present, the interval will have no end date and any data will include everything from the provided from timestamp.
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:

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).
actionMessages
number
The number of action messages sent in this thread. An example is the message that appears when a thread is resolved.
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:

lastSeenTimestamp
Date | null
The timestamp of the most recent message or reaction that this user has seen in this thread. Is null if this participant has never viewed this thread.
userID
string | null
The user ID of the participant. Can be null if the current viewer no longer shares a group with this participant (and therefore can no longer access that participant's information).
subscribers
string[]
All of the users who are subscribed to this thread.
repliers
string[]
All of the users who have replied to this 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.
pagination
PaginationDetails
Data related to cursor-based pagination.

This is an object with the following fields:

token
string | null
The token to use to get the next page of results. If empty, there are no more results.
total
number
Total number of results. Might be bigger than the number of results returned on the query. Useful to display a "total" counter.

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).
actionMessages
number
The number of action messages sent in this thread. An example is the message that appears when a thread is resolved.
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:

lastSeenTimestamp
Date | null
The timestamp of the most recent message or reaction that this user has seen in this thread. Is null if this participant has never viewed this thread.
userID
string | null
The user ID of the participant. Can be null if the current viewer no longer shares a group with this participant (and therefore can no longer access that participant's information).
subscribers
string[]
All of the users who are subscribed to this thread.
repliers
string[]
All of the users who have replied to this 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 seet/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:

userID
required
string
ID of the user that has seen/not seen the thread.
seen
required
boolean
Whether the user has seen the thread or not.

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

Ask Cordy