Commentary

A comment is the accounting commentary for a lens on a date: a headline and a text, as reports show it. Comments made on the legacy platform are listed too, with origin: "legacy"; they are read-only until your tenant has moved. Reads need the reports:read scope; writes need reports:write and an operator seat (owner, admin, advisor) or a group with the reports module at read_write. Every write takes ?dry_run=true and an Idempotency-Key header.

The comment object

idstring: Stable identifier for the comment. A UUID — treat it as opaque.
lens_idstring: The lens the comment is about.
datestring: The date it is for, YYYY-MM-DD.
headlinestring or null: The headline. null when there is none.
bodystring: The text. Only a legacy comment can be empty (the legacy platform keeps a headline without text).
created_by_user_idstring or null: The id of the user who wrote it. null on a legacy comment: the legacy platform records no author.
updated_by_user_idstring or null: The id of the user who last changed it. null on a legacy comment no one has changed here.
created_atstring: When it was made, ISO 8601 in UTC with microseconds.
updated_atstring: When it was last changed, ISO 8601 in UTC with microseconds.
originstring: legacy (from the legacy platform) or v1 (made through this API).
archived_atstring or null: When it was archived. null while it is active. A comment a generated report showed, or one from the legacy platform, is archived on delete instead of removed.
archived_bystring or null: The id of the user who archived it. null while it is active.
archive_reasonstring or null: The reason sent with the delete. null while it is active or when none was sent.

GET/v1/commentary

List comments

Returns the comments on the lenses you see, newest date first, in the standard v1 list envelope. Archived comments are left out unless you ask for them. Any parameter not listed here is a 400.

Query parameters

lens_idstring: Only this lens.
from_datestring: Comments dated on or after this day, YYYY-MM-DD.
to_datestring: Comments dated on or before this day. A to_date before from_date is a 400.
include_archivedboolean: Include archived comments. Defaults to false.
limitinteger: Page size, 1 to 1 000. Defaults to 100; a larger value is capped at 1 000.
cursorstring: Opaque cursor from the previous page's next_cursor. Omit for the first page. A cursor that does not decode is a 400.

Request

GET/v1/commentary

curl -G https://api.aleta.ai/v1/commentary \
  -H "Authorization: Bearer {access_token}" \
  -d lens_id=0190f5f0-6d1a-7c42-9a5e-3b8f2c1d4e5f

Response

{
  "data": [
    {
      "id": "0190f5f2-1b2c-7d3e-8f40-5a6b7c8d9e0f",
      "lens_id": "0190f5f0-6d1a-7c42-9a5e-3b8f2c1d4e5f",
      "date": "2024-01-31",
      "headline": "Only a headline",
      "body": "",
      "created_by_user_id": null,
      "updated_by_user_id": null,
      "created_at": "2024-02-01T08:00:00.000000Z",
      "updated_at": "2024-02-01T08:00:00.000000Z",
      "origin": "legacy",
      "archived_at": null,
      "archived_by": null,
      "archive_reason": null
    }
  ],
  "next_cursor": null,
  "limit": 100
}

GET/v1/commentary/{id}

Get a comment

Returns one comment, archived or not. An unknown id, an id that is not a UUID, or a comment on a lens you do not see, is a 404.

Request

GET/v1/commentary/{id}

curl https://api.aleta.ai/v1/commentary/0190f5f2-1b2c-7d3e-8f40-5a6b7c8d9e0f \
  -H "Authorization: Bearer {access_token}"

POST/v1/commentary

Create a comment

Makes a comment and answers 201 with it, with origin: "v1". Headline and body are trimmed. The write is kept in the change log.

Body

lens_idstring: Required. The lens the comment is about.
datestring: Required. The date it is for, YYYY-MM-DD.
headlinestring or null: Optional. At most 500 characters. Blank, null or left out means no headline.
bodystring: Required. The text: not blank, at most 20 000 characters.

Every refusal is a 400 with the reason: a missing or unknown field, a blank or too long body, a too long headline, or a lens you do not see (lens_id was not found).

Request

POST/v1/commentary

curl -X POST https://api.aleta.ai/v1/commentary \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: comment-2024-03" \
  -H "Content-Type: application/json" \
  -d '{"lens_id": "0190f5f0-6d1a-7c42-9a5e-3b8f2c1d4e5f", "date": "2024-03-31", "headline": "Q1", "body": "Equities drove the quarter."}'

Response

{
  "id": "0190f5f3-2c3d-7e4f-9a51-6b7c8d9e0f1a",
  "lens_id": "0190f5f0-6d1a-7c42-9a5e-3b8f2c1d4e5f",
  "date": "2024-03-31",
  "headline": "Q1",
  "body": "Equities drove the quarter.",
  "created_by_user_id": "0190f5e1-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
  "updated_by_user_id": "0190f5e1-7a8b-7c9d-8e0f-1a2b3c4d5e6f",
  "created_at": "2024-04-02T09:15:00.123456Z",
  "updated_at": "2024-04-02T09:15:00.123456Z",
  "origin": "v1",
  "archived_at": null,
  "archived_by": null,
  "archive_reason": null
}

PATCH/v1/commentary/{id}

Update a comment

Changes a comment and answers 200 with it. Fields left out are kept; the lens never changes, so lens_id is an unknown field (400). Send at least one of date, headline, body and status: a body with only reason, or none, is a 400. An archived comment can be changed and stays archived unless you send status: active. The write is kept in the change log.

Body

datestring: The new date, YYYY-MM-DD.
headlinestring or null: At most 500 characters. Blank or null clears the headline.
bodystring: The new text: not blank, at most 20 000 characters.
statusstring: active brings back an archived comment; on an active comment it changes nothing. archived is a 400: archive with DELETE.
reasonstring: Why, kept in the change log.

A comment you do not see is a 404. A legacy comment is a 409 with code legacy_managed until your tenant has moved.

Request

PATCH/v1/commentary/{id}

curl -X PATCH https://api.aleta.ai/v1/commentary/0190f5f3-2c3d-7e4f-9a51-6b7c8d9e0f1a \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"headline": null, "reason": "headline not used in the Q1 pack"}'

DELETE/v1/commentary/{id}

Delete a comment

Removes a comment no generated report showed and answers 204. A comment a generated report showed, or one from the legacy platform, is archived instead, so the report's history keeps it: the answer is 200 with the comment. ?reason= is kept as its archive_reason and in the change log (also when the comment is deleted). Any query parameter other than reason and dry_run is a 400. A comment that is archived already answers 200 as it is, and nothing is logged.

A comment you do not see is a 404. A legacy comment is a 409 with code legacy_managed until your tenant has moved. Sent again with the same Idempotency-Key after the comment is gone, the first answer is replayed.

Request

DELETE/v1/commentary/{id}

curl -X DELETE "https://api.aleta.ai/v1/commentary/0190f5f3-2c3d-7e4f-9a51-6b7c8d9e0f1a?reason=superseded" \
  -H "Authorization: Bearer {access_token}"