Update a comment

PATCH

/v1/comments/{id}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "PATCH");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Idempotency-Key: looker-sync-2027-03-04-0001");
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{ \"body\": \"Can we get the logo into the first two seconds?\" }");

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Patch,
    RequestUri = new Uri("https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5"),
    Headers =
    {
        { "Idempotency-Key", "looker-sync-2027-03-04-0001" },
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"body\": \"Can we get the logo into the first two seconds?\" }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5"

  payload := strings.NewReader("{ \"body\": \"Can we get the logo into the first two seconds?\" }")

  req, _ := http.NewRequest("PATCH", url, payload)

  req.Header.Add("Idempotency-Key", "looker-sync-2027-03-04-0001")
  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(res)
  fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5"))
    .header("Idempotency-Key", "looker-sync-2027-03-04-0001")
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{ \"body\": \"Can we get the logo into the first two seconds?\" }"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"body\": \"Can we get the logo into the first two seconds?\" }");
Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5")
  .patch(body)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'PATCH',
  url: 'https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  data: {body: 'Can we get the logo into the first two seconds?'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5';
const options = {
  method: 'PATCH',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"body":"Can we get the logo into the first two seconds?"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{ \"body\": \"Can we get the logo into the first two seconds?\" }")
val request = Request.Builder()
  .url("https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5")
  .patch(body)
  .addHeader("Idempotency-Key", "looker-sync-2027-03-04-0001")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

use std::str::FromStr;
use serde_json::json;
use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5";

    let payload = json!({"body": "Can we get the logo into the first two seconds?"});

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Idempotency-Key", "looker-sync-2027-03-04-0001".parse().unwrap());
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());
    headers.insert("Content-Type", "application/json".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.request(reqwest::Method::from_str("PATCH").unwrap(), url)
        .headers(headers)
        .json(&payload)
        .send()
        .await;

    let results = response.unwrap()
        .json::<serde_json::Value>()
        .await
        .unwrap();

    dbg!(results);
}

curl --request PATCH \
  --url https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001' \
  --data '{ "body": "Can we get the logo into the first two seconds?" }'

wget --quiet \
  --method PATCH \
  --header 'Idempotency-Key: looker-sync-2027-03-04-0001' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --body-data '{ "body": "Can we get the logo into the first two seconds?" }' \
  --output-document \
  - https://api.focal.inc/v1/comments/f34a811b-a8c1-408a-9faf-1291a8c009a5

Replace a comment’s text. Only the comment’s author can edit it; anyone else gets 404.

Mentions added by an edit are not notified — only a new comment notifies the people it mentions.

Required scope: comments:write. Rate-limit cost: 10. Honors an optional Idempotency-Key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string format: uuid

Example

f34a811b-a8c1-408a-9faf-1291a8c009a5

Header Parameters

Idempotency-Key

string

<= 255 characters

Example

looker-sync-2027-03-04-0001

Client-generated key (≤255 chars) for safe retries. A retry with the same key replays the original response instead of re-applying the write; reusing a key with a different body → 400, an in-flight key → 409. Required on POST; optional on PATCH/DELETE. A UUID v4 is recommended — generate one per logical write and reuse it only for retries of that write.

Request Body^required

application/json

object

body

required

The comment body as Markdown (≤10000 characters). Mentions are written <@user_id> — the user’s id in angle brackets after an @ — and render in the app as that person’s name. Every mentioned user must be a member of the comment’s space, and each one is notified by email and in the app when the comment is created.

string

>= 1 characters <= 10000 characters

Example

Can we get the logo into the first two seconds?

Responses

200

application/json

object

data

required

object

required

string format: uuid

body

required

The comment text as Markdown. Mentions are written <@user_id> — the user’s id in angle brackets after an @ — and render in the app as that person’s name. Formatting the editor offers that Markdown can’t express (underline, colour) is dropped, keeping its text.

string

author_type

required

user for a Focal account; guest for someone commenting through a collection share link, who has no account.

string

Allowed values: user guest

author_id

required

The commenting user; null for a guest.

string format: uuid

nullable

author_name

required

The author’s display name — the user’s name, or the name a guest typed. null when a guest left it blank.

string

nullable

space_id

required

string format: uuid

media_id

required

The media the comment is on, or null for a comment on a board row itself.

string format: uuid

nullable

media_version_id

required

The version of the media the comment was left on. A media keeps its comments across versions, so this can be older than the current one.

string format: uuid

nullable

board_id

required

The board the comment was left on, or null for a comment made in the media library.

string format: uuid

nullable

row_id

required

The board row (task) the comment was left on, or null for a comment made in the media library.

string format: uuid

nullable

reply_to_id

required

The comment this one replies to, or null for a top-level comment. Threads are one level deep: every reply points at the thread’s top-level comment.

string format: uuid

nullable

annotation

required

Where on the media the comment is anchored: a moment (or stretch) of a video, a page, and shapes drawn over the media. null when the comment isn’t anchored to a spot on the media.

object

timestamp

required

Seconds into the video the comment is pinned to. Only videos have one. null when the comment isn’t pinned to a moment.

number

nullable

timestamp_end

required

End, in seconds, of the stretch of video the comment covers. null when the comment marks a single moment.

number

nullable

page

required

The page (counting from 1) of a multi-page media. null otherwise.

integer

nullable >= 1

mockup

required

The ad-mockup preview the drawings were made over (e.g. InstagramFeed). When set, frame and the drawing coordinates are in that mockup’s layout rather than over the media itself. null when drawn on the media itself.

string

nullable

frame

required

The size of the image the drawing coordinates are measured in. Divide a coordinate by it to get a fraction of the frame, or scale it by media.width / frame.width for the media’s pixels. null on comments drawn before this was recorded, when the coordinate space is unknown: the media’s pixels, possibly downscaled to a preview of at most 2560×1600 for images.

object

width

required

Width of the frame in pixels.

number

height

required

Height of the frame in pixels.

number

drawings

required

Shapes drawn over the media. Empty when the comment is only pinned to a moment or a page.

Array

Any of:

A rectangle outline. Coordinates are pixels within the annotation’s frame, measured from its top-left corner. For drawings created through the API, frame is the media’s own width × height.

object

type

required

string

Allowed values: rectangle

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

required

Left edge of the rectangle.

number

required

Top edge of the rectangle.

number

width

required

Width of the rectangle.

number

height

required

Height of the rectangle.

number

A freehand line through points, in order. Coordinates are pixels within the annotation’s frame, measured from its top-left corner. For drawings created through the API, frame is the media’s own width × height.

object

type

required

string

Allowed values: path

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

points

required

The line’s points.

Array<Array<number>>

An arrow pointing from from to to. Coordinates are pixels within the annotation’s frame, measured from its top-left corner. For drawings created through the API, frame is the media’s own width × height.

object

type

required

string

Allowed values: arrow

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

from

required

Where the arrow starts, as [x, y].

Array<number>

required

Where the arrow points, as [x, y].

Array<number>

mentions

required

Everyone mentioned in body, once each.

Array<object>

object

user_id

required

string format: uuid

name

required

The mentioned user’s name as it was when mentioned.

string

reactions

required

Emoji reactions, one entry per emoji anyone used.

Array<object>

object

emoji

required

The reaction, as the app’s icon name.

string

Allowed values: thumbs-up face-grin face-grin-wink face-surprise heart check eye rocket

user_ids

required

Who reacted with this emoji.

Array<string>

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens the comment’s media or board row in the Focal web app, with its comments showing.

string

reply_count

required

How many replies the comment has. Always 0 on a reply.

integer

replies

required

The comment’s replies, oldest first. Always empty on a reply.

Array<object>

object

required

string format: uuid

body

required

string

author_type

required

user for a Focal account; guest for someone commenting through a collection share link, who has no account.

string

Allowed values: user guest

author_id

required

The commenting user; null for a guest.

string format: uuid

nullable

author_name

required

The author’s display name — the user’s name, or the name a guest typed. null when a guest left it blank.

string

nullable

space_id

required

string format: uuid

media_id

required

The media the comment is on, or null for a comment on a board row itself.

string format: uuid

nullable

media_version_id

required

The version of the media the comment was left on. A media keeps its comments across versions, so this can be older than the current one.

string format: uuid

nullable

board_id

required

The board the comment was left on, or null for a comment made in the media library.

string format: uuid

nullable

row_id

required

The board row (task) the comment was left on, or null for a comment made in the media library.

string format: uuid

nullable

reply_to_id

required

The comment this one replies to, or null for a top-level comment. Threads are one level deep: every reply points at the thread’s top-level comment.

string format: uuid

nullable

annotation

required

Where on the media the comment is anchored: a moment (or stretch) of a video, a page, and shapes drawn over the media. null when the comment isn’t anchored to a spot on the media.

object

timestamp

required

Seconds into the video the comment is pinned to. Only videos have one. null when the comment isn’t pinned to a moment.

number

nullable

timestamp_end

required

End, in seconds, of the stretch of video the comment covers. null when the comment marks a single moment.

number

nullable

page

required

The page (counting from 1) of a multi-page media. null otherwise.

integer

nullable >= 1

mockup

required

string

nullable

frame

required

object

width

required

Width of the frame in pixels.

number

height

required

Height of the frame in pixels.

number

drawings

required

Shapes drawn over the media. Empty when the comment is only pinned to a moment or a page.

Array

Any of:

object

type

required

string

Allowed values: rectangle

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

required

Left edge of the rectangle.

number

required

Top edge of the rectangle.

number

width

required

Width of the rectangle.

number

height

required

Height of the rectangle.

number

object

type

required

string

Allowed values: path

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

points

required

The line’s points.

Array<Array<number>>

object

type

required

string

Allowed values: arrow

color

required

The stroke colour as a CSS hex code, e.g. #9d2dff.

string

from

required

Where the arrow starts, as [x, y].

Array<number>

required

Where the arrow points, as [x, y].

Array<number>

mentions

required

Everyone mentioned in body, once each.

Array<object>

object

user_id

required

string format: uuid

name

required

The mentioned user’s name as it was when mentioned.

string

reactions

required

Emoji reactions, one entry per emoji anyone used.

Array<object>

object

emoji

required

The reaction, as the app’s icon name.

string

Allowed values: thumbs-up face-grin face-grin-wink face-surprise heart check eye rocket

user_ids

required

Who reacted with this emoji.

Array<string>

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

Browser URL that opens the comment’s media or board row in the Focal web app, with its comments showing.

string

Example

{
  "data": {
    "id": "f34a811b-a8c1-408a-9faf-1291a8c009a5",
    "body": "Can we get the logo into the first two seconds?",
    "author_type": "user",
    "author_id": "cfebb6ef-f092-4591-a6e3-e6667ab5a252",
    "author_name": "Maya Chen",
    "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
    "media_id": "786beeda-55ac-4025-bf6e-43b2918e84a9",
    "media_version_id": "f0a180e0-f387-47fa-9c26-11e144d1f0f6",
    "board_id": null,
    "row_id": null,
    "reply_to_id": null,
    "annotation": {
      "timestamp": 0.5,
      "timestamp_end": 2,
      "page": null,
      "mockup": null,
      "frame": {
        "width": 1080,
        "height": 1350
      },
      "drawings": [
        {
          "type": "rectangle",
          "color": "#9d2dff",
          "x": 64,
          "y": 80,
          "width": 320,
          "height": 180
        }
      ]
    },
    "mentions": [
      {
        "user_id": "5bc4dea2-9cc6-4e2a-a6ee-9156752c9646",
        "name": "Jonas Berg"
      }
    ],
    "reactions": [
      {
        "emoji": "thumbs-up",
        "user_ids": [
          "5bc4dea2-9cc6-4e2a-a6ee-9156752c9646"
        ]
      }
    ],
    "created_at": "2027-03-04T10:15:00Z",
    "updated_at": "2027-03-06T14:42:00Z",
    "html_url": "https://app.focal.inc/spaces/6916bc3d-e1ab-425b-ac25-eefada01a9a2/library?file=786beeda-55ac-4025-bf6e-43b2918e84a9&folder=80539d38-3a8e-48f8-929b-8c0e9a22ab43",
    "reply_count": 1,
    "replies": [
      {
        "id": "fe202603-d056-49f6-9c4a-3bca6d05819e",
        "body": "Done – new cut is uploaded as v2.",
        "author_type": "user",
        "author_id": "5bc4dea2-9cc6-4e2a-a6ee-9156752c9646",
        "author_name": "Jonas Berg",
        "space_id": "6916bc3d-e1ab-425b-ac25-eefada01a9a2",
        "media_id": "786beeda-55ac-4025-bf6e-43b2918e84a9",
        "media_version_id": "f0a180e0-f387-47fa-9c26-11e144d1f0f6",
        "board_id": null,
        "row_id": null,
        "reply_to_id": "f34a811b-a8c1-408a-9faf-1291a8c009a5",
        "annotation": null,
        "mentions": [
          {
            "user_id": "5bc4dea2-9cc6-4e2a-a6ee-9156752c9646",
            "name": "Jonas Berg"
          }
        ],
        "reactions": [
          {
            "emoji": "thumbs-up",
            "user_ids": [
              "5bc4dea2-9cc6-4e2a-a6ee-9156752c9646"
            ]
          }
        ],
        "created_at": "2027-03-06T14:42:00Z",
        "updated_at": "2027-03-06T14:42:00Z",
        "html_url": "https://app.focal.inc/spaces/6916bc3d-e1ab-425b-ac25-eefada01a9a2/library?file=786beeda-55ac-4025-bf6e-43b2918e84a9&folder=80539d38-3a8e-48f8-929b-8c0e9a22ab43"
      }
    ]
  }
}

400

The request was malformed (invalid cursor, unknown type, validation failure, etc.). error.code is bad_request.

application/json

Canonical error envelope. code is stable across releases and intended for programmatic handling; message is human-readable. details only appears for validation failures and lists the offending fields.

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "details": [
      {
        "field": "space_id",
        "issue": "Invalid UUID"
      }
    ]
  }
}

401

Missing, invalid, or disabled token. error.code is unauthenticated.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

The token doesn’t have the scope this endpoint requires. error.code is forbidden.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Token doesn't have the required scope"
  }
}

404

Resource doesn’t exist or is outside the token’s space allow-list. The two cases share a response shape so a restricted token can’t probe for the existence of out-of-scope spaces. error.code is not_found.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Not found"
  }
}

409

The request conflicts with the current state. Most commonly a concurrent request carrying the same Idempotency-Key is still in flight. error.code is conflict.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "conflict",
    "message": "A request with this Idempotency-Key is already being processed"
  }
}

429

Rate limit exceeded. error.code is rate_limited. Wait the number of seconds in the Retry-After header before retrying. Quotas are per-token; see the “Rate limiting” section at the top of this document.

application/json

object

error

required

object

code

required

string

Allowed values: unauthenticated forbidden not_found bad_request conflict rate_limited internal_error

message

required

string

details

Array<object>

object

field

string

issue

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

Seconds to wait before retrying.

Update a comment

Authorizations

Parameters

Path Parameters

Example

Header Parameters

Example

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

403

Example

404

Example

409

Example

429

Example

Headers

Example

Request Body^required