Report API

The Report API is how work hands the next step back to Jira. A workflow that Cuelight started reports its result. Anything else, like a pull request workflow, n8n or an AI agent, can offer a next step.

Endpoint

Each Cuelight installation has its own report URL. Find it under Cuelight settings → Reporting, where you can copy it along with ready-made examples.

  • Method: POST
  • Header: Content-Type: application/json
  • Body: a JSON object, 16 KB or smaller

Workflows that Cuelight starts receive the URL as the cuelight_callback_url input, so you only need to copy it for offers.

Two ways to authenticate

Run reportOffer
ForA workflow Cuelight startedAnything else
CredentialRun token in the body as tokenInstall key in Authorization: Bearer <key>
Where it comes fromThe cuelight_token workflow inputCuelight settings → Reporting
Lifetime24 hours from the pressUntil an admin regenerates it
CanUpdate that run and leave next stepsLeave next steps only

A run token is signed by your installation and only works for the run it was issued for. Regenerating the install key makes the old one stop working at once. Keep the key in a secret store, like GitHub Actions secrets or n8n credentials.

When a request has an Authorization header, Cuelight treats it as an offer. Otherwise it expects a run token.

Run report

{
  "token": "eyJyaWQiOi...",
  "status": "success",
  "message": "Deployed 3f2a1c9 to staging",
  "url": "https://github.com/acme/shop/actions/runs/123456789",
  "next": [
    { "action": "rollback-staging" },
    { "action": "promote-production", "inputs": { "reason": "" } }
  ],
  "expiresInHours": 168
}
FieldRequiredRules
tokenYesThe cuelight_token input, unchanged
statusYesrunning, success, failure or cancelled
messagePlain text, up to 500 characters. Never rendered as HTML
urlMust start with https://github.com/. Shown as "View run"
nextUp to 5 steps. Each action must be an action id you've defined
expiresInHours1 to 720. Default 168 (7 days)

You can send running as often as you like, for example with progress messages. The first final status wins; later final reports get 409. Each report from a run replaces the next steps that run left before. The step's "Suggested by" note shows the workflow name.

Offer

{
  "issueKey": "SHOP-1",
  "source": "PR #12",
  "message": "Preview is ready to deploy",
  "next": [{ "action": "deploy-preview", "inputs": { "pr": "12" } }],
  "expiresInHours": 72
}
FieldRequiredRules
issueKeyYesA work item key like SHOP-1
nextYes1 to 5 steps
sourceUp to 60 characters. Shown as "Suggested by PR #12"
messagePlain text, up to 500 characters
expiresInHours1 to 720. Default 168

Offers add to the work item's next steps. Sending the same offer again, with the same source, action and inputs, refreshes it instead of adding a copy. A work item keeps at most five next steps; when there are more, the oldest go first.

Next step inputs

inputs pre-fills the action's form. Values are checked the same way as typed ones: the field must exist in the action's form, text must fit maxLength, and a select value must be one of its options. The person pressing the button can still change them before it runs.

Responses

A successful request returns 202:

{ "ok": true, "run": "3f9c2a7b1e04", "status": "success" }

An offer returns { "ok": true, "issueKey": "SHOP-1", "nextSteps": 1 }, with the number of next steps it left.

Errors return a code and a message that says what to fix:

{
  "error": {
    "code": "unknown_action",
    "message": "Action 'promote-prod' isn't defined. Use an action id from Cuelight settings → Actions."
  }
}
StatusCodeMessage
400invalid_content_typeSend Content-Type: application/json.
400invalid_jsonThe body isn't valid JSON.
400invalid_payloadThe body must be a JSON object, or the field that failed and why
401missing_tokenSend the run token in "token", or an install key in the Authorization header.
401invalid_tokenThe run token is invalid. Pass the cuelight_token input of this run unchanged, from the same Jira site.
401expired_tokenThe run token has expired. Tokens are valid for 24 hours.
401invalid_install_keyThe install key is missing or invalid. Copy it from Cuelight settings → Reporting.
404run_not_foundThis run doesn't exist anymore.
404issue_not_foundWork item SHOP-1 wasn't found.
405method_not_allowedUse POST.
409run_finalThis run already finished with status 'success'.
413too_largeThe body must be 16 KB or smaller.
422unknown_actionAction 'promote-prod' isn't defined. Use an action id from Cuelight settings → Actions.
422invalid_inputnext[0]: followed by the input that failed

From GitHub Actions

The huseyinbuyukdere/cuelight-report action sends either kind of request in one step. It needs bash, curl and jq, which GitHub-hosted runners have.

Report a run. The callback URL and token default to the workflow inputs Cuelight sends:

- name: Hand back the next step
  if: always()
  uses: huseyinbuyukdere/cuelight-report@v1
  with:
    status: ${{ job.status }}
    message: Deployed ${{ github.sha }} to ${{ inputs.environment }}
    next: rollback-staging, promote-production

Offer a next step. Store the report URL and install key as repository secrets:

- name: Offer a preview deploy
  uses: huseyinbuyukdere/cuelight-report@v1
  env:
    CUELIGHT_REPORT_URL: ${{ secrets.CUELIGHT_REPORT_URL }}
  with:
    install-key: ${{ secrets.CUELIGHT_INSTALL_KEY }}
    issue-key: SHOP-1
    source: PR #${{ github.event.pull_request.number }}
    next: '[{"action":"deploy-preview","inputs":{"pr":"${{ github.event.pull_request.number }}"}}]'
InputDefaultWhat it does
statusrunning, success, failure or cancelled. Usually ${{ job.status }}. Not used for offers
messagePlain text shown on the work item
nextComma-separated action ids, or a JSON array with inputs
urlThis workflow runLink shown as "View run"
callback-urlThe cuelight_callback_url inputReport URL
tokenThe cuelight_token inputRun token
install-keyWhen set, sends an offer instead of a run report
issue-keyRequired for offers
sourceOffer label, like PR #12
expires-in-hours168How long the next steps stay
fail-on-errorfalseWhen false, a failed report logs a warning and the job goes on

The action has one output, http-status.

From curl

curl -X POST "$CUELIGHT_REPORT_URL" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $CUELIGHT_INSTALL_KEY" \
  -d '{"issueKey":"SHOP-1","source":"PR #12","next":[{"action":"deploy-preview","inputs":{"pr":"12"}}]}'

From n8n

Add an HTTP Request node. Create a Header Auth credential with the name Authorization and the value Bearer <install key>, then use these settings:

{
  "method": "POST",
  "url": "<your report URL>",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "sendBody": true,
  "specifyBody": "json",
  "jsonBody": "{\"issueKey\":\"{{ $json.issueKey }}\",\"source\":\"n8n\",\"next\":[{\"action\":\"deploy-staging\"}]}"
}

Limits

LimitValue
Body size16 KB
Message500 characters
Next steps per request and per work item5
Next step lifetime1 to 720 hours, default 168
Run token lifetime24 hours
Source label60 characters