Vertesia Secrets API
The Secrets API from Vertesia — 3 operation(s) for secrets.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/vertesiahq:vertesiahq-secrets-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Vertesia Secrets API
version: 1.6.0-dev.20261019.172735Z
x-api-version: '20260803'
description: The Vertesia API provides project-scoped access to interaction execution and content workflows. Use it to run interactions, inspect execution history, stream run progress, replay previous executions, and search content objects and collections. Authenticate requests with a bearer token, or use the official `@vertesia/client` package for typed access from Node.js applications.
contact:
name: Vertesia
url: https://vertesiahq.com/
license:
name: Apache-2.0
identifier: Apache-2.0
x-scalar-sdk-installation:
- lang: Node
description: 'Install the **Vertesia Client** from npm:'
source: npm install @vertesia/client
servers:
- url: https://api.{region}.vertesia.io/api/v1
description: Vertesia API
variables:
region:
default: us1
enum:
- us1
- eu1
- jp1
description: Regional API host label. `us1` is the global endpoint.
tags:
- name: Secrets
paths:
/secrets:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
get:
operationId: ListSecrets
tags:
- Secrets
summary: List secrets
description: Lists project-scoped secrets. This version returns website_credential secrets. Secret values are never returned.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
- name: kind
in: query
required: false
schema:
type: string
enum:
- website_credential
style: form
- name: host
in: query
required: false
schema:
type: string
- name: enabled
in: query
required: false
schema:
type: boolean
responses:
'200':
description: Secrets.
content:
application/json:
schema:
$ref: '#/components/schemas/ListSecretsResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: listSecrets
post:
operationId: CreateSecret
tags:
- Secrets
summary: Create secret
description: 'Creates a project-scoped website_credential secret. Secret values are encrypted and never returned.
**Required permissions:** `project:admin`'
security:
- bearerAuth: []
- OAuth2:
- project:admin
parameters:
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
responses:
'200':
description: Created secret metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretRecord'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- project:admin
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: createSecret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSecretRequest'
/secrets/{secretId}:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
get:
operationId: GetSecret
tags:
- Secrets
summary: Retrieve secret metadata
description: Retrieves one project-scoped secret. Secret values are never returned.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: secretId
in: path
required: true
schema:
type: string
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
- name: kind
in: query
required: false
schema:
type: string
enum:
- website_credential
style: form
responses:
'200':
description: Secret metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretRecord'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: getSecret
put:
operationId: UpdateSecret
tags:
- Secrets
summary: Update secret
description: 'Updates secret metadata and write-only secret values.
**Required permissions:** `project:admin`'
security:
- bearerAuth: []
- OAuth2:
- project:admin
parameters:
- name: secretId
in: path
required: true
schema:
type: string
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
- name: kind
in: query
required: false
schema:
type: string
enum:
- website_credential
style: form
responses:
'200':
description: Updated secret metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/SecretRecord'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- project:admin
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: updateSecret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSecretRequest'
delete:
operationId: DeleteSecret
tags:
- Secrets
summary: Delete secret
description: 'Deletes a project-scoped secret and its encrypted value bundle.
**Required permissions:** `project:admin`'
security:
- bearerAuth: []
- OAuth2:
- project:admin
parameters:
- name: secretId
in: path
required: true
schema:
type: string
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
- name: kind
in: query
required: false
schema:
type: string
enum:
- website_credential
style: form
responses:
'200':
description: Delete result.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSecretResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions:
- project:admin
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: deleteSecret
/secrets/{secretId}/actions/fill-browser:
parameters:
- name: x-api-version
in: header
required: true
schema:
type: string
minLength: 1
pattern: \S
example: '20260803'
description: Required Vertesia API version header. Use `20260803` for the current stable API shape.
x-vertesia-global-header: true
post:
operationId: FillWebsiteCredential
tags:
- Secrets
summary: Fill website credential into a browser-use sandbox
description: Resolves the browser-use sandbox server-side, observes the current page, then decrypts and fills a project-scoped website credential. Secret values are never returned.
security:
- bearerAuth: []
- OAuth2: []
parameters:
- name: secretId
in: path
required: true
schema:
type: string
- name: project_id
in: query
required: false
schema:
type: string
description: Project scope for top-level secret APIs. Must match the authenticated project context.
description: Project scope for top-level secret APIs. Must match the authenticated project context.
responses:
'200':
description: Fill result.
content:
application/json:
schema:
$ref: '#/components/schemas/WebsiteCredentialFillResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Internal Server Error
status: 500
message: Internal server error.
4XX:
description: Client error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
status: 400
message: Request validation failed.
x-vertesia-permissions: []
x-vertesia-source:
file: ../../apps/studio-server/src/api/secrets.ts
className: SecretsResource
methodName: fillWebsiteCredential
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebsiteCredentialFillRequest'
components:
schemas:
WebsiteCredentialFillResponse:
type: object
properties:
ok:
type: boolean
credential_ref:
type: string
url:
type: string
title:
type: string
filled:
type: object
properties:
username:
type: boolean
password:
type: boolean
totp:
type: boolean
submitted:
type: boolean
required:
- username
- password
- totp
- submitted
additionalProperties: false
required:
- ok
- credential_ref
- url
- title
- filled
additionalProperties: false
WebsiteCredentialWebsite:
type: object
properties:
host:
type: string
description: Hostname this credential is allowed on. Subdomains match.
login_url:
type: string
description: Optional login URL used by agents as a hint.
allowed_origins:
type: array
items:
type: string
description: Optional narrower origin allowlist for this credential.
required:
- host
additionalProperties: false
CreateSecretRequest:
type: object
properties:
kind:
$ref: '#/components/schemas/SecretKind'
metadata:
$ref: '#/components/schemas/WebsiteCredentialMetadata'
secret:
$ref: '#/components/schemas/WebsiteCredentialSecretInput'
required:
- kind
- metadata
additionalProperties: false
WebsiteCredentialRecord:
type: object
properties:
id:
type: string
credential_ref:
type: string
project:
type: string
name:
type: string
websites:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialWebsite'
username:
type: string
username_hint:
type: string
username_secret_enabled:
type: boolean
properties:
type: object
additionalProperties: true
tags:
type: array
items:
type: string
enabled:
type: boolean
capabilities:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialCapability'
notes:
type: string
totp_metadata:
$ref: '#/components/schemas/WebsiteCredentialTotpMetadata'
expires_at:
type: string
description: Optional ISO timestamp after which the credential is no longer usable. Expired credentials are hidden from lookup and cannot be filled.
created_at:
type: string
updated_at:
type: string
has_username_secret:
type: boolean
has_password:
type: boolean
has_totp:
type: boolean
has_oauth:
type: boolean
password_hint:
type: string
required:
- id
- credential_ref
- project
- name
- websites
- username_secret_enabled
- has_username_secret
- has_password
- has_totp
- has_oauth
additionalProperties: false
UpdateSecretRequest:
type: object
properties:
kind:
$ref: '#/components/schemas/SecretKind'
metadata:
$ref: '#/components/schemas/WebsiteCredentialMetadataUpdate'
secret:
$ref: '#/components/schemas/WebsiteCredentialSecretInput'
clear_username_secret:
type: boolean
clear_password:
type: boolean
clear_totp:
type: boolean
clear_oauth:
type: boolean
additionalProperties: false
WebsiteCredentialSecretInput:
type: object
properties:
username:
type: string
description: Optional encrypted username. Prefer metadata.username unless the username itself is sensitive.
password:
type: string
totp:
type: object
properties:
seed:
type: string
algorithm:
$ref: '#/components/schemas/WebsiteCredentialTotpAlgorithm'
digits:
type: number
enum:
- 6
- 8
period:
type: number
issuer:
type: string
account:
type: string
required:
- seed
additionalProperties: false
oauth:
type: object
properties:
provider_id:
type: string
token_owner:
type: string
enum:
- user
- project
token_ref:
type: string
additionalProperties: false
description: Future OAuth materialization hook. The token itself remains in the OAuth secret store.
additionalProperties: false
WebsiteCredentialMetadata:
type: object
properties:
name:
type: string
websites:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialWebsite'
username:
type: string
username_hint:
type: string
username_secret:
type: boolean
properties:
type: object
additionalProperties: true
tags:
type: array
items:
type: string
enabled:
type: boolean
capabilities:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialCapability'
notes:
type: string
totp:
$ref: '#/components/schemas/WebsiteCredentialTotpMetadata'
expires_at:
type: string
description: Optional ISO timestamp after which the credential is no longer usable. Expired credentials are hidden from lookup and cannot be filled.
required:
- name
- websites
additionalProperties: false
WebsiteCredentialCapability:
type: string
enum:
- password
- totp
- oauth
DeleteSecretResponse:
type: object
properties:
ok:
type: boolean
required:
- ok
additionalProperties: false
WebsiteCredentialTotpAlgorithm:
type: string
enum:
- SHA1
- SHA256
- SHA512
SecretKind:
type: string
const: website_credential
ListSecretsResponse:
type: object
properties:
secrets:
type: array
items:
$ref: '#/components/schemas/SecretRecord'
required:
- secrets
additionalProperties: false
WebsiteCredentialFillRequest:
type: object
properties:
username_target_id:
type: string
password_target_id:
type: string
totp_target_id:
type: string
submit_target_id:
type: string
browser_workflow_id:
type: string
description: Browser-use parent workflow id. The API resolves the Daytona sandbox and observes the current page server-side before decrypting the credential.
required:
- browser_workflow_id
additionalProperties: false
SecretRecord:
type: object
properties:
id:
type: string
secret_ref:
type: string
kind:
$ref: '#/components/schemas/SecretKind'
project:
type: string
name:
type: string
enabled:
type: boolean
tags:
type: array
items:
type: string
properties:
type: object
additionalProperties: true
created_at:
type: string
updated_at:
type: string
details:
$ref: '#/components/schemas/WebsiteCredentialRecord'
required:
- id
- secret_ref
- kind
- project
- name
additionalProperties: false
ErrorResponse:
type: object
description: Standard JSON error response returned by the server error handler.
properties:
error:
type: string
description: HTTP status text or normalized error type.
status:
type: integer
format: int32
minimum: 400
maximum: 599
description: HTTP status code. Client errors use a 4xx status code; server errors use 500.
example: 400
message:
type: string
description: Human-readable error message.
details:
type: string
description: Optional additional error details.
errorCode:
type: string
description: Machine-readable code for the specific failure, present when the error carries one, so clients can branch on it without parsing `message`.
example: account_api_key_creation_disabled
required:
- error
- status
additionalProperties: false
WebsiteCredentialMetadataUpdate:
type: object
properties:
name:
type: string
websites:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialWebsite'
username:
type: string
username_hint:
type: string
username_secret:
type: boolean
properties:
type: object
additionalProperties: true
tags:
type: array
items:
type: string
enabled:
type: boolean
capabilities:
type: array
items:
$ref: '#/components/schemas/WebsiteCredentialCapability'
notes:
type: string
totp:
$ref: '#/components/schemas/WebsiteCredentialTotpMetadata'
expires_at:
type: string
description: Optional ISO timestamp after which the credential is no longer usable. Expired credentials are hidden from lookup and cannot be filled.
additionalProperties: false
WebsiteCredentialTotpMetadata:
type: object
properties:
algorithm:
$ref: '#/components/schemas/WebsiteCredentialTotpAlgorithm'
digits:
type: number
enum:
- 6
- 8
period:
type: number
issuer:
type: string
account:
type: string
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://cloud.us1.vertesia.io/oauth/authorize
tokenUrl: https://sts.vertesia.io/oauth/token
x-scalar-security-query:
resource: https://api.us1.vertesia.io/api/v1
x-scalar-security-body:
resource: https://api.us1.vertesia.io/api/v1
scopes:
openid: ''
profile: ''
offline_access: ''
interaction:read: ''
interaction:write: ''
interaction:delete: ''
interaction:execute: ''
run:read: ''
run:write: ''
environment:admin: ''
app:manage: ''
project:admin: ''
project:integration_read: ''
project:settings_write: ''
api_key:read: ''
account:read: ''
account:write: ''
account:admin: ''
audit:read: ''
account:member: ''
content:read: ''
content:read_all: ''
content:write: ''
content:delete: ''
content:admin: ''
content:superadmin: ''
workflow:read: ''
workflow:run: ''
workflow:admin: ''
workflow:superadmin: ''
agent_run:read: ''
task:read: ''
task:manage: ''
x-tagGroups:
- name: Authentication
tags:
- Token Service
- name: GenAI
tags:
- Environments
- Prompt Templates
- Interactions
- Interaction Runs
- Agent Runs
- name: Content
tags:
- Content Object Types
- Objects
- Collections
- Files
- Rendering
- Bulk Operations
- Commands
- name: Data Store
tags:
- Data
- name: Workflow
tags:
- Processes
- Tasks
- Workflow Definitions
- Workflow Rules
- Workflow Runs
- name: Administration
tags:
- Accounts
- Projects
- Audit Trail
- Costs
- name: Access Control
tags:
- Users
- User Groups
- Roles
- Access Control Entries
- API Keys
- name: Apps & Integrations
tags:
- Apps
- OAuth Providers
- OAuth Clients
- OAuth Grants
- Remote MCP Connections