duvo.ai ClarityV2 API
Manage Clarity v2 process snapshots, transformation proposals, and the extra-capture-request follow-up loop
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders ClarityV2 API
description: Public API for programmatic access to Duvo. Authenticate with API keys created in the Duvo dashboard.
version: 1.0.0
servers:
- url: https://api.duvo.ai
description: Production server
tags:
- name: ClarityV2
description: Manage Clarity v2 process snapshots, transformation proposals, and the extra-capture-request follow-up loop
paths:
/v2/clarity-v2/processes/{process_id}:
get:
operationId: getClarityProcess
tags:
- ClarityV2
description: 'Get the v2 read model for a clarity process: the process row (with operational fields like generation_error, generation_progress, custom_prompt), its captures, and the lightweight version arrays for both snapshot tabs. The full payload of any specific snapshot is fetched lazily via the unified per-snapshot detail endpoint (`GET .../snapshots/:kind/:id`); this read model deliberately doesn''t carry it so the response stays small.'
parameters:
- schema:
default: full
type: string
enum:
- full
- lite
in: query
name: captures
required: false
description: Capture payload mode. `full` (default) embeds each capture's transcript content. `lite` omits `transcript`/`videoTranscript` (returned as null) and relies on the `hasTranscript`/`hasVideoTranscript` flags; fetch content on demand via `GET .../captures/:capture_id`.
- schema:
type: string
format: uuid
in: path
name: process_id
required: true
description: The clarity process id
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
process:
type: object
properties:
id:
type: string
format: uuid
description: Clarity process id
team_id:
type: string
format: uuid
description: Owning team id
user_id:
type: string
format: uuid
description: Creator user id
name:
type: string
description: Process name
status:
type: string
enum:
- draft
- collecting
- generating
- generating-current-process
- generating-transformation-proposal
- review
- complete
- generation_failed
description: Lifecycle status
visibility:
type: string
enum:
- team
- restricted
description: Process visibility. 'team' is workspace-visible to full members; 'restricted' is visible to the creator, org admins, workspace managers/admins, and accepted grant holders.
version:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
description: Schema version (always 2 here)
generation_error:
nullable: true
description: Error message from the most recent failed generation, if any
type: string
generation_progress:
nullable: true
description: Live progress checklist while a generation is in flight; null otherwise. Field names inside the payload are camelCase, matching the legacy v1 generation-progress shape.
type: object
properties:
steps:
type: array
items:
type: object
properties:
key:
type: string
label:
type: string
status:
type: string
enum:
- pending
- in_progress
- complete
order:
type: number
count:
type: number
required:
- key
- label
- status
- order
additionalProperties: false
required:
- steps
additionalProperties: false
custom_prompt:
nullable: true
description: User-supplied custom prompt that steers generation
type: string
created_at:
type: string
description: ISO 8601 creation timestamp
updated_at:
type: string
description: ISO 8601 last-update timestamp
required:
- id
- team_id
- user_id
- name
- status
- visibility
- version
- generation_error
- generation_progress
- custom_prompt
- created_at
- updated_at
additionalProperties: false
current_process_versions:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Snapshot id
process_id:
type: string
format: uuid
description: Parent clarity_process id
parent_current_process_id:
nullable: true
description: Parent current-process snapshot this draft forked from
type: string
format: uuid
created_at:
type: string
description: ISO 8601 creation timestamp
status:
type: string
enum:
- live
- historic
- draft
- generating
description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion.
creator_type:
type: string
enum:
- human
- ai
description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai').
user_id:
nullable: true
description: Creator user id (the human who edited or triggered the run).
type: string
format: uuid
sandbox_id:
nullable: true
description: E2B sandbox id that produced AI rows; null for user edits.
type: string
last_session_id:
nullable: true
description: Claude SDK session id for artifact-chat follow-up reuse.
type: string
required:
- id
- process_id
- parent_current_process_id
- created_at
- status
- creator_type
- user_id
- sandbox_id
- last_session_id
additionalProperties: false
description: All non-deleted current-process snapshots, newest first. Lightweight rows (no `data`) for the version-picker UI. Clients lazy-fetch the live (or selected) snapshot via the per-snapshot detail endpoint.
transformation_proposal_versions:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Proposal id
process_id:
type: string
format: uuid
description: Parent clarity_process id
clarity_current_process_id:
type: string
format: uuid
description: The current-process snapshot this proposal was generated against (provenance only; the live proposal can target any current-process snapshot).
parent_transformation_proposal_id:
nullable: true
description: Parent transformation-proposal snapshot this draft forked from
type: string
format: uuid
created_at:
type: string
description: ISO 8601 creation timestamp
status:
type: string
enum:
- live
- historic
- draft
- generating
description: Versioning state. Only one 'live' row per process at a time; drafts may be edited or generating before promotion.
creator_type:
type: string
enum:
- human
- ai
description: Whether this row was created by a user edit ('human') or an AI pipeline run ('ai').
user_id:
nullable: true
description: Creator user id (the human who edited or triggered the run).
type: string
format: uuid
sandbox_id:
nullable: true
description: E2B sandbox id that produced AI rows; null for user edits.
type: string
last_session_id:
nullable: true
description: Claude SDK session id for artifact-chat follow-up reuse.
type: string
extra_capture_requests:
description: Active extra-capture requests for this proposal. Populated only on the live proposal version row in the read-model endpoint so the FE can render assignment UI without a second round-trip; historic versions return an empty array. Other endpoints (e.g. admin snapshot views) may omit it entirely, in which case it is `undefined`. The standalone list endpoint stays the source of truth for paginated/admin views.
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Extra-capture-request id
proposal_id:
type: string
format: uuid
description: The transformation proposal this request belongs to
step_id:
type: string
description: Step id within the proposal's BPMN graph
capture_id:
nullable: true
description: Capture that fulfilled this request, once one is created
type: string
format: uuid
requested_user_id:
nullable: true
description: Assigned team member, if any
type: string
format: uuid
status:
type: string
enum:
- requested
- captured
- resolved
description: Lifecycle status of the request
gap:
type: string
description: Plain-language gap blocking automation
suggested_prompt:
nullable: true
description: LLM-produced suggested capture prompt
type: string
priority:
type: string
enum:
- low
- medium
- high
description: Priority of fulfilling this request
created_at:
type: string
description: ISO 8601 creation timestamp
updated_at:
type: string
description: ISO 8601 last-update timestamp
required:
- id
- proposal_id
- step_id
- capture_id
- requested_user_id
- status
- gap
- suggested_prompt
- priority
- created_at
- updated_at
additionalProperties: false
required:
- id
- process_id
- clarity_current_process_id
- parent_transformation_proposal_id
- created_at
- status
- creator_type
- user_id
- sandbox_id
- last_session_id
additionalProperties: false
description: All non-deleted transformation-proposal snapshots, newest first. Lightweight rows (no `data`) for the version-picker UI.
captures:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
processId:
type: string
format: uuid
userId:
type: string
format: uuid
userName:
type: string
type:
type: string
x-extensible-enum:
- video
- interview
- document
- screenshare
- meeting
videoUrl:
nullable: true
type: string
videoTranscript:
nullable: true
type: string
documentFileName:
nullable: true
type: string
documentTextMetadata:
nullable: true
type: object
properties:
pages:
type: array
items:
type: object
properties:
pageNumber:
type: integer
exclusiveMinimum: true
maximum: 9007199254740991
startOffset:
type: integer
minimum: 0
maximum: 9007199254740991
endOffset:
type: integer
minimum: 0
maximum: 9007199254740991
lines:
type: array
items:
type: object
properties:
pageNumber:
type: integer
exclusiveMinimum: true
maximum: 9007199254740991
lineNumber:
type: integer
exclusiveMinimum: true
maximum: 9007199254740991
startOffset:
type: integer
minimum: 0
maximum: 9007199254740991
endOffset:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- pageNumber
- lineNumber
- startOffset
- endOffset
additionalProperties: false
required:
- pageNumber
- startOffset
- endOffset
- lines
additionalProperties: false
required:
- pages
additionalProperties: false
transcript:
nullable: true
type: array
items:
type: object
properties:
source:
type: string
enum:
- ai
- user
- interviewer
speakerName:
type: string
message:
type: string
minLength: 1
timestamp:
type: number
required:
- source
- message
additionalProperties: false
hasTranscript:
type: boolean
hasVideoTranscript:
type: boolean
transcriptQuestionCount:
type: integer
minimum: 0
maximum: 9007199254740991
status:
type: string
enum:
- pending
- recording
- processing
- complete
- failed
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- processId
- userId
- type
- videoUrl
- videoTranscript
- transcript
- status
- createdAt
- updatedAt
additionalProperties: false
description: All captures (videos, interviews, documents) attached to this process. Field names follow the legacy v1 capture wire format (camelCase) so existing capture consumers keep working unchanged.
required:
- process
- current_process_versions
- transformation_proposal_versions
- captures
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Get Clarity Process
/v2/clarity-v2/processes/{process_id}/postprocess:
post:
operationId: postprocessClaritySnapshot
tags:
- ClarityV2
description: Re-run postprocessing agents on an existing v2 clarity snapshot. Targets either the current-process snapshot or the transformation-proposal snapshot, identified by id in the body. Flips the process status to `generating` and returns 202 immediately; agents run asynchronously and flip the status back to `review` once they settle.
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
properties:
type:
type: string
enum:
- current_process
current_process_id:
type: string
format: uuid
description: ID of the `clarity_current_process` snapshot to re-postprocess.
required:
- type
- current_process_id
- type: object
properties:
type:
type: string
enum:
- transformation_proposal
transformation_proposal_id:
type: string
format: uuid
description: ID of the `clarity_transformation_proposal` snapshot to re-postprocess.
required:
- type
- transformation_proposal_id
parameters:
- schema:
type: string
format: uuid
in: path
name: process_id
required: true
description: The clarity process id
security:
- bearerAuth: []
responses:
'202':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Postprocess Clarity Snapshot
/v2/clarity-v2/processes/{process_id}/automation:
post:
operationId: buildClarityAutomation
tags:
- ClarityV2
description: Hand the latest transformation proposal for a v2 clarity process off to the workflow-builder pipeline. Returns 202 with the new run id; the LLM run completes asynchronously.
parameters:
- schema:
type: string
format: uuid
in: path
name: process_id
required: true
description: The clarity process id
security:
- bearerAuth: []
responses:
'202':
description: Default Response
content:
application/json:
schema:
type: object
properties:
automation_run:
type: object
properties:
id:
type: string
format: uuid
description: Workflow-builder run id
status:
type: string
enum:
- generating
description: Always `generating` immediately after kickoff
required:
- id
- status
additionalProperties: false
required:
- automation_run
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Build Clarity Automation
/v2/clarity-v2/processes/{process_id}/transformation-proposals/{transformation_proposal_id}/extra-capture-requests:
get:
operationId: listClarityExtraCaptureRequests
tags:
- ClarityV2
description: List active extra-capture requests for a given transformation proposal of a Clarity v2 process. The caller is expected to know the proposal id from the V2 read model and skip the call when no proposal exists yet.
parameters:
- schema:
default: 20
type: integer
# --- truncated at 32 KB (681 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-clarityv2-api-openapi.yml