Skip to main content

Classify with AI

POST/api/projects/{projectId}/changes/{changeId}/ai-classification
Signed-in member

If the AI call fails or returns something unusable, the change keeps the rule result, records aiStatus: FAILED with a safe message, and gets an AI classification failed review trigger. Nothing is retried automatically, and a worker that stops mid-call never asks again. A person can press Retry with AI in the Change Inbox, or call POST /api/projects/{projectId}/changes/{changeId}/ai-classification with the session and a CSRF token. The failure trigger stays, so a person still reviews the change. An Unknown change that was classified while no provider was configured, and that nobody has reviewed, can be sent the same way once one is.

Read more: Project contextSource: ChangeApiController#classifyWithAi(opens in new tab)

Path parameters​

NameTypeRequiredNotes
projectIdstring (uuid)Required
changeIdstring (uuid)Required

Response​

Success: 200

FieldTypeRequiredNotes
idstring (uuid)Optional
pullRequestNumberintegerOptional
titlestringOptional
descriptionstringOptional
authorLoginstringOptional
labelsarray of stringOptional
targetBranchstringOptional
mergeCommitShastringOptional
mergedAtstring (date-time)Optional
urlstringOptional
categorystringOptional
categoryNamestringOptional
categoryGroupenum CategoryGroupOptionalFEATUREFIXPERFORMANCEDOCUMENTATIONMAINTENANCEOTHER
breakingbooleanOptional
securitybooleanOptional
needsReviewbooleanOptional
reasonsarray of stringOptional
classificationSourceenum ClassificationSourceOptionalRULESAISUGGESTIONHUMAN
aiStatusenum AiStatusOptionalNOT_REQUESTEDSUCCEEDEDFAILED
aiModelstringOptional
aiFailurestringOptional
aiEligiblebooleanOptional
reviewedBystring (uuid)Optional
reviewerNamestringOptional
reviewedAtstring (date-time)Optional
processingStatusenum ProcessingStatusOptionalPROCESSINGCOMPLETED
changedFileStatusenum ChangedFileStatusOptionalCOLLECTEDUNAVAILABLENOT_SUPPORTED
linkedContextStatusenum LinkedContextStatusOptionalNOT_SUPPORTEDNOT_CONFIGUREDNOT_FOUNDPARTIALUNAVAILABLECOLLECTED
linkedIssuesarray of LinkedIssueOptional
linkedIssues[].keystringOptional
linkedIssues[].titlestringOptional
linkedIssues[].descriptionstringOptional
linkedIssues[].typestringOptional
linkedIssues[].statusstringOptional
linkedIssues[].urlstringOptional
linkedIssues[].trackerstringOptional
linkedIssues[].statusCategorystringOptional
changedFilesarray of ChangedFileOptional
changedFiles[].pathstringOptional
changedFiles[].previousPathstringOptional
changedFiles[].kindenum ChangedFileKindOptionalADDEDMODIFIEDREMOVEDRENAMEDOTHER
reviewTriggersarray of ReviewTriggerOptional
reviewTriggers[].typeenum ReviewTriggerTypeOptionalSENSITIVE_PATHCHANGED_FILES_UNAVAILABLESENSITIVE_KEYWORDCLASSIFIER_FALLBACKCATEGORY_SUGGESTION_PENDINGCONTEXT_INSUFFICIENTLINKED_CONTEXT_UNAVAILABLEDUPLICATE_CANDIDATEMIGRATION_KIND_MISMATCH
reviewTriggers[].detailstringOptional
neutralSummaryNeutralSummaryOptional
neutralSummary.whatChangedstringOptional
neutralSummary.whyChangedstringOptional
neutralSummary.technicalDetailstringOptional
neutralSummary.migrationStepstringOptional
neutralSummary.migrationKindenum MigrationKindOptionalNONEREQUIREDCONDITIONALRECOMMENDEDUNSPECIFIED
neutralSummary.limitationsstringOptional
contentLanguagestringOptional
aiProviderenum AiProviderOptionalOPENAIANTHROPICDEEPSEEK
audienceNarrativeDetailsmap of AudienceNarrativeOptional
summaryEditorNamestringOptional
summaryEditedAtstring (date-time)Optional
contextContextAssessmentOptional
context.scoreintegerOptional
context.statusenum ContextStatusOptionalSUFFICIENTINSUFFICIENT
context.reasonsarray of stringOptional
sourceIdstring (uuid)Optional
originenum ChangeOriginOptionalWEBHOOKIMPORT
sourceTypeenum SourceTypeOptionalGITHUBGITLABLINEARJIRA
exclusionChangeExclusionOptional
exclusion.excludedBystring (uuid)Optional
exclusion.excluderNamestringOptional
exclusion.excludedAtstring (date-time)Optional
exclusion.reasonstringOptional

Errors​

StatusCodeApplies to
400validation_faileda field is missing or out of rangeAny endpoint
400invalid_parametera path or query parameter is missing or does not convert, such as an ID that is not a UUIDAny endpoint
401authentication_requiredno sessionAny endpoint
403access_deniedan administrator endpoint, or a missing or stale CSRF tokenAny endpoint
404not_foundno such addressAny endpoint
405method_not_allowedthe address does not take that methodAny endpoint
415unsupported_media_typethe address does not read a body of that typeAny endpoint
500internal_errora fault ReleaseFlow did not foresee; the body never carries the exception behind itAny endpoint
400invalid_change_filterChanges area
400invalid_change_reviewChanges area
400invalid_sensitive_pathsChanges area
404change_not_foundChanges area
404duplicate_candidate_not_foundChanges area
409change_processingChanges area
409change_not_eligible_for_aiChanges area
409duplicate_candidate_decidedChanges area
409change_excludedChanges area
409change_in_releaseChanges area
502ai_classification_failedChanges area
503ai_classification_unavailableChanges area
404category_not_foundCategories area
404category_suggestion_not_foundCategories area
409category_code_takenCategories area
409category_systemCategories area
409category_suggestion_decidedCategories area

Request

bash
# 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/ai-classification" \
-b cookies.txt -c cookies.txt \
-H "$CSRF_HEADER: $CSRF_TOKEN"

Response

200

Example

{
  "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>"
  }
}