> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# Create comment

Create a new comment on a design.

<Warning>
  This preview API is deprecated. You should use the [Create thread](https://www.canva.dev/docs/apps/rest-apis/reference/comments/create-thread/) API instead.
</Warning>

Create a new top-level comment on a design.
For information on comments and how they're used in the Canva UI, see the
[Canva Help Center](https://www.canva.com/help/comments/). A design can have a maximum
of 1000 comments.

## HTTP method and URL path

POST https\://api.canva.com/rest/v1/comments

This operation is rate limited to 20 requests per minute for each user of your app.

## Authentication and authorization

This endpoint requires a valid access token that acts on behalf of a user. For more information, see [Generate an access token](/docs/apps/rest-apis/reference/authentication/generate-access-token).

### Scopes

The access token must have all the following [scopes](/docs/apps/rest-apis/scopes) (permissions):

* `comment:write`

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string" required>
    Provides credentials to authenticate the request, in the form of a `Bearer` token.

    For example: `Authorization: Bearer {token}`
  </Prop>

  <Prop name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/json`.

    For example: `Content-Type: application/json`
  </Prop>
</Prop.List>

## Body parameters

<Prop.List>
  <Prop name="attached_to" type="CommentObjectInput" required>
    An object containing identifying information for the design or other object you want to
    attach the comment to.

    <Tabs>
      <Tab name="design">
        If the comment is attached to a Canva Design.

        <Prop.List>
          <Prop name="type" type="string" required>
            <Prop.Extras>
              **Available values:** The only valid value is `design`.
            </Prop.Extras>
          </Prop>

          <Prop name="design_id" type="string" required>
            The ID of the design you want to attach this comment to.
          </Prop>
        </Prop.List>
      </Tab>
    </Tabs>
  </Prop>

  <Prop name="message" type="string" required>
    The comment message. This is the comment body shown in the Canva UI.

    You can also mention users in your message by specifying their User ID and Team ID
    using the format `[user_id:team_id]`. If the `assignee_id` parameter is specified, you
    must mention the assignee in the message.

    <Prop.Extras>
      **Minimum length:** `1`

      **Maximum length:** `2048`
    </Prop.Extras>
  </Prop>

  <Prop name="assignee_id" type="string">
    Lets you assign the comment to a Canva user using their User ID. You *must* mention the
    assigned user in the `message`.
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/comments` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request POST 'https://api.canva.com/rest/v1/comments' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "attached_to": {
        "design_id": "DAFVztcvd9z",
        "type": "design"
      },
      "message": "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
      "assignee_id": "oUnPjZ2k2yuhftbWF7873o"
    }'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");

    fetch("https://api.canva.com/rest/v1/comments", {
      method: "POST",
      headers: {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        "attached_to": {
          "design_id": "DAFVztcvd9z",
          "type": "design"
        },
        "message": "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
        "assignee_id": "oUnPjZ2k2yuhftbWF7873o"
      }),
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/rest/v1/comments"))
                .header("Authorization", "Bearer {token}")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"attached_to\": {\"design_id\": \"DAFVztcvd9z\", \"type\": \"design\"}, \"message\": \"Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!\", \"assignee_id\": \"oUnPjZ2k2yuhftbWF7873o\"}"))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests

    headers = {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json"
    }

    data = {
        "attached_to": {
            "design_id": "DAFVztcvd9z",
            "type": "design"
        },
        "message": "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
        "assignee_id": "oUnPjZ2k2yuhftbWF7873o"
    }

    response = requests.post("https://api.canva.com/rest/v1/comments",
        headers=headers,
        json=data
    )
    print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Post,
      RequestUri = new Uri("https://api.canva.com/rest/v1/comments"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
      },
      Content = new StringContent(
        "{\"attached_to\": {\"design_id\": \"DAFVztcvd9z\", \"type\": \"design\"}, \"message\": \"Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!\", \"assignee_id\": \"oUnPjZ2k2yuhftbWF7873o\"}",
        Encoding.UTF8,
        "application/json"
      ),
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    	"strings"
    )

    func main() {
    	payload := strings.NewReader(`{
    	  "attached_to": {
    	    "design_id": "DAFVztcvd9z",
    	    "type": "design"
    	  },
    	  "message": "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
    	  "assignee_id": "oUnPjZ2k2yuhftbWF7873o"
    	}`)

    	url := "https://api.canva.com/rest/v1/comments"
    	req, _ := http.NewRequest("POST", url, payload)
    	req.Header.Add("Authorization", "Bearer {token}")
    	req.Header.Add("Content-Type", "application/json")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/rest/v1/comments",
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
        'Content-Type: application/json',
      ),
      CURLOPT_POSTFIELDS => json_encode([
        "attached_to" => [
          "design_id" => "DAFVztcvd9z",
          "type" => "design"
        ],
        "message" => "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
        "assignee_id" => "oUnPjZ2k2yuhftbWF7873o"
      ])
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/rest/v1/comments')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request['Authorization'] = 'Bearer {token}'
    request['Content-Type'] = 'application/json'
    request.body = <<REQUEST_BODY
    {
      "attached_to": {
        "design_id": "DAFVztcvd9z",
        "type": "design"
      },
      "message": "Great work [oUnPjZ2k2yuhftbWF7873o:oBpVhLW22VrqtwKgaayRbP]!",
      "assignee_id": "oUnPjZ2k2yuhftbWF7873o"
    }
    REQUEST_BODY

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

If successful, the endpoint returns a `200` response with a JSON body with the following parameters:

<Prop.List>
  <Prop name="comment" type="ParentComment" required deprecated mode="output">
    Data about the comment, including the message, author, and
    the object (such as a design) the comment is attached to.

    <PillAccordion title={<>Properties of <strong>comment</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="type" type="string" required deprecated mode="output">
          The type of comment. When creating a new parent (top-level)
          comment, the `type` is `parent`.

          <Prop.Extras>
            **Available values:** The only valid value is `parent`.
          </Prop.Extras>
        </Prop>

        <Prop name="id" type="string" required deprecated mode="output">
          The ID of the comment.

          You can use this ID to create replies to the comment using the [Create reply API](https://www.canva.dev/docs/apps/rest-apis/reference/comments/create-reply/).
        </Prop>

        <Prop name="message" type="string" required deprecated mode="output">
          The comment message. This is the comment body shown in the Canva UI.
          User mentions are shown here in the format `[user_id:team_id]`.
        </Prop>

        <Prop name="author" type="User" required deprecated mode="output">
          Metadata for the user, consisting of the User ID and display name.

          <PillAccordion title={<>Properties of <strong>author</strong></>}>
            <Prop.List>
              <Prop name="id" type="string" required deprecated mode="output">
                The ID of the user.
              </Prop>

              <Prop name="display_name" type="string" deprecated mode="output">
                The name of the user as shown in the Canva UI.
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="created_at" type="integer" deprecated mode="output">
          When the comment or reply was created, as a Unix timestamp
          (in seconds since the Unix Epoch).
        </Prop>

        <Prop name="updated_at" type="integer" deprecated mode="output">
          When the comment or reply was last updated, as a Unix timestamp
          (in seconds since the Unix Epoch).
        </Prop>

        <Prop name="assignee" type="User" deprecated mode="output">
          Metadata for the user, consisting of the User ID and display name.

          <PillAccordion title={<>Properties of <strong>assignee</strong></>}>
            <Prop.List>
              <Prop name="id" type="string" required deprecated mode="output">
                The ID of the user.
              </Prop>

              <Prop name="display_name" type="string" deprecated mode="output">
                The name of the user as shown in the Canva UI.
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="resolver" type="User" deprecated mode="output">
          Metadata for the user, consisting of the User ID and display name.

          <PillAccordion title={<>Properties of <strong>resolver</strong></>}>
            <Prop.List>
              <Prop name="id" type="string" required deprecated mode="output">
                The ID of the user.
              </Prop>

              <Prop name="display_name" type="string" deprecated mode="output">
                The name of the user as shown in the Canva UI.
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="mentions" type="object" required deprecated mode="output">
          The Canva users mentioned in the comment.

          <PillAccordion title={<>Properties of <strong>mentions</strong></>}>
            <Prop.List>
              <Prop name="<KEY>" type="object of TeamUsers" mode="output" required>
                Metadata for the user, consisting of the User ID, Team ID, and display name.

                <Prop.List>
                  <Prop name="user_id" type="string" deprecated mode="output">
                    The ID of the user.
                  </Prop>

                  <Prop name="team_id" type="string" deprecated mode="output">
                    The ID of the user's Canva Team.
                  </Prop>

                  <Prop name="display_name" type="string" deprecated mode="output">
                    The name of the user as shown in the Canva UI.
                  </Prop>
                </Prop.List>
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>

        <Prop name="attached_to" type="CommentObject" deprecated mode="output">
          Identifying information about the object (such as a design) that the comment is attached to.

          <Tabs>
            <Tab name="design">
              If the comment is attached to a Canva Design.

              <Prop.List>
                <Prop name="type" type="string" required deprecated mode="output">
                  <Prop.Extras>
                    **Available values:** The only valid value is `design`.
                  </Prop.Extras>
                </Prop>

                <Prop name="design_id" type="string" required deprecated mode="output">
                  The ID of the design this comment is attached to.
                </Prop>
              </Prop.List>
            </Tab>
          </Tabs>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example response

```json
{}
```

## Error responses

### 400 Bad Request

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### Assignee must be mentioned in comment content

```json
{
  "code": "bad_request_body",
  "message": "Assignee must be mentioned in comment content"
}
```

##### Message is too long

```json
{
  "code": "message_too_long",
  "message": "Message is too long"
}
```

##### Mentions with non-obfuscated IDs are not allowed for this client

```json
{
  "code": "invalid_field",
  "message": "Invalid IDs"
}
```

### 403 Forbidden

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### Design already has the maximum number of allowed comments

```json
{
  "code": "too_many_comments",
  "message": "Design already has the maximum number of allowed comments"
}
```

##### Not allowed to comment on this design

```json
{
  "code": "permission_denied",
  "message": "Not allowed to comment on this design"
}
```

### 404 Not Found

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### Design not found

```json
{
  "code": "design_not_found",
  "message": "Design not found"
}
```

##### A mentioned user could not be found

```json
{
  "code": "user_not_found",
  "message": "Invalid user ID"
}
```

##### A mentioned user's team could not be found

```json
{
  "code": "team_not_found",
  "message": "Invalid brand ID"
}
```