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.

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