openapi: 3.1.0
info:
  contact:
    email: support@cloudquery.io
    name: CloudQuery Support Team
    url: https://cloudquery.io
  description: 'Welcome to the CloudQuery Platform API documentation! This API can be used to interact with the CloudQuery platform. As a user, the API allows you to search the CloudQuery asset inventory, run SQL queries against the data warehouse, save and load searches, and much more. As an administrator, it allows you to manage your teams, syncs, and other objects.

    ### Authentication

    The API is secured using bearer tokens. To get started, you can generate an API key for your Platform deployment from your platform dashboard. For a step-by-step guide, see: https://www.cloudquery.io/docs/cli/managing-cloudquery/deployments/generate-api-key.

    The base URL for the API depends on where your CloudQuery Platform is hosted. If running locally, this is usually http://localhost:3000/api. In a production deployment it should be an HTTPS URL. For purposes of illustration, we will assume the platform instance is available at https://cloudquery.mycompany.com. In this case, the base API endpoint will be https://cloudquery.mycompany.com/api.

    ### Example Request

    To test your connection to the API, we can use the `/plugins` endpoint. For example:

    `curl -v -H "Authorization: Bearer $CLOUDQUERY_API_KEY" \ https://cloudquery.mycompany.com/api/plugins`

    '
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://www.cloudquery.io/terms
  title: CloudQuery Platform OpenAPI Spec admin apps API
  version: 1.0.0
security:
- bearerAuth: []
- cookieAuth: []
tags:
- name: apps
paths:
  /apps/upsert-by-name:
    post:
      description: Idempotently upsert a list of apps by name within the caller's tenant. For each name, returns its existing app id (if the name already exists) or a freshly-generated one (if newly created). Duplicate names in the request are deduplicated server-side. Intended primarily for service-to-service use from accessory writers that materialize app memberships.
      operationId: PlatformUpsertAppsByName
      tags:
      - apps
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - names
              properties:
                names:
                  type: array
                  description: List of app names to upsert. Each name must be non-empty.
                  items:
                    type: string
                    minLength: 1
                  minItems: 1
      responses:
        '200':
          description: Apps upserted; existing rows returned alongside any newly created.
          content:
            application/json:
              schema:
                type: object
                required:
                - apps
                properties:
                  apps:
                    type: array
                    items:
                      type: object
                      required:
                      - name
                      - id
                      properties:
                        name:
                          type: string
                        id:
                          type: string
                          format: uuid
        '400':
          $ref: '#/components/responses/PlatformBadRequest'
        '401':
          $ref: '#/components/responses/PlatformRequiresAuthentication'
        '422':
          $ref: '#/components/responses/PlatformUnprocessableEntity'
        '500':
          $ref: '#/components/responses/PlatformInternalError'
components:
  schemas:
    PlatformFieldError:
      allOf:
      - $ref: '#/components/schemas/PlatformBasicError'
      - properties:
          errors:
            items:
              type: string
            type: array
          field_errors:
            additionalProperties:
              type: string
            type: object
        type: object
    PlatformBasicError:
      additionalProperties: false
      description: Basic Error
      required:
      - message
      - status
      properties:
        message:
          type: string
        status:
          type: integer
      title: Basic Error
      type: object
  responses:
    PlatformBadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: Bad request
    PlatformRequiresAuthentication:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Requires authentication
    PlatformInternalError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformBasicError'
      description: Internal Error
    PlatformUnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PlatformFieldError'
      description: UnprocessableEntity
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http
    basicAuth:
      scheme: basic
      type: http
    cookieAuth:
      scheme: cookie
      type: http