Projects

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: To be able to use this endpoint, you'll have to be on the premium plan and create an 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:


name
optional
string | null
Name to show in both the subject and the body of the email. Defaults to your project's name.

imageURL
optional
string | null
URL for your logo image. The default for this is the Cord logo.

sender
optional
string | null
Email from which notifications for your service will be sent from. This will use the provided name for your project to default to <projectname>-notifications@cord.fyi.

logoConfig
optional
Customization for your logo size. Providing either a height (maximum 120) or width (maximum 240) will result in the image being proportionally resized to fit in a container of that size. The default value is {"width": 140}.

This property can be one of the following:

  • null
  • object

    This is an object with the following fields:


    width
    number
  • object

    This is an object with the following fields:


    height
    number

enableEmailNotifications
optional
boolean
Whether you want your users to receive notification emails. The default value is true.

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:


name
optional
string | null
Name to show in both the subject and the body of the email. Defaults to your project's name.

imageURL
optional
string | null
URL for your logo image. The default for this is the Cord logo.

sender
optional
string | null
Email from which notifications for your service will be sent from. This will use the provided name for your project to default to <projectname>-notifications@cord.fyi.

logoConfig
optional
Customization for your logo size. Providing either a height (maximum 120) or width (maximum 240) will result in the image being proportionally resized to fit in a container of that size. The default value is {"width": 140}.

This property can be one of the following:

  • null
  • object

    This is an object with the following fields:


    width
    number
  • object

    This is an object with the following fields:


    height
    number

enableEmailNotifications
optional
boolean
Whether you want your users to receive notification emails. The default value is true.

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:


name
string | null
Name to show in both the subject and the body of the email. Defaults to your project's name.

imageURL
string | null
URL for your logo image. The default for this is the Cord logo.

sender
string | null
Email from which notifications for your service will be sent from. This will use the provided name for your project to default to <projectname>-notifications@cord.fyi.

logoConfig
Customization for your logo size. Providing either a height (maximum 120) or width (maximum 240) will result in the image being proportionally resized to fit in a container of that size. The default value is {"width": 140}.

This property can be one of the following:

  • null
  • object

    This is an object with the following fields:


    width
    number
  • object

    This is an object with the following fields:


    height
    number

enableEmailNotifications
boolean
Whether you want your users to receive notification emails. The default value is true.

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:


name
string | null
Name to show in both the subject and the body of the email. Defaults to your project's name.

imageURL
string | null
URL for your logo image. The default for this is the Cord logo.

sender
string | null
Email from which notifications for your service will be sent from. This will use the provided name for your project to default to <projectname>-notifications@cord.fyi.

logoConfig
Customization for your logo size. Providing either a height (maximum 120) or width (maximum 240) will result in the image being proportionally resized to fit in a container of that size. The default value is {"width": 140}.

This property can be one of the following:

  • null
  • object

    This is an object with the following fields:


    width
    number
  • object

    This is an object with the following fields:


    height
    number

enableEmailNotifications
boolean
Whether you want your users to receive notification emails. The default value is true.

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

Ask Cordy