List comments

GET

/v1/comments

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.focal.inc/v1/comments");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer <token>");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Get,
    RequestUri = new Uri("https://api.focal.inc/v1/comments"),
    Headers =
    {
        { "Authorization", "Bearer <token>" },
    },
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

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

func main() {

  url := "https://api.focal.inc/v1/comments"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <token>")

  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"))
    .header("Authorization", "Bearer <token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.focal.inc/v1/comments")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build();

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

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.focal.inc/v1/comments',
  headers: {Authorization: 'Bearer <token>'}
};

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

const url = 'https://api.focal.inc/v1/comments';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.focal.inc/v1/comments")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

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

use reqwest;

#[tokio::main]
pub async fn main() {
    let url = "https://api.focal.inc/v1/comments";

    let mut headers = reqwest::header::HeaderMap::new();
    headers.insert("Authorization", "Bearer <token>".parse().unwrap());

    let client = reqwest::Client::new();
    let response = client.get(url)
        .headers(headers)
        .send()
        .await;

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

    dbg!(results);
}

List the comment threads on a media or a board row (task), newest first. Pass exactly one of media_id or row_id.

Each item is a top-level comment with its replies nested under replies, oldest first; limit and the cursor page over the top-level comments only. A comment anchored to a spot on the media — a video moment, a page, or shapes drawn over it — carries that under annotation.

Pass fields to trim the response to the properties you actually need — e.g. ?fields=name,html_url returns just those (plus id, always). Unknown names are rejected rather than ignored.

Required scope: comments:read. Rate-limit cost: 5.

Authorizations

bearerAuth

Parameters

Query Parameters

media_id

string format: uuid

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

row_id

string format: uuid

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

limit

integer

>= 1 <= 100

Max top-level comments per page (1–100). Default 25.

cursor

string

Pagination cursor returned as next_cursor from the previous page.

fields

string

Return only these properties of each comment, instead of the full object. id is always included. Omit for the complete object. Selectable: id, body, author_type, author_id, author_name, space_id, media_id, media_version_id, board_id, row_id, reply_to_id, annotation, mentions, reactions, created_at, updated_at, html_url, reply_count, replies.

Responses

200

application/json

object

data

required

Array<object>

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

next_cursor

required

Pass back as cursor to fetch the next page. null on the last page.

string

nullable

has_more

required

true when another page is available. Equivalent to next_cursor !== null.

boolean

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"
        }
      ]
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNy0wMy0wNFQxMDoxNTowMC4wMDBaIiwiaSI6Ijc4NmJlZWRhLTU1YWMtNDAyNS1iZjZlLTQzYjI5MThlODRhOSJ9",
  "has_more": true
}

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

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.