duvo.ai Organizations API
Inspect organizations you belong to and the teams within them
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Organizations 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: Organizations
description: Inspect organizations you belong to and the teams within them
paths:
/v2/organizations/{orgId}/clarity/hierarchy/proposed-processes:
post:
operationId: proposeClarityLandscapeProcess
tags:
- Organizations
description: Create a manual process in the organization's Process Landscape, either as an unassigned proposal or atomically assigned to an eligible team.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 200
description:
description: 'One short paragraph (1-3 sentences) saying why this process belongs in the landscape. Use only what you saw in the captures. Say what the process is (don''t just repeat the name), show proof it really happens, and name where you heard it - be as specific as the captures allow, like "a warehouse lead said so in their interview" or "it came up in two returns recordings". Use only facts from the captures: never make up sources, people, dates, quotes, or numbers, and don''t stretch what was said. If you have no real proof the process happens, don''t propose it.'
nullable: true
type: string
maxLength: 5000
parentId:
default: null
nullable: true
type: string
format: uuid
teamId:
default: null
nullable: true
type: string
format: uuid
required:
- name
parameters:
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
parentId:
nullable: true
type: string
format: uuid
processId:
nullable: true
type: string
format: uuid
name:
type: string
ownerLabel:
nullable: true
type: string
sortOrder:
type: number
existence:
type: string
enum:
- proposed
- active
contentConfirmedAt:
nullable: true
type: string
existenceConfirmedAt:
nullable: true
type: string
source:
type: string
enum:
- ai
- human
createdAt:
type: string
updatedAt:
type: string
team:
nullable: true
type: object
properties:
id:
type: string
format: uuid
name:
type: string
required:
- id
- name
additionalProperties: false
required:
- id
- parentId
- processId
- name
- ownerLabel
- sortOrder
- existence
- contentConfirmedAt
- existenceConfirmedAt
- source
- createdAt
- updatedAt
- team
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
'422':
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: Propose Clarity Landscape Process
/v2/organizations/{orgId}/members:
post:
operationId: inviteOrgMember
tags:
- Organizations
description: Invite a person to an organization you administer, optionally assigning them to a team in that organization. Requires an organization Admin, Executive, or Owner role. You cannot grant a role higher than your own.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
role:
type: string
enum:
- organization:executive
- organization:owner
- organization:admin
- organization:member
frontendUrl:
type: string
format: uri
teamId:
type: string
format: uuid
required:
- email
- role
parameters:
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: Organization ID
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
invitationId:
type: string
format: uuid
emailSent:
type: boolean
required:
- success
- invitationId
- emailSent
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: Invite Org Member
/v2/organizations/{orgId}/teams:
get:
operationId: listOrgTeams
tags:
- Organizations
description: List teams belonging to an organization you are a member of, including your membership and role in each.
parameters:
- schema:
default: 50
type: number
minimum: 1
maximum: 100
in: query
name: limit
required: false
description: Number of teams per page (1-100, default 50)
- schema:
type: number
minimum: 0
in: query
name: offset
required: false
description: Number of teams to skip
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: Organization ID
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
teams:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
createdAt:
type: string
discoveryMode:
type: string
enum:
- request
- auto
memberCount:
type: number
pendingInvitationCount:
type: number
pendingJoinRequestCount:
type: number
userIsMember:
type: boolean
userRole:
nullable: true
type: string
userHasPendingJoinRequest:
type: boolean
assignmentCount:
type: number
jobCount:
type: number
scheduledJobCount:
type: number
required:
- id
- name
- createdAt
- discoveryMode
- memberCount
- pendingInvitationCount
- pendingJoinRequestCount
- userIsMember
- userRole
- userHasPendingJoinRequest
- assignmentCount
- jobCount
- scheduledJobCount
additionalProperties: false
total:
type: number
required:
- teams
- total
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: List Org Teams
post:
operationId: createOrgTeam
tags:
- Organizations
description: Create a new team under an organization you administer. Requires an organization Admin, Executive, or Owner role.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
required:
- name
parameters:
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: Organization ID
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
required:
- id
- name
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: Create Org Team
/v2/organizations/{orgId}/insights/headline:
get:
operationId: getOrgInsightsHeadline
tags:
- Organizations
description: Get org-wide headline insight KPIs (run totals, success rate, distinct active agents and users) aggregated across every team in the organization. Requires an organization Admin, Executive, or Owner role.
parameters:
- schema:
type: string
format: date-time
in: query
name: startDate
required: false
description: Start of the aggregation window (ISO 8601 datetime). Defaults to 30 days ago; clamped to at most 365 days ago.
- schema:
type: string
format: date-time
in: query
name: endDate
required: false
description: End of the aggregation window (ISO 8601 datetime, exclusive). Defaults to now; clamped to now.
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: The organization's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
headline:
type: object
properties:
total_runs:
type: number
description: Total runs started in the window across all org teams
completed_runs:
type: number
description: Runs that finished with completed status
failed_runs:
type: number
description: Runs that finished with failed status
success_rate:
nullable: true
description: completed_runs / (completed_runs + failed_runs), null when no runs finished in the window
type: number
active_agents:
type: number
description: Distinct agents with at least one run in the window (org-wide, includes since-deleted agents so totals reconcile with run counts)
active_users:
type: number
description: Distinct users who started at least one run in the window, deduplicated across teams
start_date:
type: string
description: Effective window start after clamping (ISO 8601)
end_date:
type: string
description: Effective window end after clamping (ISO 8601)
truncated:
type: boolean
description: True when the org has more teams than the aggregation limit — figures cover only the first teams up to the cap
aggregated_teams:
type: number
description: Number of teams actually included in the aggregation
total_teams:
type: number
description: Actual team count on the org, even when truncated
required:
- total_runs
- completed_runs
- failed_runs
- success_rate
- active_agents
- active_users
- start_date
- end_date
- truncated
- aggregated_teams
- total_teams
additionalProperties: false
required:
- headline
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
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Get Org Insights Headline
/v2/organizations/{orgId}/insights/metrics:
get:
operationId: getOrgInsightsMetrics
tags:
- Organizations
description: Get org-level insights metrics (runs, assignments, schedules) broken down per team across the organization. Requires an organization Admin, Executive, or Owner role.
parameters:
- schema:
type: string
format: date-time
in: query
name: startDate
required: false
description: Start of the aggregation window (ISO 8601 datetime). Defaults to 7 days ago; clamped to at most 365 days ago.
- schema:
type: string
format: date-time
in: query
name: endDate
required: false
description: End of the aggregation window (ISO 8601 datetime). Defaults to now; clamped to now.
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: The organization's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
teams:
type: array
items:
type: object
properties:
team_id:
type: string
format: uuid
description: Team's unique identifier
team_name:
type: string
description: Team name
is_deleted:
type: boolean
description: Whether the team is soft-deleted
member_count:
type: number
description: Number of members on the team
assignment_count:
type: number
description: Number of (non-deleted) agents on the team
scheduled_job_count:
type: number
description: Number of enabled schedules on the team's agents
total_jobs:
type: number
description: Scheduled runs in the window (source = scheduling)
completed_jobs:
type: number
description: Scheduled runs that completed
failed_jobs:
type: number
description: Scheduled runs that failed
total_runs:
type: number
description: All runs in the window across sources
required:
- team_id
- team_name
- is_deleted
- member_count
- assignment_count
- scheduled_job_count
- total_jobs
- completed_jobs
- failed_jobs
- total_runs
additionalProperties: false
description: Per-team metric breakdown
start_date:
type: string
description: Effective window start after clamping (ISO 8601)
end_date:
type: string
description: Effective window end after clamping (ISO 8601)
truncated:
type: boolean
description: True when the org has more teams than the aggregation limit — the team list is partial
total_teams:
type: number
description: Actual team count on the org, even when truncated
org_member_count:
type: number
description: Distinct organization members (not the sum of per-team memberships)
required:
- teams
- start_date
- end_date
- truncated
- total_teams
- org_member_count
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
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Get Org Insights Metrics
/v2/organizations/{orgId}/insights/usage-chart:
get:
operationId: getOrgInsightsUsageChart
tags:
- Organizations
description: Get org-level run-volume buckets (scheduled vs on-demand) at day/week/month granularity across the organization. Requires an organization Admin, Executive, or Owner role.
parameters:
- schema:
type: string
format: date-time
in: query
name: startDate
required: true
description: Start of the chart window (ISO 8601 datetime). Clamped to at most 365 days ago.
- schema:
type: string
format: date-time
in: query
name: endDate
required: true
description: End of the chart window (ISO 8601 datetime). Clamped to now.
- schema:
type: string
enum:
- day
- week
- month
in: query
name: granularity
required: true
description: 'Bucket size: day, week, or month'
- schema:
type: string
maxLength: 64
pattern: ^[A-Za-z_]+(?:\/[A-Za-z_\-+0-9]+){0,2}$
in: query
name: timezone
required: false
description: IANA timezone for bucket boundaries (e.g. America/New_York). Defaults to UTC.
- schema:
type: string
format: uuid
in: path
name: orgId
required: true
description: The organization's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
buckets:
type: array
items:
type: object
properties:
period:
type: string
description: B
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-organizations-api-openapi.yml