Issues
Issue tracking and management
15 endpoints
Create a user-submitted issue
Request BodyCreateIssueRequest
projectrequiredstringtitlerequiredstringpriorityrequiredstringcriticalhighsuggestedbacklogseveritystringcriticalhighmediumlowinfocategorystringdescriptionstringfilePathstringlineNumberintegerfailureCodestring^(STR|SEM|PRA|EPI)-[A-Z]{3}/[CHMLI]$failureDomainstring- STR: Structural failures - SEM: Semantic failures - PRA: Pragmatic failures - EPI: Epistemic failures
STRSEMPRAEPIfailureModestringagentstringtypestringIssue type. Universal types: feature, bug, refactor, config, docs, infra, security, test, observation, deficiency, ambiguity. Domain-specific types (e.g., "omission", "interpretation" for legal) are also accepted and resolved by the API.
Responses
Response fields
dataobject/api/v1/issuescurl -X POST "https://api.uluops.ai/api/v1/issues" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"title": "Missing error handler in auth middleware",
"priority": "critical"
}'{
"data": {
"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"
}
}Search issues across projects
Parameters
querystringquerySearch text (optional — returns all issues if omitted)
projectsarrayqueryagentsarrayquerystatusstringqueryopencompleteddeferredwontfixmergedfalse-positiveallallprioritystringquerycriticalhighsuggestedbacklogallallseveritiesarrayqueryfailure_domainsarrayquerylimitintegerqueryMaximum number of results
Default:50Responses
Response fields
dataIssue[]countinteger/api/v1/issues/searchcurl -X GET "https://api.uluops.ai/api/v1/issues/search" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"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"
}
],
"count": 0
}Get issue by fingerprint
Parameters
fingerprintrequiredstringpathIssue fingerprint (SHA-256 hash, 16-64 chars)
projectrequiredstringqueryResponses
Response fields
dataobject/api/v1/issues/by-fingerprint/{fingerprint}curl -X GET "https://api.uluops.ai/api/v1/issues/by-fingerprint/a1b2c3d4e5f6g7h8?project=my-project" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"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"
}
}Update issue status by fingerprint
Parameters
fingerprintrequiredstringpathIssue fingerprint (SHA-256 hash, 16-64 chars)
projectrequiredstringqueryRequest BodyUpdateIssueStatusRequest
statusrequiredstringopencompleteddeferredwontfixmergedfalse-positiveobservationreasonstringResponses
Response fields
dataobject/api/v1/issues/by-fingerprint/{fingerprint}/statuscurl -X PATCH "https://api.uluops.ai/api/v1/issues/by-fingerprint/a1b2c3d4e5f6g7h8/status?project=my-project" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "open"
}'{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"fingerprint": "...",
"previousStatus": "...",
"newStatus": "...",
"updatedAt": "2026-01-15T10:30:00Z"
}
}Bulk update issue statuses
Request BodyBulkStatusUpdateRequest
projectrequiredstringupdatesrequiredobject[]Responses
Response fields
dataobject/api/v1/issues/bulk-statuscurl -X POST "https://api.uluops.ai/api/v1/issues/bulk-status" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "my-project",
"updates": [
{
"status": "open"
}
]
}'{
"data": {
"updated": 0,
"failed": 0
}
}List issues by project
Parameters
projectIdrequiredstringpathstatusstringqueryopencompleteddeferredwontfixmergedfalse-positiveallopenprioritystringquerycriticalhighsuggestedbacklogseveritystringquerycriticalhighmediumlowinfofailure_domainstringquerySTRSEMPRAEPIagentstringqueryFilter by agent name
include_resolvedbooleanquerylimitintegerqueryMaximum number of results
Default:50offsetintegerqueryNumber of results to skip
Default:0Responses
Response fields
dataIssue[]countinteger/api/v1/issues/project/{projectId}curl -X GET "https://api.uluops.ai/api/v1/issues/project/my-project" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"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"
}
],
"count": 0
}Get an issue
Parameters
idrequiredstringuuidpathIssue UUID
Responses
Response fields
dataobject/api/v1/issues/{id}curl -X GET "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"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"
}
}Edit issue fields
Parameters
idrequiredstringuuidpathIssue UUID
Request BodyEditIssueRequest
titlestringfilePathstringcategorystringseveritystringcriticalhighmediumlowinfofailureCodestring^(STR|SEM|PRA|EPI)-[A-Z]{3}/[CHMLI]$lineNumberintegerResponses
Response fields
dataobject/api/v1/issues/{id}curl -X PATCH "https://api.uluops.ai/api/v1/issues/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",
"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"
}
}Get full issue details with notes
Parameters
idrequiredstringuuidpathIssue UUID
include_occurrencesbooleanquerytrueinclude_relatedbooleanqueryfalseResponses
Response fields
dataobject/api/v1/issues/{id}/detailscurl -X GET "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/details" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"issue": {
"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"
},
"notes": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"issueId": "550e8400-e29b-41d4-a716-446655440000",
"content": "...",
"noteType": "context",
"createdBy": "...",
"createdAt": "2026-01-15T10:30:00Z"
}
],
"occurrences": [],
"related": [
{
"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"
}
]
}
}Get unified issue audit history (occurrences, status changes, notes)
Returns a merged audit history for an issue as a single timestamp- sorted event stream covering three sources: per-run occurrences, deliberate status transitions (and undo tombstones), and notes. Events are sorted by timestamp descending and capped at 1000 events post-merge. **BREAKING CHANGE** (live-tests T2 §3.1, F10): prior versions returned `{ issue, history: StatusHistory[] }` covering only status transitions, and the undo endpoint destroyed the row it reverted. The new envelope merges all three event sources and preserves the original row on undo via a tombstone with `transitionType: 'undo'` and `revertedChangeId` pointing at the change it reverts. Pre-migration rows (before migration 055) have `transitionType: null` and are semantically equivalent to `'change'`.
Parameters
idrequiredstringuuidpathIssue UUID
Responses
Response fields
datarequiredobject/api/v1/issues/{id}/historycurl -X GET "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/history" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"issueId": "550e8400-e29b-41d4-a716-446655440000",
"events": [],
"totalEvents": 0,
"truncated": true
}
}Update issue status
Parameters
idrequiredstringuuidpathIssue UUID
Request BodyUpdateIssueStatusRequest
statusrequiredstringopencompleteddeferredwontfixmergedfalse-positiveobservationreasonstringResponses
Response fields
dataobject/api/v1/issues/{id}/statuscurl -X PATCH "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/status" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "open"
}'{
"data": {
"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"
}
}Add a note to an issue
Parameters
idrequiredstringuuidpathIssue UUID
Request BodyAddNoteRequest
contentrequiredstringnoteTypestringcontextresolutionblockercreatedBystringResponses
Response fields
dataobject/api/v1/issues/{id}/notescurl -X POST "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/notes" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "name: example-agent\nversion: 1.0.0"
}'{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"issueId": "550e8400-e29b-41d4-a716-446655440000",
"content": "...",
"noteType": "context",
"createdBy": "...",
"createdAt": "2026-01-15T10:30:00Z"
}
}Restore a deleted issue
Parameters
idrequiredstringuuidpathIssue UUID
Responses
Response fields
dataobject/api/v1/issues/{id}/restorecurl -X POST "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/restore" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"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"
}
}Soft-delete an issue
Reversible soft-delete — sets the issue's `deletedAt` timestamp without removing the row. Restore via `POST /issues/{id}/restore`. System-key callers cannot use this endpoint (write operation; system keys are read-only on issue routes per the dual-auth contract).
Parameters
idrequiredstringuuidpathIssue UUID
Responses
/api/v1/issues/{id}/softcurl -X DELETE "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/soft" \
-H "Authorization: Bearer $ULUOPS_TOKEN"Undo last status change
Reverts the most recent status change on an issue and writes a tombstone row (`transitionType: 'undo'`, `revertedChangeId: <reverted-row-id>`) to the audit log. The original row is preserved so the timeline stays monotonic — see GET /issues/:id/history for the full envelope including tombstones. **Cannot undo an undo** (live-tests T2 §3.1 Bug B follow-up): when the most recent row is itself a tombstone, this endpoint returns 400 to prevent chained tombstones from silently bouncing the issue between statuses.
Parameters
idrequiredstringuuidpathIssue UUID
Responses
Response fields
dataobject/api/v1/issues/{id}/undocurl -X POST "https://api.uluops.ai/api/v1/issues/550e8400-e29b-41d4-a716-446655440000/undo" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"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"
}
}