Org Content

Promote a news item to users

POST/org-content/news/{id}/actions/promote
org-content:writepromote_org_news

Starts the job that sends the news item by notification and email to your organisation's members of the given lists and classifications (up to 100 live ids each, else 422), one send per list or classification membership, and returns 202 with the job. Drafts and future items are sent as well. A repeat while a job is queued or running is 409 invalid_state. Needs permission to manage content. dry_run answers 202 with meta.dry_run, no job, no Location. Emits news.promoted after the sends. It can't be undone.

Path parameters

  • idstring (uuid)Required#

    The item's id.

Query parameters

  • dry_runboolean#

    Validate and run the call without committing it, returning what the real call would return with meta.dry_run set.

Headers

  • Idempotency-Keystring#

    Makes a retry safe. Send a new UUID for each new request and reuse it only to retry that request; the first response is replayed for 24 hours.

Request body

application/json, required · NewsPromote

  • titlestringRequired#

    The email subject.

  • bodystringRequired#

    The message, as Markdown. It is converted to safe HTML for the email.

  • distribution_list_idsinteger[]#

    Distribution lists of your organisation. Every live member of your organisation is sent the promotion.

  • classification_idsinteger[]#

    Investor classifications of your organisation. Every live member of your organisation is sent the promotion.

{
  "title": "Our quarterly results",
  "body": "We have published the figures for the quarter.",
  "distribution_list_ids": [
    12
  ],
  "classification_ids": [
    3
  ]
}

Responses

202

The job that sends the promotion was started.

Job
{
  "data": {
    "id": "9a9d1c5e-4f2b-4c8e-9a7d-2f1e6b3c4d5a",
    "type": "string",
    "status": "queued",
    "progress": {
      "done": 1,
      "total": 1
    },
    "result": {},
    "error": {},
    "created_at": "2026-06-12T10:00:00+00:00",
    "updated_at": "2026-06-12T10:00:00+00:00",
    "completed_at": "2026-06-12T10:00:00+00:00"
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
404

Resource not found (error.code = not_found).

Error
409

The request conflicts with existing state (error.code = conflict), e.g. a compliance flow with the requested name already exists.

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl -X POST https://your-org-domain/kong/core/api/v2/org-content/news/{id}/actions/promote\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"\
  -d '{
  "title": "Our quarterly results",
  "body": "We have published the figures for the quarter.",
  "distribution_list_ids": [
    12
  ],
  "classification_ids": [
    3
  ]
}'