Terminal Use Secrets API

openapi: 3.1.0
info:
  title: Sb0 Agent APIKeys Secrets API
  version: 0.1.0
tags:
- name: Secrets
paths:
  /agents/{namespace_slug}/{agent_name}/environments/{env_name}/secrets:
    get:
      description: "List PENDING secrets for an environment (from EnvVar table).\n\n    This is what will be used on next deploy.\n    For deployed state, use GET /agents/{namespace_slug}/{agent_name}/environments/{env}/secrets/deployed\n\n    Note: is_secret=True values are NEVER returned, only non-secrets when include_values=True."
      operationId: agents_environments_secrets_list
      parameters:
      - in: path
        name: namespace_slug
        required: true
        schema:
          title: Namespace Slug
          type: string
      - in: path
        name: agent_name
        required: true
        schema:
          title: Agent Name
          type: string
      - in: path
        name: env_name
        required: true
        schema:
          title: Env Name
          type: string
      - description: Include values for non-secrets (is_secret=False only)
        in: query
        name: include_values
        required: false
        schema:
          default: false
          description: Include values for non-secrets (is_secret=False only)
          title: Include Values
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvVarListResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Pending Secrets for Environment
      tags:
      - Secrets
      x-fern-sdk-group-name:
      - agents
      - environments
      - secrets
      x-fern-sdk-method-name: list
    put:
      description: "Set one or more secrets/config values.\n\n    If redeploy=True (default) and environment has active deployment,\n    triggers redeploy with same image but new secrets_snapshot."
      operationId: agents_environments_secrets_set
      parameters:
      - in: path
        name: namespace_slug
        required: true
        schema:
          title: Namespace Slug
          type: string
      - in: path
        name: agent_name
        required: true
        schema:
          title: Agent Name
          type: string
      - in: path
        name: env_name
        required: true
        schema:
          title: Env Name
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEnvVarRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetEnvVarResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Set Secrets
      tags:
      - Secrets
      x-fern-sdk-group-name:
      - agents
      - environments
      - secrets
      x-fern-sdk-method-name: set
  /agents/{namespace_slug}/{agent_name}/environments/{env_name}/secrets/deployed:
    get:
      description: "List DEPLOYED secrets for an environment (from Version.secrets_snapshot).\n\n    This is what's currently running. May differ from pending state after rollback.\n    Only returns keys, never actual values."
      operationId: agents_environments_secrets_list_deployed
      parameters:
      - in: path
        name: namespace_slug
        required: true
        schema:
          title: Namespace Slug
          type: string
      - in: path
        name: agent_name
        required: true
        schema:
          title: Agent Name
          type: string
      - in: path
        name: env_name
        required: true
        schema:
          title: Env Name
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeployedSecretsResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Deployed Secrets for Environment
      tags:
      - Secrets
      x-fern-sdk-group-name:
      - agents
      - environments
      - secrets
      x-fern-sdk-method-name: list_deployed
  /agents/{namespace_slug}/{agent_name}/environments/{env_name}/secrets/{key}:
    delete:
      description: "Delete a secret from an environment.\n\n    If redeploy=True (default), triggers redeploy with updated secrets."
      operationId: agents_environments_secrets_delete
      parameters:
      - in: path
        name: namespace_slug
        required: true
        schema:
          title: Namespace Slug
          type: string
      - in: path
        name: agent_name
        required: true
        schema:
          title: Agent Name
          type: string
      - in: path
        name: env_name
        required: true
        schema:
          title: Env Name
          type: string
      - in: path
        name: key
        required: true
        schema:
          title: Key
          type: string
      - description: If true, trigger redeploy after deletion
        in: query
        name: redeploy
        required: false
        schema:
          default: true
          description: If true, trigger redeploy after deletion
          title: Redeploy
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteEnvVarResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete Secret
      tags:
      - Secrets
      x-fern-sdk-group-name:
      - agents
      - environments
      - secrets
      x-fern-sdk-method-name: delete
  /agents/{namespace_slug}/{agent_name}/secrets:
    get:
      description: "Cross-environment view of all secrets for an agent.\n\n    Shows which keys exist in which environments.\n    Never returns actual secret values (is_secret=True).\n    Values for non-secrets only returned when include_values=True."
      operationId: agents_secrets_list
      parameters:
      - in: path
        name: namespace_slug
        required: true
        schema:
          title: Namespace Slug
          type: string
      - in: path
        name: agent_name
        required: true
        schema:
          title: Agent Name
          type: string
      - description: Include values for non-secrets (is_secret=False only)
        in: query
        name: include_values
        required: false
        schema:
          default: false
          description: Include values for non-secrets (is_secret=False only)
          title: Include Values
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossEnvSecretsListResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List Secrets Across Environments
      tags:
      - Secrets
      x-fern-sdk-group-name:
      - agents
      - secrets
      x-fern-sdk-method-name: list
components:
  schemas:
    EnvVarResponse:
      description: Response model for a single environment variable.
      properties:
        created_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Creation timestamp
          title: Created At
        env_id:
          description: Environment ID
          title: Env Id
          type: string
        id:
          description: Unique identifier
          title: Id
          type: string
        is_secret:
          description: Whether value is write-only
          title: Is Secret
          type: boolean
        key:
          description: Variable key
          title: Key
          type: string
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Last update timestamp
          title: Updated At
        value:
          anyOf:
          - type: string
          - type: 'null'
          description: Decrypted value (only for non-secrets when requested)
          title: Value
      required:
      - id
      - env_id
      - key
      - is_secret
      title: EnvVarResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
      type: object
    EnvVarListResponse:
      description: Response for listing environment variables.
      properties:
        env_vars:
          description: List of environment variables
          items:
            $ref: '#/components/schemas/EnvVarResponse'
          title: Env Vars
          type: array
        state:
          default: pending
          description: Indicates this is pending state (vs deployed). Pending = what will be used on next deploy. Deployed = what's currently running (from Version.secrets_snapshot).
          title: State
          type: string
      required:
      - env_vars
      title: EnvVarListResponse
      type: object
    SetEnvVarResponse:
      description: Response after setting environment variables.
      properties:
        count:
          description: Number of variables set
          title: Count
          type: integer
        redeployed:
          default: false
          description: Whether a redeploy was triggered
          title: Redeployed
          type: boolean
        updated:
          description: Keys that were set
          items:
            type: string
          title: Updated
          type: array
        version_id:
          anyOf:
          - type: string
          - type: 'null'
          description: New version ID if redeployed
          title: Version Id
      required:
      - updated
      - count
      title: SetEnvVarResponse
      type: object
    SetEnvVarRequest:
      description: "Request to set environment variable(s).\n\nMatches design spec (deployment-addendum-rollback-and-envvars.md):\n{\n    \"secrets\": {\n        \"OPENAI_API_KEY\": {\"value\": \"sk-xxx\", \"is_secret\": true},\n        \"LOG_LEVEL\": {\"value\": \"debug\", \"is_secret\": false}\n    },\n    \"redeploy\": true\n}"
      properties:
        redeploy:
          default: true
          description: If true and env has active deployment, trigger redeploy with new secrets
          title: Redeploy
          type: boolean
        secrets:
          additionalProperties:
            $ref: '#/components/schemas/EnvVarValue'
          description: 'Dict of {key: {value, is_secret}} to set'
          examples:
          - LOG_LEVEL:
              is_secret: false
              value: debug
            OPENAI_API_KEY:
              is_secret: true
              value: sk-xxx
          title: Secrets
          type: object
      required:
      - secrets
      title: SetEnvVarRequest
      type: object
    CrossEnvSecretsListResponse:
      description: Cross-environment secrets view.
      properties:
        all_environments:
          description: All environment names for the agent
          items:
            type: string
          title: All Environments
          type: array
        variables:
          description: All secret keys across environments
          items:
            $ref: '#/components/schemas/CrossEnvSecretResponse'
          title: Variables
          type: array
      required:
      - variables
      - all_environments
      title: CrossEnvSecretsListResponse
      type: object
    EnvVarValue:
      description: Value with is_secret flag for setting environment variables.
      properties:
        is_secret:
          default: true
          description: If true, value is write-only via API (cannot retrieve). If false, value can be read back via API.
          title: Is Secret
          type: boolean
        value:
          description: The plaintext value to encrypt and store
          title: Value
          type: string
      required:
      - value
      title: EnvVarValue
      type: object
    DeployedSecretsResponse:
      description: Response for deployed secrets (from Version.secrets_snapshot).
      properties:
        deployed_at:
          description: When this version was deployed
          format: date-time
          title: Deployed At
          type: string
        secrets:
          description: List of secret keys (no values)
          items:
            $ref: '#/components/schemas/DeployedSecretKey'
          title: Secrets
          type: array
        state:
          default: deployed
          description: Always 'deployed' for this response
          title: State
          type: string
        version_id:
          description: Version ID this snapshot came from
          title: Version Id
          type: string
      required:
      - secrets
      - version_id
      - deployed_at
      title: DeployedSecretsResponse
      type: object
    DeleteEnvVarResponse:
      description: Response after deleting an environment variable.
      properties:
        deleted:
          description: Whether the variable was deleted
          title: Deleted
          type: boolean
        key:
          description: The key that was deleted
          title: Key
          type: string
        redeployed:
          default: false
          description: Whether a redeploy was triggered
          title: Redeployed
          type: boolean
        version_id:
          anyOf:
          - type: string
          - type: 'null'
          description: New version ID if redeployed
          title: Version Id
      required:
      - deleted
      - key
      title: DeleteEnvVarResponse
      type: object
    CrossEnvSecretResponse:
      description: A secret key across all environments.
      properties:
        environments:
          description: List of environments containing this key
          items:
            $ref: '#/components/schemas/EnvSecretInfo'
          title: Environments
          type: array
        is_secret:
          description: Whether this is a secret
          title: Is Secret
          type: boolean
        key:
          description: Secret key name
          title: Key
          type: string
        value:
          anyOf:
          - type: string
          - type: 'null'
          description: Value for non-secrets (is_secret=False) only. Always None for secrets.
          title: Value
      required:
      - key
      - is_secret
      - environments
      title: CrossEnvSecretResponse
      type: object
    EnvSecretInfo:
      description: Secret presence in one environment.
      properties:
        env_name:
          description: Environment name
          title: Env Name
          type: string
        is_secret:
          description: Whether this is a secret in this environment
          title: Is Secret
          type: boolean
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: Last update timestamp
          title: Updated At
        value:
          anyOf:
          - type: string
          - type: 'null'
          description: Value for non-secrets (is_secret=False) only. Always None for secrets.
          title: Value
      required:
      - env_name
      - is_secret
      title: EnvSecretInfo
      type: object
    DeployedSecretKey:
      description: A key from deployed secrets snapshot.
      properties:
        is_secret:
          default: true
          description: Whether this is a secret. Derived from snapshot metadata.
          title: Is Secret
          type: boolean
        key:
          description: Secret key name
          title: Key
          type: string
      required:
      - key
      title: DeployedSecretKey
      type: object
x-fern-idempotency-headers:
- header: Idempotency-Key
  name: idempotency_key