GuidesAPI DocsChangelogMy AppsSeismic Exchange
API Docs

Create a new comment on a program, task, or request

post
https://api.seismic.com/programs/v2/spaces//nodes//comments

Creates a new comment on the specified entity (program, task, or request) to enable team collaboration and
communication. The comment will be associated with the authenticated user and include all necessary metadata
for tracking and display in collaborative interfaces.

Key Features:

  • Creates comments with rich text content and metadata
  • Automatically associates comment with the authenticated user
  • Validates comment content for security and consistency
  • Returns complete comment object with generated IDs and timestamps
  • Supports mentions and formatting for enhanced collaboration

Authorization Logic:

  1. User must have a valid JWT token with program management scopes
  2. Token is valid for this operation
  3. User must have permission to comment on the specified entity
  4. User must have access to the space containing the entity

Usage Example:

Add feedback or questions to a program to facilitate team discussion and collaborative decision-making.

Path Params
string
required
length between 7 and 22

The unique identifier of the space containing the target entity. This determines the scope of entity queries and ensures proper access control. The space must be accessible to the authenticated user with appropriate permissions. It can be the unique identifier (GUID) of the space or the word "default" to indicate the default programs space. Common values include "default" and "rkr83lapKkyCJuLLWqLqzB".

string
required

The unique identifier of the entity (program, task, or request) to create a comment on. This entity must exist
within the specified space and be accessible to the authenticated user.

Body Params
string | null

Type classification for visual annotations or markups associated with this comment if it includes highlighting, drawing, or other graphical elements on content. Common values include 'highlight', 'text', 'freehand', 'rectangle', 'arrow', or 'stamp'. Use this to specify what kind of visual indicator should accompany the comment in document viewers or content displays. Set to null for standard text-only comments without visual annotations. Determines how the annotationPayload should be interpreted and rendered in the UI. Enables rich commenting features like highlighting specific text passages or marking up slides.

string | null

JSON-encoded string containing annotation-specific data required to render and position the visual markup associated with this comment. Typical payload structure includes coordinates (x, y positions), dimensions (width, height), color values, highlighted text ranges, drawing paths, or shape properties depending on the annotationType. Use this to provide all necessary information for recreating the annotation in content viewers. For example, a highlight annotation might include startIndex/endIndex ranges and color properties. Set to null for comments without visual annotations. Payload format varies by annotation type and client implementation.

string

The textual content of the comment provided by the user containing the actual message, feedback, question, or note being communicated. Required field that supports plain text or markdown formatting depending on client capabilities and API configuration. Content is saved as-is without additional processing or sanitization beyond standard security measures. Typical length ranges from a few words to several paragraphs (1-2000 characters). Use clear, constructive language for effective collaboration. Examples include review feedback like 'This section needs clarification on the timeline' or questions like 'Should we include Q4 results here?'. Cannot be empty or whitespace-only as it represents the core purpose of creating a comment.

boolean | null

Boolean flag indicating whether this comment should be marked as resolved or completed at creation time. Set to true when creating a comment that documents a resolved issue or represents final approval, or false (default) for comments requiring attention or response. Use this to control initial resolution state for workflow automation scenarios where comments are created programmatically with predetermined resolution status. Null defaults to false (unresolved). When true, the comment may be filtered from active comment lists and displayed in resolved/completed views. Useful for batch comment creation or migration scenarios where resolution state needs to be preserved.

Responses

Updated 1 day ago

Language
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 1 day ago