openapi: 3.0.0
info:
  title: AI Hub Audit Secrets API
  version: '0.1'
  description: The AI Hub REST API. See https://docs.instabase.com/api-sdk/ for more details.
  termsOfService: https://www.instabase.com/terms-of-service/
  contact:
    name: Instabase Support
    url: https://help.instabase.com/
  license:
    name: MIT
    url: https://github.com/instabase/aihub-python/blob/master/LICENSE
servers:
- url: https://aihub.instabase.com/api
security:
- bearerAuth: []
tags:
- name: Secrets
paths:
  /v2/aihub/secrets:
    get:
      operationId: listSecrets
      x-fern-audiences:
      - public
      tags:
      - Secrets
      summary: List secrets
      description: '<span class="badge">Commercial & Enterprise</span>


        List secrets available to the organization, available to a given workspace, or with a given alias.


        <Note>Only organization admins can list all secrets in the organization. Non-admins must specify a workspace.</Note>

        '
      parameters:
      - $ref: '#/components/parameters/ib_context'
      - in: query
        name: workspace
        schema:
          type: string
        description: 'Show secrets available in the specified workspace.


          <Info>Only members of a workspace can access secrets that are available within that workspace.</Info>

          '
      - in: query
        name: alias
        schema:
          type: string
        description: 'Get the secret with the specified alias.

          '
      responses:
        '200':
          description: A list of secrets.
          content:
            application/json:
              schema:
                type: object
                properties:
                  secrets:
                    type: array
                    items:
                      $ref: '#/components/schemas/secret'
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-fern-examples:
      - code-samples:
        - sdk: curl
          code: "curl \"${API_ROOT}/v2/aihub/secrets?workspace=<WORKSPACE>\" \\\n  -H \"Authorization: Bearer ${API_TOKEN}\" \\\n  -H \"IB-Context: ${IB_CONTEXT}\"\n"
        - sdk: python
          name: with SDK
          code: "from aihub import AIHub\n\nclient = AIHub(\n    api_root=\"https://aihub.instabase.com/api\",\n    api_key=\"abcdefghijklmnopqrst1234567890\",\n    ib_context=\"john.doe_acme.com\"\n)\n\nresponse = client.secrets.list(workspace=\"MyWorkspace\")\n\nfor secret in response.secrets:\n    print(f\"Secret description: {secret.description}\")\n"
        - sdk: python
          name: without SDK
          code: "import requests\n\nurl = \"https://aihub.instabase.com/api/v2/aihub/secrets\"\n\nheaders = {\n    \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n    \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create query parameters\nparams = {\"workspace\": \"MyWorkspace\"}\n\n# make the GET request\nresponse = requests.get(url, headers=headers, params=params)\n\n# handle the response\nif response.status_code == 200:\n    for secret in response.json()['secrets']:\n        print(f\"Secret description: {secret['description']}\")\nelse:\n    print(f\"Error: {response.status_code} - {response.text}\")\n"
    post:
      operationId: createSecret
      x-fern-audiences:
      - public
      tags:
      - Secrets
      summary: Create secret
      description: '<span class="badge">Commercial & Enterprise</span>


        Create a new secret in this organization.


        <Note>Only organization admins can create secrets.</Note>

        '
      parameters:
      - $ref: '#/components/parameters/ib_context'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  type: string
                  description: Name of the secret.
                description:
                  type: string
                  description: Description of the secret.
                value:
                  type: string
                  description: Content of the secret.
                allowed_workspaces_type:
                  type: string
                  description: Which workspaces in this organization are allowed to use this secret in custom functions.
                  enum:
                  - ALL
                  - SOME
                  - NONE
                allowed_workspaces:
                  type: array
                  description: Which workspaces are allowed to use this secret, if only some are allowed. Required when `allowed_workspaces_type` is `SOME`, otherwise ignored.
                  items:
                    type: string
              required:
              - alias
              - value
              - allowed_workspaces_type
      responses:
        '200':
          description: Secret created successfully.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-fern-examples:
      - code-samples:
        - sdk: curl
          code: "curl -X POST \"${API_ROOT}/v2/aihub/secrets\" \\\n  -H \"Authorization: Bearer ${API_TOKEN}\" \\\n  -H \"IB-Context: ${IB_CONTEXT}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"alias\": \"my_secret\",\n        \"description\": \"Sample secret\",\n        \"value\": \"my password\",\n        \"allowed_workspaces_type\": \"SOME\",\n        \"allowed_workspaces\": [\"workspace1\", \"workspace2\"]\n      }'\n"
        - sdk: python
          name: with SDK
          code: "from aihub import AIHub\n\nclient = AIHub(\n    api_root=\"https://aihub.instabase.com/api\",\n    api_key=\"abcdefghijklmnopqrst1234567890\",\n    ib_context=\"john.doe_acme.com\"\n)\n\n# returns None\nclient.secrets.create(\n    alias=\"my_secret\",\n    description=\"Sample secret\",\n    value=\"my password\",\n    allowed_workspaces_type=\"SOME\",\n    allowed_workspaces=[\"workspace1\", \"workspace2\"]\n)\n"
        - sdk: python
          name: without SDK
          code: "import requests\n\nurl = \"https://aihub.instabase.com/api/v2/aihub/secrets\"\n\nheaders = {\n    \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n    \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create the request payload\ndata = {\n    \"alias\": \"my_secret\",\n    \"description\": \"Sample secret\",\n    \"value\": \"my password\",\n    \"allowed_workspaces_type\": \"SOME\",\n    \"allowed_workspaces\": [\"workspace1\", \"workspace2\"]\n}\n\n# make the POST request\nresponse = requests.post(url, headers=headers, json=data)\n\n# handle the response\nif response.status_code == 200:\n    print(\"Secret created successfully\")\nelse:\n    print(f\"Error: {response.status_code} - {response.text}\")\n"
    patch:
      operationId: updateSecret
      x-fern-audiences:
      - public
      tags:
      - Secrets
      summary: Update secret
      description: '<span class="badge">Commercial & Enterprise</span>


        Update the description, value, or allowed workspaces for a secret. If a value for a parameter is not specified, it will remain the same.


        <Note>Only organization admins can update secrets.</Note>

        '
      parameters:
      - $ref: '#/components/parameters/ib_context'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  type: string
                  description: Name of the secret to update.
                description:
                  type: string
                  description: New description of the secret.
                value:
                  type: string
                  description: New content of the secret.
                allowed_workspaces_type:
                  type: string
                  description: New designation of which workspaces in this organization are allowed to use this secret in custom functions.
                  enum:
                  - ALL
                  - SOME
                  - NONE
                allowed_workspaces:
                  type: array
                  description: New designation of which workspaces are allowed to use this secret, if only some are.
                  items:
                    type: string
              required:
              - alias
      responses:
        '200':
          description: Secret updated successfully.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-fern-examples:
      - code-samples:
        - sdk: curl
          code: "curl -X PATCH \"${API_ROOT}/v2/aihub/secrets\" \\\n  -H \"Authorization: Bearer ${API_TOKEN}\" \\\n  -H \"IB-Context: ${IB_CONTEXT}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"alias\": \"my_secret\",\n        \"value\": \"new password\",\n        \"allowed_workspaces_type\": \"ALL\"\n      }'\n"
        - sdk: python
          name: Simple request with SDK
          code: "from aihub import AIHub\n\nclient = AIHub(\n    api_root=\"https://aihub.instabase.com/api\",\n    api_key=\"abcdefghijklmnopqrst1234567890\",\n    ib_context=\"john.doe_acme.com\"\n)\n\n# returns None\nclient.secrets.update(alias=\"password\", value=\"abc123\")\n"
        - sdk: python
          name: Simple request without SDK
          code: "import requests\n\nurl = \"https://aihub.instabase.com/api/v2/aihub/secrets\"\n\nheaders = {\n    \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n    \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create the request payload\ndata = {\n    \"alias\": \"password\",\n    \"value\": \"abc123\"\n}\n\n# make the PATCH request\nresponse = requests.patch(url, headers=headers, json=data)\n\n# handle the response\nif response.status_code == 200:\n    print(\"Secret updated successfully\")\nelse:\n    print(f\"Error: {response.status_code} - {response.text}\")\n"
        - sdk: python
          name: Advanced request with SDK
          code: "from aihub import AIHub\n\nclient = AIHub(\n    api_root=\"https://aihub.instabase.com/api\",\n    api_key=\"abcdefghijklmnopqrst1234567890\",\n    ib_context=\"john.doe_acme.com\")\n\n# returns None\nclient.secrets.update(\n    alias=\"password\",\n    description=\"password\",\n    value=\"abc123\",\n    allowed_workspaces_type=\"SOME\",\n    allowed_workspaces=[\"WorkspaceA\", \"WorkspaceB\"]\n)\n"
        - sdk: python
          name: Advanced request without SDK
          code: "import requests\n\nurl = \"https://aihub.instabase.com/api/v2/aihub/secrets\"\n\nheaders = {\n    \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n    \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create the request payload\ndata = {\n    \"alias\": \"password\",\n    \"value\": \"abc123\",\n    \"allowed_workspaces_type\": \"SOME\",\n    \"allowed_workspaces\": [\"WorkspaceA\", \"WorkspaceB\"]\n}\n\n# make the PATCH request\nresponse = requests.patch(url, headers=headers, json=data)\n\n# handle the response\nif response.status_code == 200:\n    print(\"Secret updated successfully\")\nelse:\n    print(f\"Error: {response.status_code} - {response.text}\")\n"
    delete:
      operationId: deleteSecret
      x-fern-audiences:
      - public
      tags:
      - Secrets
      summary: Delete secret
      description: '<span class="badge">Commercial & Enterprise</span>


        Delete a secret from the organization.


        <Note>Only organization admins can delete secrets.</Note>

        '
      parameters:
      - $ref: '#/components/parameters/ib_context'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                alias:
                  type: string
                  description: Name of the secret to delete.
              required:
              - alias
      responses:
        '200':
          description: Secret deleted successfully.
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-fern-examples:
      - code-samples:
        - sdk: curl
          code: "curl -X DELETE \"${API_ROOT}/v2/aihub/secrets\" \\\n  -H \"Authorization: Bearer ${API_TOKEN}\" \\\n  -H \"IB-Context: ${IB_CONTEXT}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"alias\": \"my_secret\"\n      }'\n"
        - sdk: python
          name: with SDK
          code: "from aihub import AIHub\n\nclient = AIHub(\n    api_root=\"https://aihub.instabase.com/api\",\n    api_key=\"abcdefghijklmnopqrst1234567890\",\n    ib_context=\"john.doe_acme.com\"\n)\n\n# returns None\nclient.secrets.delete(alias=\"password\")\n"
        - sdk: python
          name: without SDK
          code: "import requests\n\nurl = \"https://aihub.instabase.com/api/v2/aihub/secrets\"\n\nheaders = {\n    \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n    \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create the request payload\ndata = {\"alias\": \"password\"}\n\n# make the DELETE request\nresponse = requests.delete(url, headers=headers, json=data)\n\n# handle the response\nif response.status_code == 200:\n    print(\"Secret deleted successfully\")\nelse:\n    print(f\"Error: {response.status_code} - {response.text}\")\n"
components:
  parameters:
    ib_context:
      in: header
      name: IB-Context
      schema:
        type: string
      required: false
      description: Specify whether to use your community account or organization account to complete the request. To use your community account, define as your user ID. To use your organization account, define as your organization ID. If unspecified, defaults to community account context. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) for details.
  schemas:
    secret:
      type: object
      properties:
        alias:
          type: string
          description: Name of the secret.
        description:
          type: string
          description: Description of the secret.
        allowed_workspaces_type:
          type: string
          description: Which workspaces in this organization are allowed to use this secret in custom functions.
          enum:
          - ALL
          - SOME
          - NONE
        allowed_workspaces:
          type: array
          description: Which workspaces are allowed to use this secret, if only some are allowed.
          items:
            type: string
        org:
          type: string
          description: The organization name in which this secret was created.
        created_at:
          type: number
          description: When the secret was created in Unix time milliseconds.
        created_by:
          type: string
          description: The user ID of the user who created the secret.
        updated_at:
          type: number
          description: When the secret was last updated in Unix time milliseconds.
        last_updated_by:
          type: string
          description: The user ID of the user who last edited the secret.
    error:
      type: object
      properties:
        message:
          type: string
  securitySchemes:
    bearerAuth:
      bearerFormat: auth-scheme
      description: Bearer HTTP authentication.
      scheme: bearer
      type: http