API reference

This reference is generated from api/openapi/public-v1.yaml (OpenAPI 3.1.1, API version 1.1.0). It contains exactly 13 operations.

The contract’s declared server is http://127.0.0.1:8080. Use the deployment base URL supplied to you. Every operation uses an HTTP bearer service credential.

Scopes used by this API: upload:create, work:read, work:create, work:guide, approval:read, approval:resolve, artifact:read.

The OpenAPI document is authoritative. Do not infer other public endpoints from the application or internal APIs.

Operations

Method	Path	Operation ID	Scope
POST	/api/v1/uploads	createInputUpload	upload:create
GET	/api/v1/uploads/{id}	getInputUpload	upload:create
POST	/api/v1/uploads/{id}/processing/retry	retryInputUploadProcessing	upload:create
GET	/api/v1/work	listWork	work:read
POST	/api/v1/work	createWork	work:create
GET	/api/v1/work/{id}	getWork	work:read
GET	/api/v1/work/{id}/events	streamWorkEvents	work:read
GET	/api/v1/work/{id}/attention	listWorkAttention	work:guide
POST	/api/v1/work/{id}/attention/{attention_id}/resolve	resolveWorkAttention	work:guide
GET	/api/v1/work/{id}/approvals	listWorkApprovals	approval:read
POST	/api/v1/work/{id}/approvals/{approval_id}/resolve	resolveWorkApproval	approval:resolve
GET	/api/v1/work/{id}/artifacts	listWorkArtifacts	artifact:read
GET	/api/v1/work/{id}/artifacts/{artifact_id}/content	downloadWorkArtifact	artifact:read

POST /api/v1/uploads

Upload a bounded Work input

• Operation ID: createInputUpload
• Required scope: upload:create
• Tag: Uploads

Parameters

Name	In	Required	Type	Details
Idempotency-Key	header	Yes	string	Caller-selected key. An exact retry returns the original result; reusing the key with different input returns IDEMPOTENCY_CONFLICT. Minimum length 1. Maximum length 255

Request body

Required.

Content type	Schema
application/json	CreateInputUploadRequest

Responses

Status	Meaning	Body	Headers
200	An exact idempotent retry returned the original upload.	application/json · InputUpload	Idempotent-Replayed
201	The immutable input is ready to attach to Work.	application/json · InputUpload	—
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
422	The active organization data policy blocked the input, Work objective, or Artifact download at its governed boundary.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/uploads/{id}

Read an input upload and its scan state

Poll after upload until status is ready (attachable) or failed. processing_state and failure_code explain a failed scan.

• Operation ID: getInputUpload
• Required scope: upload:create
• Tag: Uploads

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1

Responses

Status	Meaning	Body	Headers
200	The upload created by this service account.	application/json · InputUpload	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

POST /api/v1/uploads/{id}/processing/retry

Retry a failed upload scan

Queues a new scan for an upload whose processing_state is scan_failed (for example failure_code stale_signatures).

• Operation ID: retryInputUploadProcessing
• Required scope: upload:create
• Tag: Uploads

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
Idempotency-Key	header	Yes	string	Caller-selected key. An exact retry returns the original result; reusing the key with different input returns IDEMPOTENCY_CONFLICT. Minimum length 1. Maximum length 255

Responses

Status	Meaning	Body	Headers
202	A new scan attempt was queued.	application/json · InputUpload	—
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work

List Work

Lists Work created by the authenticated service account, newest first. When next_cursor is present, pass it as cursor for the next page.

• Operation ID: listWork
• Required scope: work:read
• Tag: Work

Parameters

Name	In	Required	Type	Details
status	query	No	WorkStatus	—
limit	query	No	integer	Page size. Default 50. Minimum 1. Maximum 100
cursor	query	No	string	Opaque next_cursor from the previous page.

Responses

Status	Meaning	Body	Headers
200	The visible Work list.	application/json · WorkList	—
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

POST /api/v1/work

Create Work

Creates ordinary Work for the human owner of the authenticated service account. Bounded staged inputs are referenced by input_upload_ids; inline attachments are not accepted by this public operation.

• Operation ID: createWork
• Required scope: work:create
• Tag: Work

Parameters

Name	In	Required	Type	Details
Idempotency-Key	header	Yes	string	Caller-selected key. An exact retry returns the original result; reusing the key with different input returns IDEMPOTENCY_CONFLICT. Minimum length 1. Maximum length 255

Request body

Required.

Content type	Schema
application/json	CreateWorkRequest

Responses

Status	Meaning	Body	Headers
200	An exact idempotent retry returned the original Work.	application/json · Work	ETag, Location, Idempotent-Replayed
201	Work was created.	application/json · Work	ETag, Location
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
422	The active organization data policy blocked the input, Work objective, or Artifact download at its governed boundary.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit
503	Execution admission currently has no capacity.	application/problem+json · Problem	Retry-After

GET /api/v1/work/{id}

Get Work

Reads one Work created by the authenticated service account. Unknown, cross-tenant, and otherwise concealed Work return the same not-found problem.

• Operation ID: getWork
• Required scope: work:read
• Tag: Work

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1

Responses

Status	Meaning	Body	Headers
200	The requested Work.	application/json · Work	ETag
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work/{id}/events

Stream Work activity

Server-sent events for one Work created by the authenticated service account. Each event has id (the event sequence), event (the event type) and data (the JSON event). Resume with Last-Event-ID or the after query parameter; only later events are sent. A : heartbeat comment is sent every 15 seconds, and the credential is re-checked at each heartbeat, so a revoked credential loses the stream within one heartbeat. Each credential may hold a bounded number of open streams.

• Operation ID: streamWorkEvents
• Required scope: work:read
• Tag: Work

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
after	query	No	integer (int64)	Send only events with a greater sequence. Minimum 0
Last-Event-ID	header	No	integer (int64)	Used when the after query parameter is absent. Minimum 0

Responses

Status	Meaning	Body	Headers
200	The Work activity event stream.	text/event-stream · string	—
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work/{id}/attention

List current Needs You items for Work

• Operation ID: listWorkAttention
• Required scope: work:guide
• Tag: Work

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1

Responses

Status	Meaning	Body	Headers
200	Current open attention owned by the accountable Work owner.	application/json · AttentionList	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

POST /api/v1/work/{id}/attention/{attention_id}/resolve

Resolve a clarification Needs You item

• Operation ID: resolveWorkAttention
• Required scope: work:guide
• Tag: Work

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
attention_id	path	Yes	string	Minimum length 1
If-Match	header	Yes	string	Strong integer version tag returned by the current resource. Minimum length 1
Idempotency-Key	header	Yes	string	Caller-selected key. An exact retry returns the original result; reusing the key with different input returns IDEMPOTENCY_CONFLICT. Minimum length 1. Maximum length 255

Request body

Required.

Content type	Schema
application/json	ResolveAttentionRequest

Responses

Status	Meaning	Body	Headers
200	The clarification was resolved, or an exact retry returned its result.	application/json · Attention	ETag, Idempotent-Replayed
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
412	The If-Match version is stale; read the resource again and retry with its current version.	application/problem+json · Problem	—
428	The required If-Match header is missing.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work/{id}/approvals

List approvals for Work

• Operation ID: listWorkApprovals
• Required scope: approval:read
• Tag: Approvals

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
status	query	No	ApprovalStatus	—

Responses

Status	Meaning	Body	Headers
200	Approvals for this service-created Work.	application/json · ApprovalList	—
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

POST /api/v1/work/{id}/approvals/{approval_id}/resolve

Resolve an exact Work approval

• Operation ID: resolveWorkApproval
• Required scope: approval:resolve
• Tag: Approvals

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
approval_id	path	Yes	string	Minimum length 1
If-Match	header	Yes	string	Strong integer version tag returned by the current resource. Minimum length 1
Idempotency-Key	header	Yes	string	Caller-selected key. An exact retry returns the original result; reusing the key with different input returns IDEMPOTENCY_CONFLICT. Minimum length 1. Maximum length 255

Request body

Required.

Content type	Schema
application/json	ResolveApprovalRequest

Responses

Status	Meaning	Body	Headers
200	The approval was resolved, or an exact retry returned its result.	application/json · Approval	ETag, Idempotent-Replayed
400	The request is invalid.	application/problem+json · Problem	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
412	The If-Match version is stale; read the resource again and retry with its current version.	application/problem+json · Problem	—
428	The required If-Match header is missing.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work/{id}/artifacts

List current result Artifacts for Work

• Operation ID: listWorkArtifacts
• Required scope: artifact:read
• Tag: Artifacts

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1

Responses

Status	Meaning	Body	Headers
200	Latest result Artifact version for each output path. A version that is not yet downloadable is listed with its processing_state (and failure_code) instead of being omitted.	application/json · ArtifactList	—
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

GET /api/v1/work/{id}/artifacts/{artifact_id}/content

Download an exact result Artifact

• Operation ID: downloadWorkArtifact
• Required scope: artifact:read
• Tag: Artifacts

Parameters

Name	In	Required	Type	Details
id	path	Yes	string	Minimum length 1
artifact_id	path	Yes	string	Minimum length 1

Responses

Status	Meaning	Body	Headers
200	Hash-verified result bytes after all Artifact gates pass.	application/octet-stream · string (binary)	ETag, Content-Disposition
401	The service credential is missing, invalid, revoked, or unavailable.	application/problem+json · Problem	—
403	The service account lacks the required scope or policy denied the request.	application/problem+json · Problem	—
404	The Work or referenced resource is not visible to this service account.	application/problem+json · Problem	—
409	The idempotency key was already used with different input, the resource changed state, or a referenced upload is not attachable: INPUT_NOT_READY (still scanning; retryable, honour Retry-After) or INPUT_SCAN_FAILED (see failure_code; retryable when the scan can be retried with retryInputUploadProcessing).	application/problem+json · Problem	—
422	The active organization data policy blocked the input, Work objective, or Artifact download at its governed boundary.	application/problem+json · Problem	—
429	The credential’s rate limit for this class, its concurrent-stream limit, or the client address’s unauthenticated budget is exhausted.	application/problem+json · Problem	Retry-After, RateLimit-Policy, RateLimit

Schemas

CreateWorkRequest

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
colleague_id	Yes	string	Minimum length 1
objective	Yes	string	Minimum length 1. Maximum length 4000
title	No	string	—
visibility_scope	No	VisibilityScope	—
active_execution_limit_seconds	No	integer (int64)	Minimum 1. Maximum 86400
priority	No	WorkPriority	—
due_at	No	string (date-time)	—
input_upload_ids	No	array of string	At most 4 items. Unique items

CreateInputUploadRequest

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
name	Yes	string	Minimum length 1. Maximum length 120
media_type	Yes	string	One of application/json, text/csv, text/markdown, text/plain
content	Yes	string	Minimum length 1. Maximum length 102400. UTF-8 encoded content must not exceed 102400 bytes.

InputUpload

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
id	Yes	string	—
name	Yes	string	—
media_type	Yes	string	—
size	Yes	integer (int64)	Minimum 1. Maximum 102400
content_hash	Yes	string	—
status	Yes	string	One of ready, consumed, expired, processing, failed. ready only when the upload can be attached to Work; processing while it is scanned; failed when the scan did not pass (see processing_state and failure_code).
processing_state	No	ProcessingState	—
failure_code	No	string	Why processing did not make the upload available, for example stale_signatures or malware_detected.
retryable	No	boolean	True when retryInputUploadProcessing can clear a scan_failed state.
detected_type	No	string	—
work_id	No	string	—
expires_at	Yes	string (date-time)	—
created_at	Yes	string (date-time)	—

Work

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
id	Yes	string	—
title	Yes	string	—
objective	Yes	string	—
status	Yes	WorkStatus	—
colleague_id	Yes	string	—
human_owner_id	Yes	string	—
visibility_scope	Yes	VisibilityScope	—
priority	Yes	WorkPriority	—
due_at	No	string (date-time)	—
version	Yes	integer (int64)	Minimum 1. Increases whenever the Work changes, including its status.
created_by	Yes	string	—
created_at	Yes	string (date-time)	—
updated_at	Yes	string (date-time)	—
current_attention_id	No	string	—
attention_question	No	string	—
completion_summary	No	string	—

WorkList

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
data	Yes	array of Work	—
next_cursor	No	string	Present when more Work exists; pass as cursor.

ProcessingState

User-facing scan and processing state of an upload or result Artifact.

Type: string. One of processing, available, quarantined, scan_failed, failed, expired

WorkStatus

Type: string. One of working, needs_you, paused, done

WorkPriority

Type: string. One of low, normal, high, urgent

VisibilityScope

Type: string. One of private, team, organization

Attention

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
id	Yes	string	—
work_id	Yes	string	—
kind	Yes	string	One of clarification
source_id	Yes	string	—
title	Yes	string	—
what_happened	Yes	string	—
why_needed	Yes	string	—
recommended_action	Yes	string	—
consequences	Yes	string	—
status	Yes	string	One of open, resolved
version	Yes	integer (int64)	Minimum 1
created_at	Yes	string (date-time)	—
resolved_at	No	string (date-time)	—
resolved_by	No	string	—
resolution	No	string	—

AttentionList

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
data	Yes	array of Attention	—

ResolveAttentionRequest

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
response	Yes	string	Minimum length 1. Maximum length 4000

Approval

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
id	Yes	string	—
work_id	Yes	string	—
action_id	Yes	string	—
requested_by_colleague	Yes	string	—
summary	Yes	string	—
risk	Yes	string	—
destination	Yes	string	—
subject	Yes	string	—
body	Yes	string	—
proposed_action_payload_hash	Yes	string	—
policy_reason	Yes	string	—
status	Yes	ApprovalStatus	—
version	Yes	integer (int64)	Minimum 1
created_at	Yes	string (date-time)	—
resolved_at	No	string (date-time)	—
resolution_actor	No	string	—
resolution_comment	No	string	—

ApprovalStatus

Type: string. One of pending, approved, declined

ApprovalList

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
data	Yes	array of Approval	—

ResolveApprovalRequest

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
decision	Yes	string	One of approve, decline
comment	No	string	Maximum length 2000

Artifact

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
id	Yes	string	—
work_id	Yes	string	—
path	Yes	string	—
media_type	Yes	string	—
size	Yes	integer (int64)	Minimum 0
content_hash	Yes	string	—
version	Yes	integer (int64)	Minimum 1
created_at	Yes	string (date-time)	—
processing_state	No	ProcessingState	—
failure_code	No	string	Why a result that is not available cannot be downloaded yet.

ArtifactList

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
data	Yes	array of Artifact	—

Problem

Unknown properties are not accepted.

Property	Required	Type	Constraints and description
type	Yes	string	—
title	Yes	string	—
status	Yes	integer	—
detail	Yes	string	—
instance	Yes	string	—
code	Yes	string	—
request_id	Yes	string	—
retryable	Yes	boolean	—
failure_code	No	string	The upload’s processing failure_code on INPUT_SCAN_FAILED.