Cord LogoDocs
Sign inStart now

Projects

REST API /
Ask the Community

All available operations for manipulating projects and their information

Create a project #

This endpoint creates a project that can then be viewed and managed within the Cord Console.

Note: This feature is only available on paid plans. To use this endpoint, create a project management authentication token using your customer ID and secret. This token is a customer-level server auth token used only for the projects REST API.

HTTP Request #

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

Request Body #

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

name
required
string
Name of the project
iconURL
optional
string | null
URL for the project icon. It should be a square image of 256x256. This will be used as the avatar for messages and emails coming from your project. If not specified, the Cord logo will be used.
eventWebhookURL
optional
string | null
The URL that the events webhook is sent to
redirectURI
optional
string | null
Custom url link contained in email and slack notifications. These notifications are sent when a user is mentioned or thread is shared and by default, the link points to the page where the conversation happened. For more information, please refer to the API docs
emailSettings
optional
Partial<EmailSettings>

This is an object with the following fields:

Show property details

Example Request #

cURL:
curl "https://api.cord.com/v1/projects" \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Planet Express"
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord project create --name="Planet Express"
curl "https://api.cord.com/v1/projects" \
  -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Planet Express"
  }'
Copy

If the request succeeds, the response will be:

JSON:
{
    "success": true,
    "message": "Project created",
    "projectID": "<PROJECT_ID>",
    "secret": "<SECRET_KEY>"
}
{
    "success": true,
    "message": "Project created",
    "projectID": "<PROJECT_ID>",
    "secret": "<SECRET_KEY>"
}
Copy

The project secret that you created above is extremely sensitive. You should protect it just like you would a password or other sensitive credential. This token is used for server-to-server communication and should never be used in the browser. For more information, check out our Authentication reference guide

If the request does not succeed, the response will instead contain an error and message explaining what went wrong:

JSON:
{
  "error": "<ERROR_CODE>",
  "message": "An explanation of the error code."
}
{
  "error": "<ERROR_CODE>",
  "message": "An explanation of the error code."
}
Copy

Update a project #

This endpoint lets you update various properties of your project.

HTTP Request #

HTTP:
PUT https://api.cord.com/v1/projects/<ID>
cURL:
curl "https://api.cord.com/v1/projects/<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 project update <ID>
PUT https://api.cord.com/v1/projects/<ID>
Copy

Request Body #

The request body will be a JSON object with two optional fields.

name
optional
string
Name of the project
iconURL
optional
string | null
URL for the project icon. It should be a square image of 256x256. This will be used as the avatar for messages and emails coming from your project. If not specified, the Cord logo will be used.
eventWebhookURL
optional
string | null
The URL that the events webhook is sent to
redirectURI
optional
string | null
Custom url link contained in email and slack notifications. These notifications are sent when a user is mentioned or thread is shared and by default, the link points to the page where the conversation happened. For more information, please refer to the API docs
emailSettings
optional
Partial<EmailSettings>

This is an object with the following fields:

Show property details

Example Request #

cURL:
curl "https://api.cord.com/v1/projects/<ID>" \
  -X PUT \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Planet Express, Inc"
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord project update <ID> --name="Planet Express, Inc"
curl "https://api.cord.com/v1/projects/<ID>" \
  -X PUT \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Planet Express, Inc"
  }'
Copy

If the request succeeds, the response will be:

JSON:
{
    "success": true,
    "message": "✅ You successfully updated project <ID>",
}
{
    "success": true,
    "message": "✅ You successfully updated project <ID>",
}
Copy

List projects #

This endpoint lists all your projects.

HTTP Request #

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

Request Body #

This REST endpoint has no request body.

Response #

The response is a list of objects with the following fields:

id
string
The ID for the project.
secret
string
The secret key for the project. Please treat securely as access to this will allow someone to take actions as if they are the project.
name
string
Name of the project
iconURL
string | null
URL for the project icon. It should be a square image of 256x256. This will be used as the avatar for messages and emails coming from your project. If not specified, the Cord logo will be used.
eventWebhookURL
string | null
The URL that the events webhook is sent to
redirectURI
string | null
Custom url link contained in email and slack notifications. These notifications are sent when a user is mentioned or thread is shared and by default, the link points to the page where the conversation happened. For more information, please refer to the API docs
emailSettings
EmailSettings
Email settings for notifications.

This is an object with the following fields:

Show property details

createdTimestamp
Date
The time at which the project was created

Example Request #

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

If successful, the response will be similar to:

JSON:
[
  {
    "id": "124",
    "name": "Planet Express",
    "iconURL": null,
  },
  {
    "id": "123",
    "name": "Awesome Express",
    "iconURL": null,
  }
]
[
  {
    "id": "124",
    "name": "Planet Express",
    "iconURL": null,
  },
  {
    "id": "123",
    "name": "Awesome Express",
    "iconURL": null,
  }
]
Copy

Get a Project #

This endpoint returns data about a single project.

HTTP Request #

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

Request Body #

This REST endpoint has no request body.

Response #

The response is an object with the following fields:

id
string
The ID for the project.
secret
string
The secret key for the project. Please treat securely as access to this will allow someone to take actions as if they are the project.
name
string
Name of the project
iconURL
string | null
URL for the project icon. It should be a square image of 256x256. This will be used as the avatar for messages and emails coming from your project. If not specified, the Cord logo will be used.
eventWebhookURL
string | null
The URL that the events webhook is sent to
redirectURI
string | null
Custom url link contained in email and slack notifications. These notifications are sent when a user is mentioned or thread is shared and by default, the link points to the page where the conversation happened. For more information, please refer to the API docs
emailSettings
EmailSettings
Email settings for notifications.

This is an object with the following fields:

Show property details

createdTimestamp
Date
The time at which the project was created

Example Request #

cURL:
curl "https://api.cord.com/v1/projects/124" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord project get 124
curl "https://api.cord.com/v1/projects/124" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
Copy

If successful, the response will be similar to:

JSON:
{
  "id": "124",
  "name": "Planet Express",
  "iconURL": null,
}
{
  "id": "124",
  "name": "Planet Express",
  "iconURL": null,
}
Copy

Delete a Project #

This endpoint lets you delete your project and any associated data.This operation will permanently delete the project along with any groups, users, threads and messages associated with that project. Please only use if you are okay with that.

HTTP Request #

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

Request Body #

The request body contains only one field:

secret
required
string
Secret key of the project that you want to delete. This can be found within the Cord Console.

Example Request #

cURL:
curl "https://api.cord.com/v1/projects/<ID>" \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "secret": <SECRET_KEY>
  }'
CLI:
# you can install @cord-sdk/cli for a simpler experience
cord project delete <ID>

# you will be prompted to input the project secret to confirm deletion              
              
curl "https://api.cord.com/v1/projects/<ID>" \
  -X DELETE \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "secret": <SECRET_KEY>
  }'
Copy

If the request succeeds, the response will be:

JSON:
{
    "success": true,
    "message": "💀 You successfully deleted project <ID>",
}
{
    "success": true,
    "message": "💀 You successfully deleted project <ID>",
}
Copy

Not finding the answer you need? Ask our Developer Community

Ask Cordy