# Manage comments using OpenAPI

> OpenAPI endpoints and uip ah CLI commands for listing, posting, editing, and deleting comments on ideas and business processes in Automation Hub.

List, post, edit, and delete comments on ideas and business processes by calling the `/api/v1/openapi/automations/{id}/comments` endpoints, or by using the `uip ah automations comments` commands.

## Prerequisites

- You have an active Automation Hub API token. For instructions, see [Generate your Token from Automation Hub](generate-your-token-from-automation-hub.md).
- You know the numeric ID of the idea or business process (`automationId`). To find it, use the Get Automations API request.
- The user that the call acts as can view the idea or business process.

## Authentication and authorship

The comment author depends on the type of token you use:

| Token | Author of the comment |
| --- | --- |
| Token tied to a user | The user of the token. |
| Token not tied to a user | The active Automation Hub user whose email address you pass in the `submitter` field. A call without a valid, active `submitter` returns `403`. |

The author must be able to view the idea or business process. You can edit or delete a comment only if you are its author.

## Endpoints

| Action | Request | Body |
| --- | --- | --- |
| List comments | `GET /api/v1/openapi/automations/{id}/comments` | None. Optional query parameters: `page` and `limit`. |
| Post a comment | `POST /api/v1/openapi/automations/{id}/comments` | `text`, and optionally `parent_comment_id` and `submitter` |
| Edit a comment | `PUT /api/v1/openapi/automations/{id}/comments/{commentId}` | `text`, and optionally `submitter` |
| Delete a comment | `DELETE /api/v1/openapi/automations/{id}/comments/{commentId}` | `submitter`, in the JSON body, if the token is not tied to a user |

Send the same authentication headers as for the other OpenAPI calls. For details, see [Authenticating to your Automation Hub tenant](authenticating-to-your-automation-hub-tenant.md).

| Header | Value |
| --- | --- |
| `Authorization` | `Bearer <tenant-id>/<your-access-token>` |
| `x-ah-openapi-auth` | `openapi-token` |
| `x-ah-openapi-app-key` | Your API key, if you added one. |
| `Content-Type` | `application/json`, for `POST` and `PUT` requests |

## List comments

The list returns top-level comments, newest first, each with its replies, author, and created and updated timestamps. Each comment is returned as plain text (`text`) and in its stored rich text (DraftJS) format (`text_draftjs`).

| Query parameter | Description |
| --- | --- |
| `page` | The page number, starting at 1. The default is 1. |
| `limit` | The number of top-level comments per page, up to 100. The default is 20. A value of 5 or less also returns 20. |

## Post a comment

Send the comment as plain text of 1 to 2,000 characters. Line breaks are kept. To reply to a comment, set `parent_comment_id` to the ID of that comment.

```json
{
  "text": "Approved for the next planning cycle.",
  "parent_comment_id": 1234,
  "submitter": "jane.doe@email.com"
}
```

The comment shows in the interface with the correct author and time. Automation Hub sends the same notifications (to followers, collaborators, mentioned users, and the author of the parent comment) as for a comment posted in the interface.

## Edit a comment

Send the new text of the comment, as plain text of 1 to 2,000 characters. The new text replaces the whole comment, including any `@mentions` it had. Plain text cannot add mentions, so an edit removes the existing ones, and Automation Hub sends no mention notifications.

```json
{
  "text": "Approved for the next planning cycle, pending budget review.",
  "submitter": "jane.doe@email.com"
}
```

## Delete a comment

Automation Hub removes the comment from the idea or business process and updates the comment count of the automation. When you delete a reply, it also updates the reply count of the parent comment.

If the token is not tied to a user, send the email address of the comment's author in the `submitter` field of the JSON body.

## Use the CLI

| Action | Command |
| --- | --- |
| List comments | `uip ah automations comments list <automation-id>` |
| Post a comment | `uip ah automations comments add <automation-id> --text "<comment-text>"` |
| Edit a comment | `uip ah automations comments edit <automation-id> <comment-id> --text "<comment-text>"` |
| Delete a comment | `uip ah automations comments delete <automation-id> <comment-id>` |

The `edit` and `delete` commands accept the `--submitter` option, which takes the email address of the user the call acts as.

## Error codes

| Code | Meaning |
| --- | --- |
| `400` | Bad request. The request body or a parameter is not valid, for example when `text` is empty or longer than 2,000 characters. |
| `403` | Forbidden. The user cannot view the automation, is not the author of the comment, or the token is not tied to a user and no valid `submitter` was passed. |
| `404` | Not found. The idea or business process does not exist, or the comment does not exist on it or was already deleted. |
