Create a comment

POST

/v1/comments

const url = 'https://api.focal.inc/v1/comments';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'looker-sync-2027-03-04-0001',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"media_id":"786beeda-55ac-4025-bf6e-43b2918e84a9","row_id":"6eee0a1d-ef35-45ee-b1c9-b95f1f54d652","reply_to_id":"f34a811b-a8c1-408a-9faf-1291a8c009a5","body":"Can we get the logo into the first two seconds?","annotation":{"timestamp":0.5,"timestamp_end":2,"page":1,"drawings":[{"type":"rectangle","color":"#9d2dff","x":64,"y":80,"width":320,"height":180}]}}'
};

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

• Production

Comment on a media or a board row (task), or reply to an existing comment. Pass exactly one of media_id, row_id or reply_to_id.

A top-level media comment can carry an annotation: pin it to a moment of a video with timestamp (seconds), to a page of a multi-page media with page, and draw over an image or video with drawings in the media’s pixel coordinates — read width, height, duration and page_count from the media first.

Mentions are written <@user_id> — the user’s id in angle brackets after an @ — and render in the app as that person’s name. Mentioned users and, for a reply, the thread’s author are notified, and the comment is posted to any Slack channel subscribed to where it was left — exactly as a comment typed in the app.

A comment is posted as the person behind the credentials — the user who authorized the connection, or the API token’s creator — and only its author can edit or archive it.

Required scope: comments:write. Rate-limit cost: 10. An Idempotency-Key header is required.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

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

Media typeapplication/json

object

media_id

The media whose comments to read or write. Covers comments made on it anywhere — in the library and in the board media player.

string format: uuid

Example

786beeda-55ac-4025-bf6e-43b2918e84a9

row_id

The board row (task) whose comments to read or write.

string format: uuid

Example

6eee0a1d-ef35-45ee-b1c9-b95f1f54d652

reply_to_id

Reply to this comment instead of starting a new thread. The reply joins the thread’s media or row, so send it without media_id or row_id. Replying to a reply adds to the same thread.

string format: uuid

Example

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

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?

annotation

Anchor a top-level media comment to a spot on the media, as the app’s media player does: pin it to a moment of a video, to a page, and/or draw over it. Set at least one of timestamp, page or a non-empty drawings. Only with media_id. The anchor is fixed once the comment is created.

object

timestamp

Seconds into the video the comment is pinned to. Only videos have one.

number

Example

0.5

timestamp_end

End, in seconds, of the stretch of video the comment covers. Leave it out to mark a single moment; when set it must be at least timestamp.

number

Example

2

page

The page (counting from 1) of a multi-page media. Only for media with more than one page.

integer

>= 1

Example

1

drawings

Shapes to draw over the media (≤50), for images and videos. Every coordinate must lie within the media’s width × height.

Array

Any of:

object

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 (#rrggbb or #rgb).

string

/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/

Example

#9d2dff

x

required

Left edge of the rectangle.

number

Example

64

y

required

Top edge of the rectangle.

number

Example

80

width

required

Width of the rectangle.

number

Example

320

height

required

Height of the rectangle.

number

Example

180

object

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 (#rrggbb or #rgb).

string

/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/

Example

#9d2dff

points

required

The line’s points (2–1000).

Array<Array<number>>

Example

[
  [
    64,
    80
  ],
  [
    210,
    142
  ],
  [
    388,
    260
  ]
]

object

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 (#rrggbb or #rgb).

string

/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/

Example

#9d2dff

from

required

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

Array<number>

Example

[
  120,
  700
]

to

required

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

Array<number>

Example

[
  420,
  520
]

Responses

201

Created

Media typeapplication/json

object

data

required

object

id

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:

object

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

x

required

Left edge of the rectangle.

number

y

required

Top edge of the rectangle.

number

width

required

Width of the rectangle.

number

height

required

Height of the rectangle.

number

object

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>>

object

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>

to

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

id

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:

object

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

x

required

Left edge of the rectangle.

number

y

required

Top edge of the rectangle.

number

width

required

Width of the rectangle.

number

height

required

Height of the rectangle.

number

object

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>>

object

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>

to

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.

Media typeapplication/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.

Media typeapplication/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": "unauthenticated",
    "message": "Bearer token is missing or invalid"
  }
}

403

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

Media typeapplication/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": "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.

Media typeapplication/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": "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.

Media typeapplication/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": "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.

Media typeapplication/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": "rate_limited",
    "message": "Rate limit of 1000 units per 60s exceeded (this request cost 5)"
  }
}

Headers

Retry-After

integer

Example

12

Seconds to wait before retrying.