Skip to main content

Add App History Note

POST /clients/{client_id}/apps/{app_id}/history/notes

Appends a note event to the app history timeline for a single app.

This endpoint does not change app approval state. Use Approve Apps or Remove App Approvals for approval changes.

Path Parameters​

ParameterTypeDescription
client_idstring (uuid)Unique identifier for the client organization
app_idstring (uuid)Unique identifier for the app

Request Body​

FieldTypeRequiredDescription
commentstringYesNote text to append to the timeline

Example Request Body​

{
  "comment": "Waiting for security sign-off"
}

Response​

Returns the created AppHistoryEvent.

Example Request​

curl -X POST "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/apps/f1a2b3c4-d5e6-7890-abcd-ef1234567890/history/notes" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Waiting for security sign-off"
  }'

Example Response​

{
  "id": "81ab9698-7837-43c1-8b89-6b3118b8b1f2",
  "event_type": "note_added",
  "actor": {
    "id": "1b8fbc0f-f234-4da7-9cb2-5ae10ef63b8e",
    "display_name": "Jane Smith"
  },
  "message": "added a note",
  "comment": "Waiting for security sign-off",
  "metadata": null,
  "created_at": "2026-03-05T17:15:00.000Z"
}

Error Responses​

StatusDescription
400Invalid request (e.g. empty comment, invalid UUID)
401Authentication required
403Insufficient permissions for this client
404App or client not found
500Server error

Example Error Response​

{
  "error": {
    "code": "not_found",
    "message": "App not found",
    "details": {
      "app_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890"
    }
  }
}

Notes​

  • This endpoint always creates a note_added event.
  • Notes are append-only.
  • The created event is returned in the same shape used by App History.