Runs
Validation run management
13 endpoints
Save features list (create validation run)
Request BodySaveFeaturesListRequest
projectrequiredstringProject name
workflow_typerequiredstringagentsrequiredAgentInput[]recommendationsrequiredRecommendationInput[]timestampstringdate-timeraw_markdownstringnullablesummaryobjectidempotency_keystringnullabledefinition_typestringnullabledefinition_namestringnullabledefinition_versionstringnullabledefinition_hashstringnullabledefinition_idstringuuidnullableRegistry definition UUID — enables direct identity linkage between tracker and registry
analysis_recordsAnalysisRecordInput[]analysis_summaryobjectResponses
Response fields
dataobject/api/v1/runscurl -X POST "https://api.uluops.ai/api/v1/runs" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"workflow_type": "ship",
"agents": [
{
"name": "my-project",
"decision": "example-value"
}
],
"recommendations": [
{
"agent": "code-validator",
"title": "Missing error handler in auth middleware",
"priority": "critical"
}
]
}'{
"data": {
"run": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
},
"agents": [],
"correlation": {
"newIssues": 0,
"recurringIssues": 0,
"regressions": 0,
"observed": 0,
"duplicatesSkipped": 0,
"crossAgentMatches": [
{
"issueId": "550e8400-e29b-41d4-a716-446655440000",
"title": "...",
"agent": "...",
"crossAgentMatches": []
}
]
},
"deduplicated": true
}
}Preview save_run without saving
Request BodySaveFeaturesListRequest
projectrequiredstringProject name
workflow_typerequiredstringagentsrequiredAgentInput[]recommendationsrequiredRecommendationInput[]timestampstringdate-timeraw_markdownstringnullablesummaryobjectidempotency_keystringnullabledefinition_typestringnullabledefinition_namestringnullabledefinition_versionstringnullabledefinition_hashstringnullabledefinition_idstringuuidnullableRegistry definition UUID — enables direct identity linkage between tracker and registry
analysis_recordsAnalysisRecordInput[]analysis_summaryobjectResponses
Response fields
dataobject/api/v1/runs/validatecurl -X POST "https://api.uluops.ai/api/v1/runs/validate" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"workflow_type": "ship",
"agents": [
{
"name": "my-project",
"decision": "example-value"
}
],
"recommendations": [
{
"agent": "code-validator",
"title": "Missing error handler in auth middleware",
"priority": "critical"
}
]
}'{
"data": {
"wouldCreate": 0,
"wouldUpdate": 0,
"wouldRegress": 0,
"wouldObserve": 0,
"validationErrors": [],
"preview": {
"newIssues": [
{
"title": "...",
"agent": "..."
}
],
"recurringIssues": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "...",
"timesSeen": 0
}
],
"regressions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "...",
"lastStatus": "..."
}
],
"observations": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"title": "..."
}
]
}
}
}Archive old runs
Request BodyArchiveRunsRequest
projectrequiredstringbefore_run_numberintegerbefore_datestringdate-timekeep_lastintegerreasonstringResponses
Response fields
dataobject/api/v1/runs/archivecurl -X POST "https://api.uluops.ai/api/v1/runs/archive" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project"
}'{
"data": {
"archived": 0
}
}Update run by project and run number
Request BodyUpdateRunRequest
projectrequiredstringrun_numberrequiredintegerworkflow_typestringall_gates_passedbooleanaverage_scorenumberraw_markdownstringagentsAgentTokenUpdate[]recommendationsRecommendationInput[]analysis_recordsUpdateAnalysisRecordInput[]analysis_summaryobjectrecord_write_modestringRecords-only write mode (spec §3.2, 1b; default replace). replace = set-replacement within each named agent (omission retires); merge = upsert on (agent_name, record_id) — matched keys superseded, unmatched keys appended, nothing retired. Summaries have no mode (always per-agent replace). Unknown values 400; sending the mode without analysis_records 400.
replacemergeResponses
Response fields
dataobjectanalysisWriteobjectAdditive block on analysis-bearing update responses (replacement-semantics spec §3.9), serialized camelCase beside the data envelope. New SDKs assert recordMode equals the mode they sent, converting silent version skew into a loud error; old consumers strip the block harmlessly.
/api/v1/runs/updatecurl -X PATCH "https://api.uluops.ai/api/v1/runs/update" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"run_number": 5
}'{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
},
"analysisWrite": {
"recordMode": "replace",
"supersededRecords": 0,
"supersededSummaries": 0,
"createdRecords": 0,
"createdSummaries": 0
}
}Preview an analysis-bearing update by project and run number (read-only)
By-project sibling of POST /runs/{id}/update-preview. Accepts analysis concerns only — a body carrying agents, recommendations, or run metadata fields is a 400, never a silent strip. Shares its resolution and plan computation with the write path; nothing is written.
Request Body
projectrequiredstringrun_numberrequiredintegeranalysis_recordsUpdateAnalysisRecordInput[]analysis_summaryobjectrecord_write_modestringRecords-only write mode (spec §3.2, 1b; default replace). replace = set-replacement within each named agent (omission retires); merge = upsert on (agent_name, record_id) — matched keys superseded, unmatched keys appended, nothing retired. Summaries have no mode (always per-agent replace). Unknown values 400; sending the mode without analysis_records 400.
replacemergeResponses
Response fields
datarequiredobject/api/v1/runs/update-previewcurl -X POST "https://api.uluops.ai/api/v1/runs/update-preview" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"run_number": 5
}'{
"data": {
"preview": "true",
"recordMode": "replace",
"byAgent": "..."
}
}Compare two runs
Parameters
projectrequiredstringquerybase_runrequiredintegerquerycompare_runrequiredintegerqueryworkflow_typestringqueryResponses
Response fields
dataobject/api/v1/runs/diffcurl -X GET "https://api.uluops.ai/api/v1/runs/diff?project=my-project&base_run=1&compare_run=1" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"fixed": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"fingerprint": "...",
"semanticFingerprint": "...",
"title": "...",
"status": "open",
"priority": "critical",
"severity": "critical",
"failureCode": "...",
"failureDomain": "STR",
"failureMode": "...",
"failureSeverityCode": "C",
"category": "...",
"agent": "...",
"type": "...",
"filePath": "...",
"lineNumber": 0,
"timesSeen": 0,
"firstSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"lastSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"resolvedAt": "2026-01-15T10:30:00Z",
"resolutionRunId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"new": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"fingerprint": "...",
"semanticFingerprint": "...",
"title": "...",
"status": "open",
"priority": "critical",
"severity": "critical",
"failureCode": "...",
"failureDomain": "STR",
"failureMode": "...",
"failureSeverityCode": "C",
"category": "...",
"agent": "...",
"type": "...",
"filePath": "...",
"lineNumber": 0,
"timesSeen": 0,
"firstSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"lastSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"resolvedAt": "2026-01-15T10:30:00Z",
"resolutionRunId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"unchanged": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"fingerprint": "...",
"semanticFingerprint": "...",
"title": "...",
"status": "open",
"priority": "critical",
"severity": "critical",
"failureCode": "...",
"failureDomain": "STR",
"failureMode": "...",
"failureSeverityCode": "C",
"category": "...",
"agent": "...",
"type": "...",
"filePath": "...",
"lineNumber": 0,
"timesSeen": 0,
"firstSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"lastSeenRunId": "550e8400-e29b-41d4-a716-446655440000",
"resolvedAt": "2026-01-15T10:30:00Z",
"resolutionRunId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"agentChanges": []
}
}List runs for a project
Parameters
projectIdrequiredstringpathworkflow_typestringqueryshowArchivedbooleanqueryInclude archived runs in the result set (default false)
Default:falselimitintegerqueryMaximum number of results
Default:50offsetintegerqueryNumber of results to skip
Default:0Responses
Response fields
dataRun[]totalintegerTotal matching runs across all pages
countintegerNumber of runs in the current response (length of data)
/api/v1/runs/project/{projectId}curl -X GET "https://api.uluops.ai/api/v1/runs/project/my-project" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"total": 0,
"count": 0
}Get latest run for a project
Returns the latest VALIDATION run. The synthetic per-project 'manual' run (the anchor row for issues logged outside a validation run) is excluded unless workflow_type=manual is passed explicitly — it executed no gates and must not answer "did the latest run pass?" (T8).
Parameters
projectIdrequiredstringpathworkflow_typestringqueryResponses
Response fields
dataobject/api/v1/runs/project/{projectId}/latestcurl -X GET "https://api.uluops.ai/api/v1/runs/project/my-project/latest" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
}Get run details for a project
Parameters
projectIdrequiredstringpathrun_numberintegerqueryworkflow_typestringqueryResponses
Response fields
dataobject/api/v1/runs/project/{projectId}/detailscurl -X GET "https://api.uluops.ai/api/v1/runs/project/my-project/details" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"run": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
},
"agents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"runId": "550e8400-e29b-41d4-a716-446655440000",
"name": "...",
"definitionVersion": "...",
"score": 0,
"maxScore": 0,
"decision": "...",
"summary": "...",
"model": "...",
"inputTokens": 0,
"outputTokens": 0,
"cacheCreationTokens": 0,
"cacheReadTokens": 0,
"totalEffectiveTokens": 0,
"durationMs": 0,
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
],
"recommendations": [
{
"issueId": "550e8400-e29b-41d4-a716-446655440000",
"title": "...",
"priority": "critical",
"status": "new",
"issueStatus": "open",
"agent": "..."
}
]
}
}Get a run by ID
Parameters
idrequiredstringuuidpathRun UUID
Responses
Response fields
dataobject/api/v1/runs/{id}curl -X GET "https://api.uluops.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
}
}Update a run
Parameters
idrequiredstringuuidpathRun UUID
Request Body
all_gates_passedbooleanaverage_scorenumberraw_markdownstringworkflow_typestringarchived_atstringdate-timenullableISO 8601 timestamp marking the run archived. Null clears the archive.
archived_reasonstringnullableOptional human-readable reason for archiving (max 500 chars).
agentsAgentTokenUpdate[]recommendationsRecommendationInput[]analysis_recordsUpdateAnalysisRecordInput[]analysis_summaryobjectrecord_write_modestringRecords-only write mode (spec §3.2, 1b; default replace). replace = set-replacement within each named agent (omission retires); merge = upsert on (agent_name, record_id) — matched keys superseded, unmatched keys appended, nothing retired. Summaries have no mode (always per-agent replace). Unknown values 400; sending the mode without analysis_records 400.
replacemergeResponses
Response fields
dataobjectanalysisWriteobjectAdditive block on analysis-bearing update responses (replacement-semantics spec §3.9), serialized camelCase beside the data envelope. New SDKs assert recordMode equals the mode they sent, converting silent version skew into a loud error; old consumers strip the block harmlessly.
/api/v1/runs/{id}curl -X PATCH "https://api.uluops.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"projectId": "550e8400-e29b-41d4-a716-446655440000",
"runNumber": 0,
"workflowType": "...",
"timestamp": "2026-01-15T10:30:00Z",
"allGatesPassed": true,
"averageScore": 0,
"rawMarkdown": "...",
"archivedAt": "2026-01-15T10:30:00Z",
"archiveReason": "...",
"idempotencyKey": "...",
"payloadHash": "...",
"definitionType": "...",
"definitionName": "...",
"definitionVersion": "...",
"definitionHash": "...",
"definitionId": "550e8400-e29b-41d4-a716-446655440000",
"registrySyncedAt": "2026-01-15T10:30:00Z",
"mergedFromProjectId": "550e8400-e29b-41d4-a716-446655440000",
"mergedFromRunNumber": 0,
"mergedFromIdempotencyKey": "...",
"authorId": "550e8400-e29b-41d4-a716-446655440000",
"projectSlug": "...",
"orgSlug": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z"
},
"analysisWrite": {
"recordMode": "replace",
"supersededRecords": 0,
"supersededSummaries": 0,
"createdRecords": 0,
"createdSummaries": 0
}
}Delete a run
Parameters
idrequiredstringuuidpathRun UUID
X-Confirm-DeleterequiredstringheaderMust match the run ID exactly for confirmation
Responses
Response fields
dataobject/api/v1/runs/{id}curl -X DELETE "https://api.uluops.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "X-Confirm-Delete: true"{
"data": {
"deleted": true
}
}Preview an analysis-bearing update without writing (read-only)
Returns, per agent named in the payload (after defaulting from the run's stored definition_name), what a PATCH with this analysis payload would supersede, create, and retire by omission. Accepts analysis concerns only — a body carrying agents, recommendations, or run metadata fields is a 400, never a silent strip. Deliberately a separate endpoint rather than a dry-run flag on PATCH: a flag sent to an older API would be stripped and the write would execute; this endpoint on an old API 404s.
Parameters
idrequiredstringuuidpathRun UUID
Request Body
analysis_recordsUpdateAnalysisRecordInput[]analysis_summaryobjectrecord_write_modestringRecords-only write mode (spec §3.2, 1b; default replace). replace = set-replacement within each named agent (omission retires); merge = upsert on (agent_name, record_id) — matched keys superseded, unmatched keys appended, nothing retired. Summaries have no mode (always per-agent replace). Unknown values 400; sending the mode without analysis_records 400.
replacemergeResponses
Response fields
datarequiredobject/api/v1/runs/{id}/update-previewcurl -X POST "https://api.uluops.ai/api/v1/runs/550e8400-e29b-41d4-a716-446655440000/update-preview" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"preview": "true",
"recordMode": "replace",
"byAgent": "..."
}
}