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 report | Offer | |
|---|---|---|
| For | A workflow Cuelight started | Anything else |
| Credential | Run token in the body as token | Install key in Authorization: Bearer <key> |
| Where it comes from | The cuelight_token workflow input | Cuelight settings → Reporting |
| Lifetime | 24 hours from the press | Until an admin regenerates it |
| Can | Update that run and leave next steps | Leave 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
}| Field | Required | Rules |
|---|---|---|
token | Yes | The cuelight_token input, unchanged |
status | Yes | running, success, failure or cancelled |
message | Plain text, up to 500 characters. Never rendered as HTML | |
url | Must start with https://github.com/. Shown as "View run" | |
next | Up to 5 steps. Each action must be an action id you've defined | |
expiresInHours | 1 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
}| Field | Required | Rules |
|---|---|---|
issueKey | Yes | A work item key like SHOP-1 |
next | Yes | 1 to 5 steps |
source | Up to 60 characters. Shown as "Suggested by PR #12" | |
message | Plain text, up to 500 characters | |
expiresInHours | 1 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."
}
}| Status | Code | Message |
|---|---|---|
| 400 | invalid_content_type | Send Content-Type: application/json. |
| 400 | invalid_json | The body isn't valid JSON. |
| 400 | invalid_payload | The body must be a JSON object, or the field that failed and why |
| 401 | missing_token | Send the run token in "token", or an install key in the Authorization header. |
| 401 | invalid_token | The run token is invalid. Pass the cuelight_token input of this run unchanged, from the same Jira site. |
| 401 | expired_token | The run token has expired. Tokens are valid for 24 hours. |
| 401 | invalid_install_key | The install key is missing or invalid. Copy it from Cuelight settings → Reporting. |
| 404 | run_not_found | This run doesn't exist anymore. |
| 404 | issue_not_found | Work item SHOP-1 wasn't found. |
| 405 | method_not_allowed | Use POST. |
| 409 | run_final | This run already finished with status 'success'. |
| 413 | too_large | The body must be 16 KB or smaller. |
| 422 | unknown_action | Action 'promote-prod' isn't defined. Use an action id from Cuelight settings → Actions. |
| 422 | invalid_input | next[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-productionOffer 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 }}"}}]'| Input | Default | What it does |
|---|---|---|
status | running, success, failure or cancelled. Usually ${{ job.status }}. Not used for offers | |
message | Plain text shown on the work item | |
next | Comma-separated action ids, or a JSON array with inputs | |
url | This workflow run | Link shown as "View run" |
callback-url | The cuelight_callback_url input | Report URL |
token | The cuelight_token input | Run token |
install-key | When set, sends an offer instead of a run report | |
issue-key | Required for offers | |
source | Offer label, like PR #12 | |
expires-in-hours | 168 | How long the next steps stay |
fail-on-error | false | When 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
| Limit | Value |
|---|---|
| Body size | 16 KB |
| Message | 500 characters |
| Next steps per request and per work item | 5 |
| Next step lifetime | 1 to 720 hours, default 168 |
| Run token lifetime | 24 hours |
| Source label | 60 characters |