openapi: 3.1.0
info:
  title: Computer-Use Agents Vaults API
  version: 1.0.0
servers:
- url: https://agp.eu.hcompany.ai
  description: Europe
  x-fern-server-name: Eu
- url: https://agp.hcompany.ai
  description: United States
  x-fern-server-name: Us
tags:
- name: Vaults
paths:
  /api/v2/vaults:
    post:
      tags:
      - Vaults
      summary: Create Vault
      description: Create a vault config. The provider token is validated by env-manager before storage.
      operationId: create_vault_api_v2_vaults_post
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConfigRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Vaults
      summary: List Vaults
      description: List the caller's org vault configs.
      operationId: list_vaults_api_v2_vaults_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConfigList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/vaults/{vault_id}:
    get:
      tags:
      - Vaults
      summary: Get Vault
      description: Fetch a vault config by id.
      operationId: get_vault_api_v2_vaults__vault_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConfigRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Vaults
      summary: Update Vault
      description: Partial update of a vault config (name and/or provider_config).
      operationId: update_vault_api_v2_vaults__vault_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Vault Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultConfigRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Vaults
      summary: Delete Vault
      description: Delete a vault config.
      operationId: delete_vault_api_v2_vaults__vault_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Vault Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/vaults/{vault_id}/token:
    put:
      tags:
      - Vaults
      summary: Rotate Vault Token
      description: Rotate the stored provider token. env-manager health-checks it before writing.
      operationId: rotate_vault_token_api_v2_vaults__vault_id__token_put
      security:
      - HTTPBearer: []
      parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Vault Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultTokenRotateRequest'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/vaults/{vault_id}/health:
    get:
      tags:
      - Vaults
      summary: Vault Health
      description: Probe the vault's provider. Always 200 when reachable; branch on ``ok``.
      operationId: vault_health_api_v2_vaults__vault_id__health_get
      security:
      - HTTPBearer: []
      parameters:
      - name: vault_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Vault Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultHealth'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OnePasswordConfig:
      properties:
        provider:
          type: string
          const: onepassword
          title: Provider
          default: onepassword
        op_vault_id:
          type: string
          title: Op Vault Id
      type: object
      required:
      - op_vault_id
      title: OnePasswordConfig
      description: 1Password vault provider config.
    VaultCreateRequest:
      properties:
        name:
          type: string
          title: Name
        provider_config:
          $ref: '#/components/schemas/OnePasswordConfig'
        token:
          type: string
          format: password
          title: Token
          writeOnly: true
      type: object
      required:
      - name
      - provider_config
      - token
      title: VaultCreateRequest
      description: Request body for creating a vault config.
    VaultConfigRead:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        org_id:
          type: string
          format: uuid
          title: Org Id
        name:
          type: string
          title: Name
        provider_config:
          $ref: '#/components/schemas/OnePasswordConfig'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - org_id
      - name
      - provider_config
      - created_at
      - updated_at
      title: VaultConfigRead
      description: Response model for a vault config. Never includes the stored token.
    VaultUpdateRequest:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        provider_config:
          anyOf:
          - $ref: '#/components/schemas/OnePasswordConfig'
          - type: 'null'
      type: object
      title: VaultUpdateRequest
      description: Partial update; only provided fields are forwarded. Token rotation is separate.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VaultHealth:
      properties:
        ok:
          type: boolean
          title: Ok
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      required:
      - ok
      title: VaultHealth
      description: Result of a provider health check. The API always returns 200; branch on ``ok``.
    VaultTokenRotateRequest:
      properties:
        token:
          type: string
          format: password
          title: Token
          writeOnly: true
      type: object
      required:
      - token
      title: VaultTokenRotateRequest
      description: Request body for rotating a vault's stored provider token.
    VaultConfigList:
      properties:
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        vaults:
          items:
            $ref: '#/components/schemas/VaultConfigRead'
          type: array
          title: Vaults
      type: object
      required:
      - total
      - limit
      - offset
      - vaults
      title: VaultConfigList
      description: Response model for listing vault configs.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer