Clarify

Clarify Comments API

The Comments API from Clarify — 2 operation(s) for comments.

GitHub OpenAPI

Operations 4

POST /workspaces/{workspace}/comments Create a comment #
GET /workspaces/{workspace}/comments/{id} Get a comment #
PATCH /workspaces/{workspace}/comments/{id} Update a comment #
DELETE /workspaces/{workspace}/comments/{id} Delete a comment #

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/openapi/clarify-comments-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-list-of-workflows-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-workflow-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-workspace-settings-dto-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-create-relationship-dto-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-list-of-activities-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/clarify/refs/heads/main/json-schema/clarify-update-layout-body-dto-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clarify:clarify-comments-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clarify-comments-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clarify Comments API
  description: The Clarify API OpenAPI documentation
  version: '0.1'
  contact: {}
servers:
- url: https://api.clarify.ai/v1
security:
- apiKey: []
tags:
- name: Comments
paths:
  /workspaces/{workspace}/comments:
    post:
      description: Creates a comment on a record. The comment body is rich text, and `owner_id` plus `entity` identify the record it is attached to. Returns the created comment row.
      operationId: createComment
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentDto'
            examples:
              create:
                summary: Comment on a person record
                value:
                  entity: person
                  owner_id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                  message:
                  - id: '1'
                    type: paragraph
                    children: []
                    content:
                    - type: text
                      text: Followed up after the QBR — Jane wants pricing by Friday.
                      styles: {}
      responses:
        '201':
          description: The created comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentRow'
              example:
                _id: 9d3e1f7a-2c4b-4e6d-8a1f-5b7c9e0d2a46
                message:
                - id: '1'
                  type: paragraph
                  children: []
                  content:
                  - type: text
                    text: Followed up after the QBR — Jane wants pricing by Friday.
                    styles: {}
                owner_id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                entity: person
                _created_at: '2026-01-15T09:30:00.000Z'
                _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                _updated_at: null
                _updated_by: null
        '403':
          description: '`owner_id` does not resolve to a record you can comment on.'
        '422':
          description: The message is empty, or the entity does not support comments.
      summary: Create a comment
      tags:
      - Comments
  /workspaces/{workspace}/comments/{id}:
    get:
      description: Returns a single comment by its ID.
      operationId: getComment
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the comment.
        schema:
          type: string
      responses:
        '200':
          description: The requested comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentRow'
              example:
                _id: 9d3e1f7a-2c4b-4e6d-8a1f-5b7c9e0d2a46
                message:
                - id: '1'
                  type: paragraph
                  children: []
                  content:
                  - type: text
                    text: Followed up after the QBR — Jane wants pricing by Friday.
                    styles: {}
                owner_id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                entity: person
                _created_at: '2026-01-15T09:30:00.000Z'
                _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                _updated_at: null
                _updated_by: null
      summary: Get a comment
      tags:
      - Comments
    patch:
      description: Replaces the body of an existing comment. Only the comment’s author may edit it. Returns the updated comment.
      operationId: updateComment
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the comment.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCommentDto'
            examples:
              update:
                summary: Edit the comment body
                value:
                  message:
                  - id: '1'
                    type: paragraph
                    children: []
                    content:
                    - type: text
                      text: Followed up after the QBR — Jane signed off on pricing.
                      styles: {}
      responses:
        '200':
          description: The updated comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentRow'
              example:
                _id: 9d3e1f7a-2c4b-4e6d-8a1f-5b7c9e0d2a46
                message:
                - id: '1'
                  type: paragraph
                  children: []
                  content:
                  - type: text
                    text: Followed up after the QBR — Jane wants pricing by Friday.
                    styles: {}
                owner_id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                entity: person
                _created_at: '2026-01-15T09:30:00.000Z'
                _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                _updated_at: null
                _updated_by: null
        '403':
          description: The caller is not the author of the comment.
        '404':
          description: No comment exists with that ID.
        '422':
          description: The message is empty.
      summary: Update a comment
      tags:
      - Comments
    delete:
      description: Permanently deletes a comment. A comment can be deleted by its author, by an admin, or by the owner of the agent that posted it. Returns the deleted comment. This cannot be undone.
      operationId: deleteComment
      parameters:
      - name: workspace
        required: true
        in: path
        description: The workspace slug — the `{slug}` segment of your Clarify workspace URL.
        schema:
          type: string
      - name: id
        required: true
        in: path
        description: The unique ID of the comment.
        schema:
          type: string
      - name: silent
        in: query
        required: false
        schema:
          type: boolean
        description: When true, suppresses in-app and Slack notifications for this mutation.
      responses:
        '200':
          description: The deleted comment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentRow'
              example:
                _id: 9d3e1f7a-2c4b-4e6d-8a1f-5b7c9e0d2a46
                message:
                - id: '1'
                  type: paragraph
                  children: []
                  content:
                  - type: text
                    text: Followed up after the QBR — Jane wants pricing by Friday.
                    styles: {}
                owner_id: 5f8b7d2e-9c4a-4e1b-8f3d-2a6c9e0b4d71
                entity: person
                _created_at: '2026-01-15T09:30:00.000Z'
                _created_by: 7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81
                _updated_at: null
                _updated_by: null
      summary: Delete a comment
      tags:
      - Comments
components:
  schemas:
    UpdateCommentDto:
      type: object
      properties:
        message:
          description: The comment body, as a non-empty array of rich-text (BlockNote) nodes.
          type: array
          items:
            type: object
            additionalProperties: {}
      required:
      - message
    CreateCommentDto:
      type: object
      properties:
        _id:
          type: string
          format: uuid
          description: The unique ID of the comment. Generated by the server when omitted on create.
        message:
          description: The comment body, as a non-empty array of rich-text (BlockNote) nodes.
          type: array
          items:
            type: object
            additionalProperties: {}
        owner_id:
          type: string
          description: The unique ID of the record the comment is attached to.
        entity:
          description: The object type of the record the comment is attached to. Must be an object that supports comments (e.g. `person`, `deal`, `task`, or a custom object such as `c_dog`). Lead-finder records (`tam_person`, `tam_company`) cannot be commented on.
          type: string
        _event_id:
          type: string
          format: uuid
          description: An optional client-supplied ID for the comment creation event; generated by the server when omitted.
      required:
      - message
      - owner_id
      - entity
    CommentRow:
      type: object
      properties:
        _id:
          type: string
          format: uuid
          description: The unique ID of the comment. Generated by the server when omitted on create.
        message:
          description: The comment body, as a non-empty array of rich-text (BlockNote) nodes.
          type: array
          items:
            type: object
            additionalProperties: {}
        owner_id:
          type: string
          description: The unique ID of the record the comment is attached to.
        entity:
          description: The object type of the record the comment is attached to. Must be an object that supports comments (e.g. `person`, `deal`, `task`, or a custom object such as `c_dog`). Lead-finder records (`tam_person`, `tam_company`) cannot be commented on.
          type: string
        _created_at:
          type: string
          format: date-time
          description: The time the comment was created.
        _created_by:
          type: string
          description: The ID of the user or agent that created the comment.
        _updated_at:
          type: string
          format: date-time
          nullable: true
          description: The time the comment was last edited, or `null` if it has never been edited.
        _updated_by:
          type: string
          nullable: true
          description: The ID of the user or agent that last edited the comment, or `null` if it has never been edited.
      required:
      - message
      - owner_id
      - entity
      - _created_at
      - _created_by
      - _updated_at
      - _updated_by
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key authentication. Send your key in the Authorization header as: `api-key <your-api-key>`.'
    bearer:
      type: http
      scheme: bearer
      description: 'User access token authentication for endpoints that act across workspaces. Send a WorkOS access token in the Authorization header as: `Bearer <token>`.'