duvo.ai Secrets API
Manage env-var secrets injected into runs, and attach them to assignment revisions. Only metadata is exposed; values are never returned
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Secrets 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: Secrets
description: Manage env-var secrets injected into runs, and attach them to assignment revisions. Only metadata is exposed; values are never returned
paths:
/v2/credentials/{id}:
get:
operationId: getSecret
tags:
- Secrets
description: Get an env-var secret by id. Returns metadata and env var keys; secret values are never exposed.
parameters:
- schema:
type: string
format: uuid
in: path
name: id
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
team_id:
type: string
format: uuid
user_id:
nullable: true
type: string
format: uuid
name:
type: string
service_slug:
nullable: true
type: string
env_var_keys:
type: array
items:
type: string
created_by:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- team_id
- user_id
- name
- service_slug
- env_var_keys
- created_by
- created_at
- updated_at
additionalProperties: false
'401':
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 Secret
patch:
operationId: updateSecret
tags:
- Secrets
description: Update an env-var secret. Send `values` to replace all entries, or any of `rename_keys`, `remove_keys`, `add_values` for a non-destructive patch. Editing a team-shared secret or toggling sharing requires manager role.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 128
service_slug:
nullable: true
type: string
minLength: 1
maxLength: 64
shared:
type: boolean
values:
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 65536
rename_keys:
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 128
pattern: ^[A-Z_][A-Z0-9_]*$
remove_keys:
minItems: 1
type: array
items:
type: string
minLength: 1
maxLength: 128
pattern: ^[A-Z_][A-Z0-9_]*$
add_values:
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 65536
parameters:
- schema:
type: string
format: uuid
in: path
name: id
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
team_id:
type: string
format: uuid
user_id:
nullable: true
type: string
format: uuid
name:
type: string
service_slug:
nullable: true
type: string
env_var_keys:
type: array
items:
type: string
created_by:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- team_id
- user_id
- name
- service_slug
- env_var_keys
- created_by
- created_at
- updated_at
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: Update Secret
delete:
operationId: deleteSecret
tags:
- Secrets
description: Soft-delete an env-var secret. Deleting a team-shared secret requires manager role.
parameters:
- schema:
type: string
format: uuid
in: path
name: id
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
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: Delete Secret
/v2/agents/{agentId}/revisions/{buildId}/credentials:
get:
operationId: listRevisionSecrets
tags:
- Secrets
description: List env-var secrets attached to a specific revision (build) of an assignment. Returns metadata and env-var keys only — secret values are never exposed.
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
- schema:
type: string
format: uuid
in: path
name: buildId
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
team_id:
type: string
format: uuid
user_id:
nullable: true
type: string
format: uuid
name:
type: string
service_slug:
nullable: true
type: string
env_var_keys:
type: array
items:
type: string
created_by:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- team_id
- user_id
- name
- service_slug
- env_var_keys
- created_by
- created_at
- updated_at
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: List Revision Secrets
post:
operationId: attachRevisionSecret
tags:
- Secrets
description: Attach an env-var secret to a revision so its keys are injected into Runs spawned from that revision. Personal secrets can only be attached by their owner; team-shared secrets require builder permissions.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
credentialId:
type: string
format: uuid
required:
- credentialId
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
- schema:
type: string
format: uuid
in: path
name: buildId
required: true
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
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
'409':
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: Attach Revision Secret
/v2/agents/{agentId}/revisions/{buildId}/credentials/{credentialId}:
delete:
operationId: detachRevisionSecret
tags:
- Secrets
description: Detach an env-var secret from a revision. Personal secrets can only be detached by their owner; team-shared secrets require builder permissions.
parameters:
- schema:
type: string
format: uuid
in: path
name: agentId
required: true
- schema:
type: string
format: uuid
in: path
name: buildId
required: true
- schema:
type: string
format: uuid
in: path
name: credentialId
required: true
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
required:
- success
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
'409':
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: Detach Revision Secret
/v2/teams/{teamId}/credentials:
get:
operationId: listSecrets
tags:
- Secrets
description: List env-var secrets visible to the caller — team-shared (user_id IS NULL) plus the caller's own personal entries. Returns metadata and env-var keys only; secret values are never exposed.
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
team_id:
type: string
format: uuid
user_id:
nullable: true
type: string
format: uuid
name:
type: string
service_slug:
nullable: true
type: string
env_var_keys:
type: array
items:
type: string
created_by:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- team_id
- user_id
- name
- service_slug
- env_var_keys
- created_by
- created_at
- updated_at
additionalProperties: false
'401':
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 Secrets
post:
operationId: createSecret
tags:
- Secrets
description: 'Create an env-var secret. Personal by default; pass `shared: true` to create a team-shared secret (requires manager role).'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 128
service_slug:
nullable: true
type: string
minLength: 1
maxLength: 64
shared:
default: false
type: boolean
values:
type: object
additionalProperties:
type: string
minLength: 1
maxLength: 65536
required:
- name
- values
security:
- bearerAuth: []
parameters:
- schema:
type: string
in: path
name: teamId
required: true
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
team_id:
type: string
format: uuid
user_id:
nullable: true
type: string
format: uuid
name:
type: string
service_slug:
nullable: true
type: string
env_var_keys:
type: array
items:
type: string
created_by:
type: string
format: uuid
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- id
- team_id
- user_id
- name
- service_slug
- env_var_keys
- created_by
- created_at
- updated_at
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: Create Secret
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your API key from the Duvo dashboard.