Manage location timeline comments

Request#

POST /api/v1/locations/{record}/timeline/{type}/{entry}/comments

Requires locations:read and locations:timeline:update. For a todo entry, locations:todos is also required. See token permissions.

Send Authorization: Bearer YOUR_API_TOKEN, Accept: application/json, and Content-Type: application/json. Every operation requires Idempotency-Key. Reuse the same key when retrying the same request.

Path parameters#

record integer Required

The numeric location ID in your token's organization.

type string Required

person_location_event for an event owned by this location, or todo for one of its to-dos.

entry integer Required

The event or to-do ID from entry details.

Query parameters#

This endpoint does not use query parameters.

Request body#

Example#

Get the entry and copy its version and content_version. Set ASSETCENTER_API_TOKEN as described in the quick start, and set IDEMPOTENCY_KEY to a new UUID for this action. Replace the two version placeholders below with the returned values and use your record and entry IDs.

curl --request POST "https://my.assetcenter.app/api/v1/locations/123/timeline/person_location_event/901/comments" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"version":"VERSION","content_version":"CONTENT_VERSION","operation":"create","body":"Follow up next week."}'

For the other operations, include comment_id. Send a body when editing or replying; omit it when deleting. Use the latest versions and a new key for each action.

Response#

201 Created for create and reply; 200 OK for edit and delete. Example of a created comment:

{
  "data": {
    "resource": "locations",
    "record_id": 123,
    "entry_id": 901,
    "type": "person_location_event",
    "operation": "create",
    "comment_id": 7,
    "version": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "content_version": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "comments": [
      {
        "id": 7,
        "parent_id": null,
        "body": "Follow up next week.",
        "created_by": {
          "id": 4,
          "name": "Alex Admin"
        },
        "created_at": "2026-10-11T16:00:00.000000Z",
        "updated_at": "2026-10-11T16:00:00.000000Z"
      }
    ]
  }
}

Behavior and constraints#

The action changes comments only, preserving the entry's details and files. Both versions must match the current entry. A stale version returns 409; retrieve the entry again before submitting a new action. The response provides the new versions and current comments. A comment-only change leaves content_version unchanged.

Comments are attributed to the administrator who created the token. Editing and deleting require that administrator to be the comment's author, even with Full Access. You can reply to another author's top-level comment, but cannot reply to a reply. Violating these author or thread rules returns 403. A comment from another entry or organization returns 422 when selected for a change.

The comments list includes each top-level comment followed by its replies. parent_id is null for a top-level comment and the parent comment ID for a reply. Deleting a top-level comment removes it and its replies from the returned thread. created_by is null if the author is no longer a member of the token's organization. Treat bodies as plain text when displaying them.

Successful responses are remembered for 24 hours per token. An identical retry returns the original response and status with Idempotency-Replayed: true, without duplicating the action. The first success uses Idempotency-Replayed: false. Permissions are checked again before replay. Reusing a key with a different method, path, or body returns 409. Unknown body fields are rejected with 422.

You can also submit bulk comment edits and replies alongside other entry changes through PATCH.

Errors#

401 means the token is missing, expired, revoked, or not a customer API token. 403 means a required permission or administrator access is missing. 404 means the record or entry is unavailable through this path. 422 identifies invalid or unsupported input; inspect the errors object. 429 means a rate limit was reached. See error handling and rate limits. 409 indicates stale entry versions or an idempotency key reused for another request.