openapi: 3.1.0
info:
  title: Streamlit Community Cloud Apps Secrets API
  description: The Streamlit Community Cloud API provides programmatic access to manage Streamlit applications hosted on Community Cloud. Developers can use this API to deploy apps from GitHub repositories, manage app secrets, view deployment logs, restart apps, and manage workspace settings. Authentication uses Streamlit-issued API tokens.
  version: 1.0.0
  contact:
    name: Streamlit Support
    url: https://discuss.streamlit.io
  termsOfService: https://streamlit.io/terms-of-use
servers:
- url: https://api.streamlit.io/v1
  description: Streamlit Community Cloud API
security:
- streamlitBearerAuth: []
tags:
- name: Secrets
  description: Manage secrets for Streamlit applications. Secrets are environment variables securely injected into the application at runtime via st.secrets.
paths:
  /apps/{appId}/secrets:
    get:
      operationId: getAppSecrets
      summary: Get App Secrets
      description: Returns the secret keys (not values) configured for a Streamlit application. Secret values are never returned via the API for security.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: The app secret keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  secrets:
                    type: array
                    items:
                      type: string
                    description: List of secret key names (values not included)
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateAppSecrets
      summary: Update App Secrets
      description: Replaces all secrets for a Streamlit application. Secrets are provided as a TOML-formatted string and are made available in the app via st.secrets. Updating secrets automatically restarts the application.
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecretsUpdateRequest'
      responses:
        '200':
          description: Secrets updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: The error code
        message:
          type: string
          description: A human-readable error message
    SecretsUpdateRequest:
      type: object
      required:
      - secrets
      properties:
        secrets:
          type: string
          description: 'Secrets in TOML format. Example: api_key = "your_key_here" or nested: [database]\nhost = "localhost"\npassword = "secret"'
  responses:
    Unauthorized:
      description: Unauthorized — invalid or missing API token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AppId:
      name: appId
      in: path
      required: true
      description: The unique identifier of the Streamlit app
      schema:
        type: string
  securitySchemes:
    streamlitBearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token issued from the Streamlit Community Cloud account settings. Include as Authorization: Bearer {token}.'
externalDocs:
  description: Streamlit Community Cloud Documentation
  url: https://docs.streamlit.io/deploy/streamlit-community-cloud