Vertesia

Vertesia Secrets API

The Secrets API from Vertesia — 3 operation(s) for secrets.

GitHub OpenAPI

Operations 6

GET /secrets List secrets #
POST /secrets Create secret #
GET /secrets/{secretId} Retrieve secret metadata #
PUT /secrets/{secretId} Update secret #
DELETE /secrets/{secretId} Delete secret #
POST /secrets/{secretId}/actions/fill-browser Fill website credential into a browser-use sandbox #

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/openapi/vertesiahq-secrets-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-agent-run-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-update-app-payload-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-app-manifest-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-app-manifest-data-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-indexing-status-response-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/vertesiahq/refs/heads/main/json-schema/vertesiahq-dashboard-schema.json

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.
All 92 tools →

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"

Discovery needs no key. Ratings and market analysis are Pro.

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

vertesiahq-secrets-api-openapi.yml Raw ↑ 
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