Outlign

Outlign API

v1.0 Documentation

Comments API

Comments are threaded replies attached to a task (step), a message, or a project info section. The same comment object is used across all three; the commentable_type field tells you what it is attached to.

The Comment Object

{
  "id": 901,
  "commentable_type": "step",
  "commentable_id": 123,
  "content": "Looks good — just tweak the hero copy.",
  "user": {
    "id": 123,
    "name": "John Doe"
  },
  "created_at": "2023-01-01T12:00:00.000000Z",
  "updated_at": "2023-01-01T12:00:00.000000Z"
}

Attributes

Attribute Type Description
id integer Unique identifier for the comment
commentable_type string What the comment is attached to: step, message, or projectinfo
commentable_id integer ID of the parent resource
content string Comment body, returned as Markdown
user object The author (id, name)
created_at string ISO 8601 timestamp
updated_at string ISO 8601 timestamp

List Comments

Comments are listed per parent resource, oldest first. Use the endpoint that matches the resource type you're reading.

GET /api/v1/steps/{step}/comments
GET /api/v1/messages/{message}/comments
GET /api/v1/project-infos/{projectInfo}/comments

Query Parameters

Parameter Type Description
per_page integer Number of results per page (max 1000)

Example Request

GET /api/v1/steps/123/comments
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

[
  {
    "id": 901,
    "commentable_type": "step",
    "commentable_id": 123,
    "content": "Looks good — just tweak the hero copy.",
    "user": { "id": 123, "name": "John Doe" },
    "created_at": "2023-01-01T12:00:00.000000Z",
    "updated_at": "2023-01-01T12:00:00.000000Z"
  }
]

Create a Comment

Posts a comment to a step, message, or project info section. Content may be plain text or Markdown and is converted to Outlign's rich text format on save.

POST /api/v1/steps/{step}/comments
POST /api/v1/messages/{message}/comments
POST /api/v1/project-infos/{projectInfo}/comments

Request Body

Parameter Type Required Description
content string Yes Comment body (plain text or Markdown, max 200,000 characters)

Internal content: Commenting on an internal task (a step in an internal phase) or an internal message requires that you are a member of the agency company that owns the project. Otherwise the request returns 403 Forbidden.

Example Request

POST /api/v1/steps/123/comments
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "content": "Looks good — just tweak the hero copy."
}

Example Response

201 Created

{
  "id": 902,
  "commentable_type": "step",
  "commentable_id": 123,
  "content": "Looks good — just tweak the hero copy.",
  "user": { "id": 123, "name": "John Doe" },
  "created_at": "2023-01-15T10:00:00.000000Z",
  "updated_at": "2023-01-15T10:00:00.000000Z"
}

Update a Comment

Edits a comment you authored. You can only edit your own comments, and only while you still have access to the parent resource.

Attachments, form fields, and embeds are preserved on content updates. Markdown cannot express these elements, so when content replaces the body, any such elements in the existing content are kept in place even if your markdown omits them (elements retained as plain links are upgraded back to their original form). To remove them deliberately, pass allow_removing_attachments: true.

PUT PATCH /api/v1/comments/{comment}

Request Body

Parameter Type Required Description
content string Yes Updated body (plain text or Markdown, max 200,000 characters)

Example Request

PATCH /api/v1/comments/902
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

{
  "content": "Updated: tighten the hero copy and bump the CTA."
}

Delete a Comment

Deletes a comment you authored.

DELETE /api/v1/comments/{comment}

Example Request

DELETE /api/v1/comments/902
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Response

204 No Content