Skip to content
Swingback, home

API reference

Comments

Comments are the conversation on a post, with one level of replies. Internal notes are comments that only your team sees: the portal never shows them. A post has at most one pinned comment, and a deleted comment goes to the trash with its replies.

The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

List comments#

GET/v1/workspaces/{workspace_id}/comments

Any API key: Read or Read and write

Returns the comments on live posts, internal notes included, newest first, or the comments in the trash with deleted=true. The review queue for comments is moderation_state=held with sort=oldest.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

Query parameters

  • sortstring

    newest first (the default), or oldest first.

    One ofnewestoldest
  • moderation_statearray of strings

    Only the comments in any of these moderation states. Repeat the parameter for each value.

    Each one ofapprovedheldrejected

    At most 3 items

  • visibilitystring

    Only the public comments, or only the internal notes.

    One ofpublicinternal
  • deletedboolean

    Return the items in the trash instead of the live ones.

    Defaults to false

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl
  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • cursorstring

    The previous page's next_cursor, to get the next page.

    At most 1,024 characters

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments?moderation_state=held&sort=oldest"
Response · 200 OK
{
  "data": [
    {
      "id": "comment_01h455vb4pex5vsknk084sn02q",
      "attachments": [],
      "author": {
        "id": "user_01h455vb4pex5vsknk084sn04s",
        "avatar_url": null,
        "email": "lee@example.com",
        "external_id": "u-9031",
        "kind": "user",
        "name": "Lee Park"
      },
      "body_html": "<p>We need this for quarterly reports too.</p>",
      "body_md": "We need this for quarterly reports too.",
      "heart_count": 0,
      "hearted": false,
      "language": "en",
      "mentions": [],
      "moderation_flags": [
        {
          "reason": "approval",
          "detail": "",
          "created_at": "2026-09-28T14:03:12.482Z"
        }
      ],
      "moderation_state": "held",
      "parent_id": null,
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "source": "portal",
      "translation": null,
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null,
      "edited_at": null,
      "pinned_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

List a post's comments#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/comments

Any API key: Read or Read and write

Returns the post's live comments, internal notes included, oldest first, or its comments in the trash with deleted=true. A reply names its comment in parent_id. A reply is hidden while its parent is in the trash.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Query parameters

  • visibilitystring

    Only the public comments, or only the internal notes.

    One ofpublicinternal
  • pinnedboolean

    Only the pinned comment.

    Defaults to false

  • deletedboolean

    Return the items in the trash instead of the live ones.

    Defaults to false

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl
  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • cursorstring

    The previous page's next_cursor, to get the next page.

    At most 1,024 characters

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/comments"
Response · 200 OK
{
  "data": [
    {
      "id": "comment_01h455vb4pex5vsknk084sn02q",
      "attachments": [],
      "author": {
        "id": "user_01h455vb4pex5vsknk084sn04s",
        "avatar_url": null,
        "email": "lee@example.com",
        "external_id": "u-9031",
        "kind": "user",
        "name": "Lee Park"
      },
      "body_html": "<p>We need this for quarterly reports too.</p>",
      "body_md": "We need this for quarterly reports too.",
      "heart_count": 2,
      "hearted": false,
      "language": "en",
      "mentions": [],
      "moderation_flags": [],
      "moderation_state": "approved",
      "parent_id": null,
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "source": "api",
      "translation": null,
      "visibility": "public",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null,
      "edited_at": null,
      "pinned_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Create a comment#

POST/v1/workspaces/{workspace_id}/posts/{post_id}/comments

An API key with Read and write access

Adds a comment to the post. With an API key, author is required: it names the end user who comments, who is created if new. Authors of public comments follow the post.

visibility: internal makes an internal note, which only your team sees. Its author must be a team member's end user, or the request fails validation with not_team on author. A reply (parent_id) answers a top-level comment, since replies have no replies of their own (not_top_level on parent_id). A reply to an internal note is internal: asking for public fails with internal_parent on visibility.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Headers

  • Idempotency-Keystring

    Makes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.

    1 to 255 characters

Request body

application/jsonrequired
  • authorobjectrequired

    Who writes the comment: an existing end user by id, or a customer by external_id or email, who's created if new. The author of a public comment follows the post.

    An internal note's author is a team member's end user, by id. List end users finds it: its kind is team, and q finds it by the member's email. A teammate has an end user once they've posted, commented, voted, followed a post or liked a comment, signed in to the portal, been mentioned, or been named as a changelog entry's author or in an import.

    Child fields (5)
    • idstring

      An existing end user's id. Send it alone, without the other fields.

      Starts with user_

    • external_idstring

      The customer's id in your system. Swingback looks for the customer by it first.

      1 to 255 characters

    • emailstring · email

      The customer's email. Without a match on external_id, Swingback looks for the customer by email.

      At most 254 characters

    • namestring

      The customer's name, which replaces the one Swingback has.

      1 to 100 characters

    • avatar_urlstring · URL

      The address of the customer's avatar, http or https, which replaces the one Swingback has.

      At most 2,048 characters

  • body_mdstringrequired

    The comment's Markdown. A team author mentions someone with their token: <@user_…> with an end user's id, or <@mem_…> with a member's id, which is stored as the member's end-user token. A note can mention members. A public comment can mention members and the post's customers: its author, commenters, voters and followers. A comment mentions at most 10 people. Mentioning anyone else fails validation with mention_not_allowed on body_md, and mentioning more people with too_many_mentions. In a customer's comment, tokens are plain text and mention nobody.

    1 to 10,000 characters

  • asset_idsarray of strings

    Uploaded images to attach, in order, from your own uploads that aren't attached to anything yet.

    At most 4 itemsEach starts with asset_

  • parent_idstring

    The top-level comment this one replies to.

    Starts with comment_

  • visibilitystring

    public, or internal for a note for your team, which the portal never shows.

    One ofpublicinternal

Responses

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body_md": "We need this for quarterly reports too.",
    "author": {
      "external_id": "u-9031",
      "email": "lee@example.com",
      "name": "Lee Park"
    }
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/comments"
Response · 201 Created
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 0,
  "hearted": false,
  "language": null,
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

Retrieve a comment#

GET/v1/workspaces/{workspace_id}/comments/{comment_id}

Any API key: Read or Read and write

Returns a comment, live or in the trash.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Query parameters

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

Update a comment#

PATCH/v1/workspaces/{workspace_id}/comments/{comment_id}

An API key with Read and write access

Fields you don't send stay unchanged. Whoever edits it, the body is still rendered as its author's text: in a customer's comment, images don't show and links are marked nofollow. A comment in the trash, in a thread in the trash, or on a post in the trash or on a board in the trash returns 409 in_trash. A comment copied from a GitHub or Linear issue is read-only (409 synced_comment).

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Request body

application/jsonrequired
  • body_mdstring

    The comment's Markdown, with mentions written as when you create a comment. People the new text adds are notified, and people it drops are no longer mentioned. Someone who's already mentioned can stay, even if they couldn't be mentioned now.

    1 to 10,000 characters

  • asset_idsarray of strings

    The images to attach, in order, in place of the current ones. Images already attached can stay; any others must be your own uploads that aren't attached to anything yet.

    At most 4 itemsEach starts with asset_

Responses

Example

Request
curl -X PATCH \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body_md": "We need this for yearly reports too."
  }' \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for yearly reports too.</p>",
  "body_md": "We need this for yearly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": null,
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": "2026-10-02T09:30:00.000Z",
  "pinned_at": null
}

Delete a comment#

DELETE/v1/workspaces/{workspace_id}/comments/{comment_id}

An API key with Read and write access

Moves the comment to the trash, and hides its replies with it. It stays there for 30 days, then is deleted for good, with its replies. Deleting a comment that's already in the trash changes nothing. A comment copied from a GitHub or Linear issue can't be deleted here (409 synced_comment).

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Responses

  • 204
    No ContentThe comment is in the trash.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

Restore a comment#

POST/v1/workspaces/{workspace_id}/comments/{comment_id}/restore

An API key with Read and write access

Takes the comment out of the trash, and its replies show again. A comment on a post in the trash, or on a board in the trash, returns 409 in_trash. Restoring a live comment changes nothing.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Headers

  • Idempotency-Keystring

    Makes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.

    1 to 255 characters

Responses

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q/restore"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

Pin a comment#

PUT/v1/workspaces/{workspace_id}/comments/{comment_id}/pin

An API key with Read and write access

Pins a public top-level comment on the post it was written on, in place of the post's pinned comment if it has one. Any other comment, including one that shows on the post only through a merge, returns 422 not_pinnable. A comment in the trash, in a thread in the trash, or on a post or a board in the trash returns 409 in_trash. Pinning a pinned comment again changes nothing.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Responses

Example

Request
curl -X PUT \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q/pin"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": "2026-10-02T09:30:00.000Z"
}

Unpin a comment#

DELETE/v1/workspaces/{workspace_id}/comments/{comment_id}/pin

An API key with Read and write access

Unpins the comment. A comment in the trash, in a thread in the trash, or on a post or a board in the trash returns 409 in_trash. Unpinning a comment that isn't pinned changes nothing.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • comment_idstringrequired

    The comment's id.

    Starts with comment_

Responses

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/comments/comment_01h455vb4pex5vsknk084sn02q/pin"
Response · 200 OK
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

List a post's activity#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/activity

Any API key: Read or Read and write

Returns the post's timeline, oldest first: its live comments, internal notes included, and its status changes.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Query parameters

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl
  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • cursorstring

    The previous page's next_cursor, to get the next page.

    At most 1,024 characters

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/activity"
Response · 200 OK
{
  "data": [
    {
      "comment": {
        "id": "comment_01h455vb4pex5vsknk084sn02q",
        "attachments": [],
        "author": {
          "id": "user_01h455vb4pex5vsknk084sn04s",
          "avatar_url": null,
          "email": "lee@example.com",
          "external_id": "u-9031",
          "kind": "user",
          "name": "Lee Park"
        },
        "body_html": "<p>We need this for quarterly reports too.</p>",
        "body_md": "We need this for quarterly reports too.",
        "heart_count": 2,
        "hearted": false,
        "language": "en",
        "mentions": [],
        "moderation_flags": [],
        "moderation_state": "approved",
        "parent_id": null,
        "post_id": "post_01h455vb4pex5vsknk084sn02q",
        "source": "api",
        "translation": null,
        "visibility": "public",
        "created_at": "2026-09-28T14:03:12.482Z",
        "updated_at": "2026-09-28T14:03:12.482Z",
        "deleted_at": null,
        "edited_at": null,
        "pinned_at": null
      },
      "type": "comment",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

The comment object#

Fields

  • idstring

    Starts with comment_

  • attachmentsarray of objects

    Each item is an asset object.

  • authorobject

    Who wrote the comment.

    Child fields (6)
    • idstring

      Starts with user_

    • avatar_urlstringnullable
    • emailstring · emailnullable
    • external_idstringnullable
    • kindstring

      user for a customer, team for the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), and guest for someone who wrote in the portal without signing in.

      One ofuserteamguest
    • namestringnullable
  • body_htmlstring

    body_md, rendered as sanitized HTML. A mention becomes <span class="mention">@Name</span>, written for the reader: the person's name, else their email, or "Someone" if they were erased since. A token that names nobody (one that isn't in mentions) shows as written.

  • body_mdstring

    The comment's Markdown. A mention is the person's token, such as <@user_…> (see mentions).

    At most 10,000 characters

  • heart_countinteger

    How many people liked the comment.

  • heartedboolean

    Whether the signed-in member liked the comment. Always false with an API key.

  • languagestringnullable

    The language the comment is written in, as the AI detected it: an ISO 639-1 code, such as ja. Null until the workspace's translation has read the comment, when the AI can't name the language, and always for an internal note, which is never sent to the AI.

  • mentionsarray of objects

    The people the comment mentions. Your team can mention teammates in a note or a comment, and the post's customers in a public comment. Each person mentioned is notified once, in the app and by email.

    Fields of each item (4)
    • idstring

      Starts with user_

    • emailstring · emailnullable
    • kindstring

      team for a teammate, user for a customer.

      One ofteamuser
    • namestringnullable
  • moderation_flagsarray of objects

    Why the comment is held. Empty once your team has decided.

    Fields of each item (3)
    • detailstring

      What the reason found: the kinds of data for sensitive_data, separated by commas; the category for ai; why for ai_unavailable. Empty for the other reasons.

      At most 200 characters

    • reasonstring

      approval: the workspace reviews this kind of content first. sensitive_data: a card number, an IBAN, a key or a token (detail lists the kinds). links: more than 3 links. duplicate: the author wrote the same text in the last 24 hours. ai: the AI moderation found what detail names (spam, abuse, sexual, violence or personal_data). ai_unavailable: a guest's text that the AI moderation couldn't judge (detail says why).

      One ofapprovalsensitive_datalinksduplicateaiai_unavailable
    • created_atstring · date-time
  • moderation_statestring

    approved content shows in the portal. held content waits for your team's review, and rejected content shows only to its author and your team. What your team and API keys create is always approved.

    One ofapprovedheldrejected
  • parent_idstringnullable

    The top-level comment this one replies to.

    Starts with comment_

  • post_idstring

    Starts with post_

  • sourcestring

    Where the comment came from: dashboard (your team, in the dashboard), api (an API key or the MCP server), portal (someone on the portal or in the widget) or import. github and linear mark a comment someone wrote on a linked issue in that tracker.

    Such a synced comment is an internal note, or a public comment where the connection's settings publish it, as its visibility says. It follows its original: it changes and is deleted with it. Nobody can edit it, delete it or reply to it here (409 synced_comment). A public one is moderated like any comment.

    One ofdashboardapiportalimportgithublinear
  • translationobjectnullable

    The comment in the language the request asked for with language. Null without that parameter, for a comment written in that language, for one the AI hasn't translated, and for an internal note.

    Child fields (2)
    • body_htmlstring

      The translated text, rendered as sanitized HTML like the original.

    • languagestring

      One of the seven languages the portal and Swingback's emails come in.

      One ofenfrdeesitptnl
  • visibilitystring

    public, or internal for a note for your team, which the portal never shows.

    One ofpublicinternal
  • created_atstring · date-time
  • updated_atstring · date-time
  • deleted_atstring · date-timenullable

    Set while the comment is in the trash.

  • edited_atstring · date-timenullable

    When the comment's text was last edited.

  • pinned_atstring · date-timenullable

    When the comment was pinned on its post. Null when it isn't pinned.

Example

The comment object
{
  "id": "comment_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "body_html": "<p>We need this for quarterly reports too.</p>",
  "body_md": "We need this for quarterly reports too.",
  "heart_count": 2,
  "hearted": false,
  "language": "en",
  "mentions": [],
  "moderation_flags": [],
  "moderation_state": "approved",
  "parent_id": null,
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "source": "api",
  "translation": null,
  "visibility": "public",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "pinned_at": null
}

The activity object#

One entry in a post's timeline, a comment or a status_change, as its type says.

Fields

Example

The activity object
{
  "comment": {
    "id": "comment_01h455vb4pex5vsknk084sn02q",
    "attachments": [],
    "author": {
      "id": "user_01h455vb4pex5vsknk084sn04s",
      "avatar_url": null,
      "email": "lee@example.com",
      "external_id": "u-9031",
      "kind": "user",
      "name": "Lee Park"
    },
    "body_html": "<p>We need this for quarterly reports too.</p>",
    "body_md": "We need this for quarterly reports too.",
    "heart_count": 2,
    "hearted": false,
    "language": "en",
    "mentions": [],
    "moderation_flags": [],
    "moderation_state": "approved",
    "parent_id": null,
    "post_id": "post_01h455vb4pex5vsknk084sn02q",
    "source": "api",
    "translation": null,
    "visibility": "public",
    "created_at": "2026-09-28T14:03:12.482Z",
    "updated_at": "2026-09-28T14:03:12.482Z",
    "deleted_at": null,
    "edited_at": null,
    "pinned_at": null
  },
  "type": "comment",
  "created_at": "2026-09-28T14:03:12.482Z"
}

Search pages, sections and code: a setting, an event, a method.