Request missing narratives
/api/projects/{projectId}/changes/{changeId}/missing-narrativesBring back makes it active again, and the page says who brought it back and when. A change the AI classified while the audience was retired has no narrative for it; its note still includes the change under the neutral headline (whatChanged), with no narrative, and never leaves it out. The release's Review tab lists those changes under Changes with no narrative for an audience, so a person writes the narrative with Edit summary, or asks the AI for only the missing narratives. The button shows the request's rough size in tokens, worked out from its text without sending anything; the answer adds those narratives and changes nothing else about the change. Through the API, a release in review or approved lists them as missingNarratives (changeId, reference, title, audienceNames, estimatedTokens), and any member asks the AI with POST /api/projects/{projectId}/changes/{changeId}/missing-narratives, which answers the change. A change the AI did not classify is refused with 409 change_not_eligible_for_ai; without AI the answer is 503 ai_classification_unavailable, and a failed request 502 ai_classification_failed, which records nothing.
Path parameters
| Name | Type | Required | Notes |
|---|---|---|---|
projectId | string (uuid) | Required | |
changeId | string (uuid) | Required |
Response
Success: 200
| Field | Type | Required | Notes |
|---|---|---|---|
id | string (uuid) | Optional | |
pullRequestNumber | integer | Optional | |
title | string | Optional | |
description | string | Optional | |
authorLogin | string | Optional | |
labels | array of string | Optional | |
targetBranch | string | Optional | |
mergeCommitSha | string | Optional | |
mergedAt | string (date-time) | Optional | |
url | string | Optional | |
category | string | Optional | |
categoryName | string | Optional | |
categoryGroup | enum CategoryGroup | Optional | FEATUREFIXPERFORMANCEDOCUMENTATIONMAINTENANCEOTHER |
breaking | boolean | Optional | |
security | boolean | Optional | |
needsReview | boolean | Optional | |
reasons | array of string | Optional | |
classificationSource | enum ClassificationSource | Optional | RULESAISUGGESTIONHUMAN |
aiStatus | enum AiStatus | Optional | NOT_REQUESTEDSUCCEEDEDFAILED |
aiModel | string | Optional | |
aiFailure | string | Optional | |
aiEligible | boolean | Optional | |
reviewedBy | string (uuid) | Optional | |
reviewerName | string | Optional | |
reviewedAt | string (date-time) | Optional | |
processingStatus | enum ProcessingStatus | Optional | PROCESSINGCOMPLETED |
changedFileStatus | enum ChangedFileStatus | Optional | COLLECTEDUNAVAILABLENOT_SUPPORTED |
linkedContextStatus | enum LinkedContextStatus | Optional | NOT_SUPPORTEDNOT_CONFIGUREDNOT_FOUNDPARTIALUNAVAILABLECOLLECTED |
linkedIssues | array of LinkedIssue | Optional | |
linkedIssues[].key | string | Optional | |
linkedIssues[].title | string | Optional | |
linkedIssues[].description | string | Optional | |
linkedIssues[].type | string | Optional | |
linkedIssues[].status | string | Optional | |
linkedIssues[].url | string | Optional | |
linkedIssues[].tracker | string | Optional | |
linkedIssues[].statusCategory | string | Optional | |
changedFiles | array of ChangedFile | Optional | |
changedFiles[].path | string | Optional | |
changedFiles[].previousPath | string | Optional | |
changedFiles[].kind | enum ChangedFileKind | Optional | ADDEDMODIFIEDREMOVEDRENAMEDOTHER |
reviewTriggers | array of ReviewTrigger | Optional | |
reviewTriggers[].type | enum ReviewTriggerType | Optional | SENSITIVE_PATHCHANGED_FILES_UNAVAILABLESENSITIVE_KEYWORDCLASSIFIER_FALLBACKCATEGORY_SUGGESTION_PENDINGCONTEXT_INSUFFICIENTLINKED_CONTEXT_UNAVAILABLEDUPLICATE_CANDIDATEMIGRATION_KIND_MISMATCH |
reviewTriggers[].detail | string | Optional | |
neutralSummary | NeutralSummary | Optional | |
neutralSummary.whatChanged | string | Optional | |
neutralSummary.whyChanged | string | Optional | |
neutralSummary.technicalDetail | string | Optional | |
neutralSummary.migrationStep | string | Optional | |
neutralSummary.migrationKind | enum MigrationKind | Optional | NONEREQUIREDCONDITIONALRECOMMENDEDUNSPECIFIED |
neutralSummary.limitations | string | Optional | |
contentLanguage | string | Optional | |
aiProvider | enum AiProvider | Optional | OPENAIANTHROPICDEEPSEEK |
audienceNarrativeDetails | map of AudienceNarrative | Optional | |
summaryEditorName | string | Optional | |
summaryEditedAt | string (date-time) | Optional | |
context | ContextAssessment | Optional | |
context.score | integer | Optional | |
context.status | enum ContextStatus | Optional | SUFFICIENTINSUFFICIENT |
context.reasons | array of string | Optional | |
sourceId | string (uuid) | Optional | |
origin | enum ChangeOrigin | Optional | WEBHOOKIMPORT |
sourceType | enum SourceType | Optional | GITHUBGITLABLINEARJIRA |
exclusion | ChangeExclusion | Optional | |
exclusion.excludedBy | string (uuid) | Optional | |
exclusion.excluderName | string | Optional | |
exclusion.excludedAt | string (date-time) | Optional | |
exclusion.reason | string | Optional |
Errors
| Status | Code | Applies to |
|---|---|---|
400 | validation_faileda field is missing or out of range | Any endpoint |
400 | invalid_parametera path or query parameter is missing or does not convert, such as an ID that is not a UUID | Any endpoint |
401 | authentication_requiredno session | Any endpoint |
403 | access_deniedan administrator endpoint, or a missing or stale CSRF token | Any endpoint |
404 | not_foundno such address | Any endpoint |
405 | method_not_allowedthe address does not take that method | Any endpoint |
415 | unsupported_media_typethe address does not read a body of that type | Any endpoint |
500 | internal_errora fault ReleaseFlow did not foresee; the body never carries the exception behind it | Any endpoint |
400 | invalid_change_filter | Changes area |
400 | invalid_change_review | Changes area |
400 | invalid_sensitive_paths | Changes area |
404 | change_not_found | Changes area |
404 | duplicate_candidate_not_found | Changes area |
409 | change_processing | Changes area |
409 | change_not_eligible_for_ai | Changes area |
409 | duplicate_candidate_decided | Changes area |
409 | change_excluded | Changes area |
409 | change_in_release | Changes area |
502 | ai_classification_failed | Changes area |
503 | ai_classification_unavailable | Changes area |
404 | category_not_found | Categories area |
404 | category_suggestion_not_found | Categories area |
409 | category_code_taken | Categories area |
409 | category_system | Categories area |
409 | category_suggestion_decided | Categories area |
Request
# Sign in first and keep the session cookie in cookies.txt (see Sessions and CSRF).
# CSRF_HEADER and CSRF_TOKEN are the headerName and token GET /api/csrf returned.
curl -X POST "http://localhost:8080/api/projects/$PROJECT_ID/changes/$CHANGE_ID/missing-narratives" \
-b cookies.txt -c cookies.txt \
-H "$CSRF_HEADER: $CSRF_TOKEN"
Response
200Example
{
"id": "<uuid>",
"pullRequestNumber": 0,
"title": "<string>",
"description": "<string>",
"authorLogin": "<string>",
"labels": [
"<string>"
],
"targetBranch": "<string>",
"mergeCommitSha": "<string>",
"mergedAt": "<date-time>",
"url": "<string>",
"category": "<string>",
"categoryName": "<string>",
"categoryGroup": "FEATURE",
"breaking": false,
"security": false,
"needsReview": false,
"reasons": [
"<string>"
],
"classificationSource": "RULES",
"aiStatus": "NOT_REQUESTED",
"aiModel": "<string>",
"aiFailure": "<string>",
"aiEligible": false,
"reviewedBy": "<uuid>",
"reviewerName": "<string>",
"reviewedAt": "<date-time>",
"processingStatus": "PROCESSING",
"changedFileStatus": "COLLECTED",
"linkedContextStatus": "NOT_SUPPORTED",
"linkedIssues": [
{
"key": "<string>",
"title": "<string>",
"description": "<string>",
"type": "<string>",
"status": "<string>",
"url": "<string>",
"tracker": "<string>",
"statusCategory": "<string>"
}
],
"changedFiles": [
{
"path": "<string>",
"previousPath": "<string>",
"kind": "ADDED"
}
],
"reviewTriggers": [
{
"type": "SENSITIVE_PATH",
"detail": "<string>"
}
],
"neutralSummary": {
"whatChanged": "<string>",
"whyChanged": "<string>",
"technicalDetail": "<string>",
"migrationStep": "<string>",
"migrationKind": "NONE",
"limitations": "<string>"
},
"contentLanguage": "<string>",
"aiProvider": "OPENAI",
"audienceNarrativeDetails": {
"<key>": {
"relevance": "NONE",
"headline": "<string>",
"body": "<string>"
}
},
"summaryEditorName": "<string>",
"summaryEditedAt": "<date-time>",
"context": {
"score": 0,
"status": "SUFFICIENT",
"reasons": [
"<string>"
]
},
"sourceId": "<uuid>",
"origin": "WEBHOOK",
"sourceType": "GITHUB",
"exclusion": {
"excludedBy": "<uuid>",
"excluderName": "<string>",
"excludedAt": "<date-time>",
"reason": "<string>"
}
}