openapi: 3.0.1
info:
  title: Ampersand public API
  version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
paths:
  /oauth-connect:
    post:
      operationId: oauthConnect
      summary: Ampersand Generate OAuth Authorization URL
      description: Generate a URL for the browser to render to kick off OAuth flow. You can use this endpoint as an alternative to the [prebuilt UI 
        components](https://docs.withampersand.com/embeddable-ui-components).
      tags: ["OAuth"]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - projectId
              - groupRef
              - consumerRef
              - provider
              properties:
                projectId:
                  type: string
                  description: The Ampersand project ID.
                  example: my-project
                provider:
                  type: string
                  description: The provider that this app connects to.
                  example: salesforce
                groupRef:
                  type: string
                  description: Your application's identifier for the organization or workspace that this connection belongs to (e.g. an org ID or team ID).
                  example: group-123
                groupName:
                  type: string
                  description: The display name for the group. Defaults to groupRef if not provided.
                  example: Organization Name
                consumerRef:
                  type: string
                  description: The ID that your app uses to identify the user whose SaaS credential will be used for this OAuth flow.
                  example: user_123456
                consumerName:
                  type: string
                  description: The display name for the consumer. Defaults to consumerRef if not provided.
                  example: John Doe
                providerWorkspaceRef:
                  type: string
                  description: The identifier for the provider workspace (e.g. the Salesforce subdomain).
                  example: acme-corp
                providerMetadata:
                  description: Additional provider-specific metadata required by certain providers (e.g., account ID for NetSuite). See provider documentation for which fields are needed.
                  $ref: "#/components/schemas/ProviderMetadata"
                  example:
                    accountId:
                      value: "1234567890"
                      source: input
                providerAppId:
                  type: string
                  description: ID of the provider app, returned from the [Create Provider App endpoint](https://docs.withampersand.com/reference/provider-apps/create-provider-app). If omitted, the 
                    default provider app that was set up on the Ampersand Dashboard is assumed.
                  example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
                enableCSRFProtection:
                  type: boolean
                  description: This boolean flag is used by the UI library internally. Set it to false or omit it when manually calling this API.
                  example: false
            examples:
              basicOAuth:
                summary: Basic OAuth flow (required fields only)
                value:
                  projectId: my-project
                  provider: salesforce
                  groupRef: group-123
                  consumerRef: user_123456
              withProviderWorkspace:
                summary: With provider workspace and provider app
                value:
                  projectId: my-project
                  provider: salesforce
                  groupRef: group-123
                  groupName: Acme Corp
                  consumerRef: user_123456
                  consumerName: John Doe
                  providerWorkspaceRef: acme-corp
                  providerAppId: 32356abe-d2fd-49c7-9030-abdcbc6456d4
              withProviderMetadata:
                summary: With provider metadata (e.g. NetSuite account ID)
                value:
                  projectId: my-project
                  provider: netsuite
                  groupRef: group-456
                  consumerRef: user_789012
                  providerMetadata:
                    accountId:
                      value: "1234567890"
                      source: input
        required: true
      responses:
        200:
          description: OK
          content:
            text/plain:
              schema:
                type: string
                description: URL to render
                example: "https://login.salesforce.com/services/oauth2/authorize?client_id=xxx&redirect_uri=https%3A%2F%2Fapi.withampersand.com%2Fcallbacks%2Fv1%2Foauth&state=xxx"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: connectOAuthParams
  /projects/{projectIdOrName}/connections/{connectionId}:oauth-update:
    patch:
      operationId: oauthUpdate
      summary: Ampersand Generate OAuth Authorization URL for Existing Connection
      description: >
        Generate a URL for the browser to render to kick off an OAuth flow that updates an existing connection. Use this when the connection's credentials need to be refreshed. To start an OAuth flow without
        specifying a connection ID, use the [/oauth-connect endpoint](https://docs.withampersand.com/reference/oauth/generate-oauth-authorization-url) instead.
      tags: ["OAuth"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand project ID or name.
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the connection to update.
      responses:
        200:
          description: URL to initiate OAuth flow
          content:
            text/plain:
              schema:
                type: string
                example: "https://login.salesforce.com/services/oauth2/authorize?client_id=xxx&redirect_uri=https%3A%2F%2Fapi.withampersand.com%2Fcallbacks%2Fv1%2Foauth&state=xxx"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects:
    get:
      summary: Ampersand List Projects
      description: Lists projects your credentials can access.
      operationId: listProjects
      tags: ["Project"]
      responses:
        200:
          description: List of projects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Project"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      summary: Ampersand Create a New Project
      description: Creates a new project within an organization. A project is a container for provider apps, integrations, and connections.
      operationId: createProject
      tags: ["Project"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              required:
              - appName
              - name
              - orgId
              type: object
              properties:
                appName:
                  type: string
                  description: The display name of your application, shown to end users during the connection flow.
                  minLength: 1
                  maxLength: 128
                  example: MailMonkey
                name:
                  type: string
                  description: The unique name for the project. Must contain only letters, numbers, and hyphens. Values are normalized to lowercase on save.
                  pattern: "^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]$"
                  minLength: 2
                  maxLength: 128
                  example: mailmonkey-staging
                orgId:
                  type: string
                  description: The ID of the organization this project belongs to. Obtain this from the Ampersand Dashboard or by calling `GET /orgs`.
                  example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
            example:
              appName: MailMonkey
              name: mailmonkey-staging
              orgId: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
        required: true
      responses:
        201:
          description: The newly created project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        422:
          description: Unprocessable Entity — the request body failed validation (e.g. invalid characters in project name, missing required fields).
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: project
  /projects/{projectIdOrName}:
    get:
      summary: Ampersand Get a Project
      description: Get a project by its ID or name.
      operationId: getProject
      tags: ["Project"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: includeEntitlements
        in: query
        required: false
        description: If true, the response includes the project's entitlements (plan-based feature flags). Defaults to false.
        schema:
          type: boolean
          default: false
      responses:
        200:
          description: The requested project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    # Uncomment when ENG-2300 is fixed
    # delete:
    #   summary: Delete a project
    #   operationId: deleteProject
    #   tags: ["Project"]
    #   parameters:
    #     - name: projectIdOrName
    #       in: path
    #       required: true
    #       description: The Ampersand project ID or project name.
    #       schema:
    #         type: string
    #       example: my-project
    #   responses:
    #     204:
    #       description: Deleted
    #     422:
    #       description: Unprocessable Entity
    #       content:
    #         application/problem+json:
    #           schema:
    #             $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
    #     default:
    #       description: Error
    #       content:
    #         application/problem+json:
    #           schema:
    #             $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update a Project
      operationId: updateProject
      description: Update a project's mutable fields using field masks. Currently, the updatable fields are `appName` (the display name shown to end users) and `name` (the unique project identifier).
      tags: ["Project"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              required:
              - project
              - updateMask
              type: object
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: |
                    Array of field paths specifying which fields to update. Each path must have a
                    corresponding value in the `project` object. A field included in `project` but
                    not listed here will be ignored. Allowed values:
                    - `appName` - the display name of the application, shown to end users during the connection flow.
                    - `name` - the unique project identifier (must be unique within your organization).
                  example: ["appName"]
                project:
                  type: object
                  properties:
                    appName:
                      type: string
                      description: The display name of the application, shown to end users during the connection flow.
                      example: MailMonkey
                    name:
                      type: string
                      description: The unique name for the project. Must be unique within the organization.
                      example: mailmonkey-staging
                  description: |
                    The project fields to update. Only fields whose paths are listed in `updateMask`
                    will be applied; all other fields in this object are ignored.
            example:
              updateMask:
              - "appName"
              project:
                appName: "MailMonkey Pro"
        required: true
      responses:
        200:
          description: The updated project.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: projectUpdate
  /projects/{projectIdOrName}/provider-apps:
    get:
      summary: Ampersand List Provider Apps
      operationId: listProviderApps
      tags: ["Provider App"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: TThe Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: List of provider apps
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProviderApp"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      summary: Ampersand Create a New Provider App
      operationId: createProviderApp
      tags: ["Provider App"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              required:
              - clientId
              - clientSecret
              - provider
              type: object
              properties:
                externalRef:
                  type: string
                  description: The ID used by the provider to identify the app (optional).
                  example: external-id-123
                provider:
                  type: string
                  description: The SaaS provider that this app connects to.
                  example: salesforce
                clientId:
                  type: string
                  description: The OAuth client ID for this app.
                  example: client-id-123
                clientSecret:
                  type: string
                  description: The OAuth client secret for this app.
                  example: client-secret-123
                scopes:
                  type: array
                  description: The OAuth scopes for this app.
                  items:
                    type: string
                    example:
                    - read
                    - write
                metadata:
                  $ref: "#/components/schemas/ProviderAppMetadata"
        required: true
      responses:
        200:
          description: The newly created provider app
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderApp"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: providerApp
  /projects/{projectIdOrName}/provider-apps/{providerAppId}:
    delete:
      summary: Ampersand Delete a Provider App.
      operationId: deleteProviderApp
      tags: ["Provider App"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: providerAppId
        in: path
        required: true
        description: ID of the provider app, returned by the CreateProviderApp call.
        schema:
          type: string
        example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
      responses:
        204:
          description: Deleted
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update a Provider App
      operationId: updateProviderApp
      tags: ["Provider App"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: providerAppId
        in: path
        required: true
        description: ID of the provider app, returned by the CreateProviderApp call.
        schema:
          type: string
        example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
      requestBody:
        content:
          application/json:
            schema:
              required:
              - providerApp
              - updateMask
              type: object
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: |
                    Array of field paths specifying which fields to update. Allowed values include:
                    - externalRef
                    - clientId
                    - clientSecret
                    - provider
                    - scopes
                    - metadata
                  example: ["externalRef", "clientId"]
                providerApp:
                  type: object
                  properties:
                    externalRef:
                      type: string
                      description: The ID used by the provider to identify the app (optional).
                      example: external-id-123
                    provider:
                      type: string
                      description: The SaaS provider that this app connects to.
                      example: salesforce
                    clientId:
                      type: string
                      description: The OAuth client ID for this app.
                      example: client-id-123
                    clientSecret:
                      type: string
                      description: The OAuth client secret for this app.
                      example: client-secret-123
                    scopes:
                      type: array
                      description: The OAuth scopes for this app.
                      items:
                        type: string
                        example:
                        - read
                        - write
                    metadata:
                      $ref: "#/components/schemas/ProviderAppMetadata"
                  description: The provider app fields to update. (Only include the fields you'd like to update.)
        required: true
      responses:
        200:
          description: The updated provider app
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderApp"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: providerAppUpdate
  /projects/{projectIdOrName}/integrations:
    get:
      summary: Ampersand List Integrations
      operationId: listIntegrations
      tags: ["Integration"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: List of integrations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Integration"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      summary: Ampersand Create a New Integration.
      operationId: createIntegration
      tags: ["Integration"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              required:
              - name
              - provider
              - latestRevision
              type: object
              properties:
                name:
                  type: string
                  description: The integration name.
                  example: my-integration
                provider:
                  type: string
                  description: The provider name (e.g. "salesforce", "hubspot")
                latestRevision:
                  type: object
                  required:
                  - content
                  - specVersion
                  properties:
                    specVersion:
                      type: string
                      description: The spec version string.
                      example: 1.0.0
                    content:
                      $ref: "../manifest/manifest.yaml#/components/schemas/Integration"
        required: true
      responses:
        201:
          description: Created
          content: {}
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: integration
  /projects/{projectIdOrName}/integrations/{integrationIdOrName}:
    get:
      summary: Ampersand Get an Integration by ID or Name
      operationId: getIntegration
      tags: ["Integration"]
      parameters:
      - name: integrationIdOrName
        in: path
        required: true
        description: The integration ID or name.
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: The integration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Integration"
        404:
          description: Integration not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations/{integrationId}:
    delete:
      summary: Ampersand Delete an Integration
      operationId: deleteIntegration
      description: Delete an integration and all its installations.
      tags: ["Integration"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
        example: 123e4567-e89b-12d3-a456-426614174000
      responses:
        204:
          description: Deleted
        404:
          description: Integration not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations:batch:
    put:
      summary: Ampersand Batch Upsert a Group of Integrations
      operationId: batchUpsertIntegrations
      description: This endpoint is used by the Ampersand CLI to batch upsert integrations. We recommend using the [CLI's deploy 
        command](https://docs.withampersand.com/cli/overview#deploy-integrations) rather than this API endpoint directly.
      tags: ["Integration"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: destructive
        in: query
        required: false
        description: Defaults to false. This flag controls whether to perform destructive actions when deploying integrations, like pausing all read actions for an object that was removed in the 
          latest revision.
        schema:
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceZipUrl:
                  type: string
                  description: URL of where a zip of the source files can be downloaded (e.g. Google Cloud Storage URL).
                  example: https://storage.googleapis.com/my-bucket/source-files/integration-v1.2.3.zip
                sourceYaml:
                  type: string
                  description: A YAML string that defines the integrations.
              description: The source of the integrations to upsert. One of sourceZipUrl or sourceYaml is required.
      responses:
        200:
          description: Upserted integrations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Integration"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations/{integrationId}/revisions:
    post:
      summary: Ampersand Create a New Revision.
      operationId: createRevision
      description: We recommend using the [CLI's deploy command](https://docs.withampersand.com/cli/overview#deploy-integrations) rather than this API endpoint directly, unless you have an advanced 
        use case.
      tags: ["Revision"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
      - name: destructive
        in: query
        required: false
        description: Defaults to false. This flag controls whether to perform destructive actions when deploying integrations, like pausing all read actions for an object that was removed in the 
          latest revision.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceZipUrl:
                  type: string
                  description: URL of where a zip of the source files can be downloaded (e.g. Google Cloud Storage URL).
                  example: https://storage.googleapis.com/my-bucket/source-files/integration-v1.2.3.zip
                sourceYaml:
                  type: string
                  description: The source YAML file that defines the revision.
              description: The source of the revision to create. One of sourceZipUrl or sourceYaml is required.
        required: true
      responses:
        201:
          description: Created
          content: {}
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: revision
  /projects/{projectIdOrName}/integrations/{integrationId}/revisions/{revisionId}:hydrate:
    get:
      summary: Ampersand Get a Hydrated Revision
      description: |
        Returns the integration revision enriched with live field metadata from the consumer's connected SaaS instance, such as available fields, display names, and type for each object defined in the integration.
      operationId: getHydratedRevision
      tags: ["Revision"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
        example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      - name: revisionId
        in: path
        required: true
        description: The revision ID. You can find this on the integration object's `latestRevision.id` field.
        schema:
          type: string
        example: "f0e1d2c3-b4a5-6789-0abc-def123456789"
      - name: connectionId
        in: query
        required: true
        description: The ID of the consumer's connection to the SaaS provider. This connection's credentials are used to fetch field metadata from the provider's API.
        schema:
          type: string
        example: "1a2b3c4d-5e6f-7890-abcd-ef0123456789"
      responses:
        200:
          description: Hydrated revision.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HydratedRevision"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations/{integrationId}/installations:
    get:
      summary: Ampersand List Installations for an Integration
      description: |
        Lists all installations for a specific integration within a project. To list installations across all integrations, use listInstallationsForProject instead.
      operationId: listInstallations
      tags: ["Installation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The unique identifier (UUID) of the integration.
        schema:
          type: string
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: groupRef
        in: query
        description: The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group.
        example: group-123
        schema:
          type: string
      responses:
        200:
          description: List of installations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Installation"
              example:
              - id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
                projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                integrationId: 550e8400-e29b-41d4-a716-446655440000
                group:
                  groupRef: org_12345
                  groupName: Acme Corp
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  createTime: "2024-01-15T10:30:00.000000Z"
                healthStatus: healthy
                connection:
                  id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  provider: salesforce
                  group:
                    groupRef: org_12345
                    groupName: Acme Corp
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  consumer:
                    consumerRef: user_67890
                    consumerName: Jane Smith
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  createTime: "2024-01-15T10:30:00.000000Z"
                  authScheme: oauth2/authorizationCode
                  status: working
                createTime: "2024-01-15T10:30:00.000000Z"
                createdBy: "consumer:user_67890"
                config:
                  id: e4d3c2b1-a098-7654-3210-fedcba987654
                  revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
                  createTime: "2024-01-15T10:30:00.000000Z"
                  createdBy: "consumer:user_67890"
                  content:
                    provider: salesforce
                    read:
                      objects:
                        account:
                          objectName: account
                          schedule: "*/15 * * * *"
                          destination: accountWebhook
                          selectedFields:
                            name: true
                            industry: true
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      summary: Ampersand Create a New Installation
      operationId: createInstallation
      description: |
        Install an integration for a specific group. The group must already have a SaaS connection — either provide its `connectionId`, or omit it to use the group's default. To create a connection, use the [OAuth Connect endpoint](https://docs.withampersand.com/reference/oauth/generate-oauth-authorization-url) or the [prebuilt UI components](https://docs.withampersand.com/embeddable-ui-components).
      tags: ["Installation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
        example: "113e9685-9a51-42cc-8662-9d9725b17f14"
      requestBody:
        content:
          application/json:
            schema:
              required:
              - config
              - groupRef
              type: object
              properties:
                groupRef:
                  type: string
                  description: The ID of the user group that has access to this installation.
                  example: group-123
                connectionId:
                  type: string
                  description: The ID of the SaaS connection tied to this installation. If omitted the default connection for this group will be used.
                  example: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
                config:
                  required:
                  - content
                  type: object
                  properties:
                    revisionId:
                      type: string
                      deprecated: true
                      description: "Deprecated: This field will be automatically set to the latest revision."
                    createdBy:
                      type: string
                      description: The person who created the config, in the format of "consumer:{consumer-id}", "builder:{builder-id}", or "api:{api-caller}".
                      default: "api:create-installation"
                    content:
                      $ref: "../config/config.yaml#/components/schemas/ConfigContent"
                      description: The content of the config.
                  description: The config of the installation.
            examples:
              writeOnly:
                summary: Minimal write-only installation
                value:
                  groupRef: group-123
                  connectionId: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
                  config:
                    content:
                      provider: salesforce
                      write:
                        objects:
                          contacts:
                            objectName: contacts
              readWriteAndSubscribe:
                summary: Read, write, and subscribe
                value:
                  groupRef: group-456
                  connectionId: b2d5f8a3-9e4c-4b7f-8d1a-6c9e2f5b8d4a
                  config:
                    content:
                      provider: salesforce
                      read:
                        objects:
                          contacts:
                            objectName: contacts
                            schedule: "*/15 * * * *"
                            selectedFields:
                              phone: true
                              email: true
                            selectedFieldMappings:
                              phoneNumber: phone
                              emailAddress: email
                      write:
                        objects:
                          contacts:
                            objectName: contacts
                      subscribe:
                        objects:
                          contacts:
                            objectName: contacts
                            destination: contactWebhook
                            inheritFieldsAndMappings: true
        required: true
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Installation"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: installation
  /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:
    get:
      summary: Ampersand Get an Installation
      description: |
        Retrieves a single installation by ID, including its connection details, config, and health status.
      operationId: getInstallation
      tags: ["Installation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The unique identifier (UUID) of the integration.
        schema:
          type: string
        example: 550e8400-e29b-41d4-a716-446655440000
      - name: installationId
        in: path
        required: true
        description: The unique identifier (UUID) of the installation.
        schema:
          type: string
        example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b
      responses:
        200:
          description: The installation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Installation"
              example:
                id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
                projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                integrationId: 550e8400-e29b-41d4-a716-446655440000
                group:
                  groupRef: org_12345
                  groupName: Acme Corp
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  createTime: "2024-01-15T10:30:00.000000Z"
                healthStatus: healthy
                connection:
                  id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  provider: salesforce
                  group:
                    groupRef: org_12345
                    groupName: Acme Corp
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  consumer:
                    consumerRef: user_67890
                    consumerName: Jane Smith
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  createTime: "2024-01-15T10:30:00.000000Z"
                  authScheme: oauth2/authorizationCode
                  status: working
                createTime: "2024-01-15T10:30:00.000000Z"
                createdBy: "consumer:user_67890"
                config:
                  id: e4d3c2b1-a098-7654-3210-fedcba987654
                  revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
                  createTime: "2024-01-15T10:30:00.000000Z"
                  createdBy: "consumer:user_67890"
                  content:
                    provider: salesforce
                    read:
                      objects:
                        account:
                          objectName: account
                          schedule: "*/15 * * * *"
                          destination: accountWebhook
                          selectedFields:
                            name: true
                            industry: true
        400:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    delete:
      summary: Ampersand Delete an Installation
      operationId: deleteInstallation
      tags: ["Installation"]
      description: |
        Delete an Installation. This will also delete the associated Connection if it is not used by any other Installations.
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
      - name: installationId
        in: path
        required: true
        schema:
          type: string
        description: The Ampersand installation ID.
      responses:
        204:
          description: Deleted
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update an Installation
      operationId: updateInstallation
      tags: ["Installation"]
      description: |
        Update an installation using field masks. Note: subscribe config changes trigger a subscription change in the provider's system, which typically takes 1-2 minutes but may take up to 10 minutes.
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The ID of the integration that this installation belongs to.
        schema:
          type: string
        example: e3a7f9c1-4b2d-4e8a-9f6b-2d5c8a1e3b7f
      - name: installationId
        in: path
        required: true
        description: The Ampersand installation ID.
        schema:
          type: string
        example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b
      requestBody:
        content:
          application/json:
            schema:
              required:
              - installation
              - updateMask
              type: object
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: |
                    Array of field paths specifying which fields to update. Each path must have a corresponding value in the `installation` object. A field included in `installation` but not listed here will be ignored. Allowed values:
                    - `connectionId` - switch the SaaS connection tied to this installation.
                    - `config.createdBy` - change the attribution for who created this config.
                    - `config.content.read.objects.<objectName>` - replace the read config for a single object (e.g. `config.content.read.objects.contacts`).
                    - `config.content.write.objects.<objectName>` - replace the write config for a single object.
                    - `config.content.write.objects` - replace the entire write objects map.
                    - `config.content.subscribe.objects.<objectName>` - replace the subscribe config for a single object.
                    - `config.content.subscribe.objects` - replace the entire subscribe objects map.
                    - `config.content.proxy.enabled` - enable or disable the proxy.

                    Replace `<objectName>` with the provider object name (e.g. `contacts`, `leads`, `accounts`).
                  example: ["config.content.read.objects.contacts", "config.content.write.objects.leads"]
                installation:
                  type: object
                  properties:
                    connectionId:
                      type: string
                      description: The ID of the SaaS connection tied to this installation.
                      example: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c
                    config:
                      type: object
                      properties:
                        revisionId:
                          type: string
                          deprecated: true
                          description: "Deprecated: This field will be automatically set to the latest revision ID."
                        createdBy:
                          type: string
                          description: The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".
                        content:
                          $ref: "../config/config.yaml#/components/schemas/UpdateInstallationConfigContent"
                          description: The content of the config.
                      description: The config of the installation.
                  description: |
                    The installation fields to update. Only fields whose paths are listed in `updateMask` will be
                    applied; all other fields in this object are ignored.
            example:
              updateMask:
              - "config.content.read.objects.contacts"
              installation:
                config:
                  content:
                    read:
                      objects:
                        contacts:
                          objectName: contacts
                          schedule: "*/30 * * * *"
                          destination: contactsWebhook
                          selectedFields:
                            email: true
                            phone: true
        required: true
      responses:
        200:
          description: The updated installation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Installation"
        400:
          description: Invalid input (e.g. unrecognized update mask path, missing value for a mask, or malformed request body).
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: installationUpdate
  /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content:
    patch:
      summary: Ampersand Update an Installation Object
      description: |
        Updates a single object's configuration within an installation using JSON Patch syntax.
      operationId: patchObjectConfigContent
      tags: ["Installation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
      - name: objectName
        in: path
        required: true
        description: |
          The object name whose config content will be patched.
          Must match an object name defined in the integration's manifest for the specified action type (read, subscribe, or write).
          Common examples include: `account`, `contact`, `lead`, `opportunity` (for Salesforce), `deal`, `company` (for HubSpot), etc.
        schema:
          type: string
        example: account
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - oneOf:
                - type: object
                  required: [groupRef, action, changes]
                  properties:
                    groupRef:
                      type: string
                      description: |
                        The ID of the user group that has access to this installation.
                        Either groupRef or installationId must be provided.
                      example: group-123
                    action:
                      type: string
                      enum: [read, subscribe, write]
                      description: The action type for the object config (read, subscribe, or write).
                      example: read
                    changes:
                      type: array
                      minItems: 1
                      description: |
                        Array of JSON Patch operations to apply.
                      items:
                        $ref: "#/components/schemas/JSONPatchOperation"
                      example:
                      - op: replace
                        path: /schedule
                        value: "*/10 * * * *"
                      - op: add
                        path: /selectedFields/phone
                        value: true
                      - op: remove
                        path: /selectedFields/billingcity
                - type: object
                  required: [installationId, action, changes]
                  properties:
                    installationId:
                      type: string
                      description: |
                        The installation ID.
                        Either groupRef or installationId must be provided.
                      example: installation-123
                    action:
                      type: string
                      enum: [read, subscribe, write]
                      description: The action type for the object config (read, subscribe, or write).
                      example: read
                    changes:
                      type: array
                      minItems: 1
                      description: |
                        Array of JSON Patch operations to apply.
                      items:
                        $ref: "#/components/schemas/JSONPatchOperation"
                      example:
                      - op: replace
                        path: /schedule
                        value: "*/10 * * * *"
                      - op: add
                        path: /selectedFields/phone
                        value: true
                      - op: remove
                        path: /selectedFields/billingcity
        required: true
      responses:
        200:
          description: The updated installation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Installation"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        404:
          description: Installation not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: patchObjectConfigContent
  /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/metadata:
    get:
      summary: Ampersand Get Object Metadata via Installation
      description: |
        Retrieves metadata about an object in a customer's SaaS instance, including its fields. An installation must exist for the given `groupRef` and `integrationId`. The `objectName` can be either the mapped name from your integration config or the native provider name. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$['billingaddress']['city']`).
      tags: ["Objects & Fields"]
      operationId: getObjectMetadataForInstallation
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The unique identifier of the integration.
        schema:
          type: string
        example: "e3a7f9c1-4b2d-4e8a-9f6b-2d5c8a1e3b7f"
      - name: objectName
        in: path
        required: true
        description: |
          The name of the object to retrieve metadata for. You can use either the mapped name from your integration config (e.g. `people`) or the native provider object name (e.g. `contact`).
        schema:
          type: string
        example: account
      - name: groupRef
        in: query
        required: true
        description: The ID of the user group that has access to this installation.
        example: group-123
        schema:
          type: string
      - name: excludeReadOnly
        in: query
        required: false
        description: Excludes fields where `ReadOnly` is `true` from the response.
        example: true
        schema:
          type: boolean
      responses:
        '200':
          description: The retrieved object metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectMetadata'
              example:
                name: "account"
                displayName: "Account"
                mappedObjectName: "companies"
                fields:
                  name:
                    fieldName: "name"
                    displayName: "Account Name"
                    valueType: "string"
                    providerType: "string"
                    readOnly: false
                    isCustom: false
                    isRequired: true
                  billingcity:
                    fieldName: "billingcity"
                    displayName: "Billing City"
                    valueType: "string"
                    providerType: "string"
                    readOnly: false
                    isCustom: false
                    isRequired: false
                  industry:
                    fieldName: "industry"
                    displayName: "Industry"
                    valueType: "singleSelect"
                    providerType: "picklist"
                    readOnly: false
                    isCustom: false
                    isRequired: false
                    values:
                    - value: "technology"
                      displayValue: "Technology"
                    - value: "finance"
                      displayValue: "Finance"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/installations:
    get:
      summary: Ampersand List Installations for a Project
      description: |
        Lists all installations across every integration in a project, giving you a complete view of all active customer integrations. To narrow results to a single integration, use listInstallations instead.
      operationId: listInstallationsForProject
      tags: ["Installation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: groupRef
        in: query
        description: The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group.
        example: group-123
        schema:
          type: string
      responses:
        200:
          description: List of installations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Installation"
              example:
              - id: 3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d
                projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                integrationId: 550e8400-e29b-41d4-a716-446655440000
                group:
                  groupRef: org_12345
                  groupName: Acme Corp
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  createTime: "2024-01-15T10:30:00.000000Z"
                healthStatus: healthy
                connection:
                  id: 9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210
                  projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                  provider: salesforce
                  group:
                    groupRef: org_12345
                    groupName: Acme Corp
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  consumer:
                    consumerRef: user_67890
                    consumerName: Jane Smith
                    projectId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                    createTime: "2024-01-15T10:30:00.000000Z"
                  createTime: "2024-01-15T10:30:00.000000Z"
                  authScheme: oauth2/authorizationCode
                  status: working
                createTime: "2024-01-15T10:30:00.000000Z"
                createdBy: "consumer:user_67890"
                config:
                  id: e4d3c2b1-a098-7654-3210-fedcba987654
                  revisionId: f0e1d2c3-b4a5-6789-0abc-def123456789
                  createTime: "2024-01-15T10:30:00.000000Z"
                  createdBy: "consumer:user_67890"
                  content:
                    provider: salesforce
                    read:
                      objects:
                        account:
                          objectName: account
                          schedule: "*/15 * * * *"
                          destination: accountWebhook
                          selectedFields:
                            name: true
                            industry: true
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/providers/{provider}/objects/{objectName}/metadata:
    get:
      summary: Ampersand Get Object Metadata via Connection
      description: |
        Retrieves metadata about an object in a customer's SaaS instance, including its fields. A connection must exist for the given `groupRef` and `provider`. For Salesforce, nested fields may be included using JSONPath bracket notation (e.g. `$['billingaddress']['city']`).
      tags: ["Objects & Fields"]
      operationId: getObjectMetadataForConnection
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: provider
        in: path
        required: true
        description: The provider name (e.g. `salesforce`, `hubspot`).
        schema:
          type: string
        example: salesforce
      - name: objectName
        in: path
        required: true
        description: The native provider object name to retrieve metadata for.
        schema:
          type: string
        example: contact
      - name: groupRef
        in: query
        required: true
        description: The ID of the user group whose connection should be used to fetch the metadata.
        example: group-123
        schema:
          type: string
      - name: excludeReadOnly
        in: query
        required: false
        description: Excludes fields where `ReadOnly` is `true` from the response.
        example: true
        schema:
          type: boolean
      responses:
        '200':
          description: The retrieved object metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectMetadata'
              example:
                name: "contact"
                displayName: "Contact"
                fields:
                  firstname:
                    fieldName: "firstname"
                    displayName: "First Name"
                    valueType: "string"
                    providerType: "string"
                    readOnly: false
                    isCustom: false
                    isRequired: true
                  email:
                    fieldName: "email"
                    displayName: "Email"
                    valueType: "string"
                    providerType: "string"
                    readOnly: false
                    isCustom: false
                    isRequired: false
                  lifecyclestage:
                    fieldName: "lifecyclestage"
                    displayName: "Lifecycle Stage"
                    valueType: "singleSelect"
                    providerType: "enumeration"
                    readOnly: false
                    isCustom: false
                    isRequired: false
                    values:
                    - value: "lead"
                      displayValue: "Lead"
                    - value: "customer"
                      displayValue: "Customer"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations/{integrationId}/object-metadata:
    put:
      summary: Ampersand Upsert Custom Fields for Installation
      operationId: upsertMetadataForInstallation
      description: Create or update fields in the SaaS instance tied to an installation. Only HubSpot and Salesforce are supported currently.
      tags: ["Objects & Fields"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
        example: 32356abe-d2fd-49c7-9030-abdcbc6456d4
      requestBody:
        required: true
        description: Metadata upsert request containing field definitions to create or update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertMetadataRequest'
            examples:
              createTextFields:
                summary: Create text fields on multiple objects
                value:
                  groupRef: "group-123"
                  fields:
                    Account:
                    - fieldName: "Industry"
                      displayName: "Industry Sector"
                      description: "The industry this account operates in"
                      valueType: "string"
                      required: false
                      stringOptions:
                        length: 255
                        defaultValue: "Technology"
                    - fieldName: "Company_Size"
                      displayName: "Company Size"
                      valueType: "string"
                      stringOptions:
                        values: ["Small", "Medium", "Large", "Enterprise"]
                        valuesRestricted: true
                    Contact:
                    - fieldName: "Seniority_Level"
                      displayName: "Seniority Level"
                      valueType: "string"
                      stringOptions:
                        values: ["Junior", "Mid", "Senior", "Executive"]
                        valuesRestricted: true
              createNumericFields:
                summary: Create numeric fields with constraints
                value:
                  groupRef: "group-123"
                  fields:
                    Opportunity:
                    - fieldName: "Deal_Score"
                      displayName: "Deal Score"
                      description: "Likelihood score from 0-100"
                      valueType: "float"
                      required: true
                      numericOptions:
                        precision: 5
                        scale: 2
                        min: 0
                        max: 100
                        defaultValue: 50
              createAssociationField:
                summary: Create field with association to another object
                value:
                  groupRef: "group-123"
                  fields:
                    Task:
                    - fieldName: "Related_Contact"
                      displayName: "Related Contact"
                      valueType: "string"
                      association:
                        associationType: "lookup"
                        targetObject: "Contact"
                        targetField: "Id"
                        cardinality: "many-to-one"
                        required: false
                        labels:
                          singular: "Contact"
                          plural: "Contacts"
      responses:
        '200':
          description: Metadata creation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertMetadataResponse'
        '400':
          description: Invalid request payload or validation errors
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '401':
          description: Authentication required
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '403':
          description: Insufficient permissions for metadata operations
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '404':
          description: Project, integration, or installation not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/providers/{provider}/object-metadata:
    put:
      summary: Ampersand Upsert Custom Fields for Connection
      operationId: upsertMetadataForConnection
      description: Create or update fields in the SaaS instance tied to a connection. Only HubSpot and Salesforce are supported currently.
      tags: ["Objects & Fields"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: provider
        in: path
        required: true
        description: The provider that this connection connects to.
        schema:
          type: string
        example: salesforce
      requestBody:
        required: true
        description: Metadata upsert request containing field definitions to create or update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertMetadataRequest'
            examples:
              createTextFields:
                summary: Create text fields on multiple objects
                value:
                  groupRef: "group-123"
                  fields:
                    Account:
                    - fieldName: "Industry"
                      displayName: "Industry Sector"
                      description: "The industry this account operates in"
                      valueType: "string"
                      required: false
                      stringOptions:
                        length: 255
                        defaultValue: "Technology"
                    - fieldName: "Company_Size"
                      displayName: "Company Size"
                      valueType: "string"
                      stringOptions:
                        values: ["Small", "Medium", "Large", "Enterprise"]
                        valuesRestricted: true
                    Contact:
                    - fieldName: "Seniority_Level"
                      displayName: "Seniority Level"
                      valueType: "string"
                      stringOptions:
                        values: ["Junior", "Mid", "Senior", "Executive"]
                        valuesRestricted: true
              createNumericFields:
                summary: Create numeric fields with constraints
                value:
                  groupRef: "group-123"
                  fields:
                    Opportunity:
                    - fieldName: "Deal_Score"
                      displayName: "Deal Score"
                      description: "Likelihood score from 0-100"
                      valueType: "float"
                      required: true
                      numericOptions:
                        precision: 5
                        scale: 2
                        min: 0
                        max: 100
                        defaultValue: 50
              createAssociationField:
                summary: Create field with association to another object
                value:
                  groupRef: "group-123"
                  fields:
                    Task:
                    - fieldName: "Related_Contact"
                      displayName: "Related Contact"
                      valueType: "string"
                      association:
                        associationType: "lookup"
                        targetObject: "Contact"
                        targetField: "Id"
                        cardinality: "many-to-one"
                        required: false
                        labels:
                          singular: "Contact"
                          plural: "Contacts"
      responses:
        '200':
          description: Metadata creation completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertMetadataResponse'
        '400':
          description: Invalid request payload or validation errors
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '401':
          description: Authentication required
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '403':
          description: Insufficient permissions for metadata operations
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '404':
          description: Project or connection not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '500':
          description: Internal server error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}/operations:
    get:
      summary: Ampersand List Operations
      operationId: listOperations
      tags: ["Operation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The integration ID.
        schema:
          type: string
      - name: installationId
        in: path
        required: true
        description: The Ampersand installation ID.
        schema:
          type: string
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 200
        description: The number of operations to return.
      - name: pageToken
        in: query
        schema:
          type: string
        description: A cursor that can be passed to paginate through multiple pages of operations.
      responses:
        200:
          description: List of operations
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - pagination
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Operation'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  ? /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}/objects/{objectName}/backfill-progress
  : get:
      summary: Ampersand Get Backfill Progress
      operationId: getBackfillProgress
      tags: ["Operation"]
      description: Retrieve backfill progress (records processed, estimated total) for an object. Use to track progress of an initial data sync.
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: integrationId
        in: path
        required: true
        description: The Ampersand integration ID.
        schema:
          type: string
        example: 113e9685-9a51-42cc-8662-9d9725b17f14
      - name: installationId
        in: path
        required: true
        description: The Ampersand installation ID.
        schema:
          type: string
        example: 66438162-5299-4669-a41d-85c5a3b1a83e
      - name: objectName
        in: path
        required: true
        description: Name of the object being synced (e.g., "contact", "account").
        schema:
          type: string
        example: contact
      responses:
        200:
          description: Backfill progress for the object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackfillProgress"
              example:
                installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
                objectName: "contact"
                operationId: "3efc0f0f-4bb9-498f-996c-9893d98ca4b5"
                recordsProcessed: 1250
                recordsEstimatedTotal: 5000
                createTime: "2025-02-13T10:00:00Z"
                updateTime: "2025-02-13T10:05:00Z"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        404:
          description: No backfill operation found or progress not available
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/operations/{operationId}:
    get:
      summary: Ampersand Get an Operation
      description: |
        Retrieve a single operation by ID. An operation represents an async read, write, or subscribe action for an installation. Use this endpoint to poll for status, inspect the result summary, or fetch metadata such as backfill progress or write outcome details. 
      operationId: getOperation
      tags: ["Operation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: operationId
        in: path
        required: true
        description: Unique identifier for the operation. Obtain from the list operations API endpoint, the Ampersand dashboard, or webhook payloads.
        schema:
          type: string
        example: 3efc0f0f-4bb9-498f-996c-9893d98ca4b5
      responses:
        200:
          description: The operation, including its current status, result summary, and metadata (e.g. backfill progress or write results).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Operation"
              examples:
                readSuccess:
                  summary: Completed read (no new data)
                  value:
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    integrationId: "113e9685-9a51-42cc-8662-9d9725b17f14"
                    installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
                    configId: "a1b2c3d4-e5f6-4789-a012-3456789abcde"
                    actionType: read
                    status: success
                    id: 3efc0f0f-4bb9-498f-996c-9893d98ca4b5
                    result: "[contact] No new data found"
                    metadata:
                      objects: [contact]
                    createTime: "2023-07-13T21:34:44.816354Z"
                readBackfill:
                  summary: Read with backfill progress
                  value:
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    integrationId: "113e9685-9a51-42cc-8662-9d9725b17f14"
                    installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
                    configId: "a1b2c3d4-e5f6-4789-a012-3456789abcde"
                    actionType: read
                    status: in_progress
                    id: 3efc0f0f-4bb9-498f-996c-9893d98ca4b5
                    metadata:
                      objects: [contact]
                      progress:
                        installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
                        objectName: contact
                        operationId: "3efc0f0f-4bb9-498f-996c-9893d98ca4b5"
                        recordsProcessed: 1250
                        recordsEstimatedTotal: 5000
                    createTime: "2023-07-13T21:34:44.816354Z"
                writeSuccess:
                  summary: Completed write with successful record IDs
                  value:
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    integrationId: "113e9685-9a51-42cc-8662-9d9725b17f14"
                    installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
                    configId: "a1b2c3d4-e5f6-4789-a012-3456789abcde"
                    actionType: write
                    status: success
                    id: 7a8b9c0d-1e2f-4a5b-8c9d-0e1f2a3b4c5d
                    result: "Batch write completed (2 succeeded, 0 failed)"
                    metadata:
                      objects: [contact]
                      successfulRecordIds: ["001xx000003DGbYAAW", "001xx000003DGbZAAW"]
                    createTime: "2023-07-13T22:10:00.000000Z"
        default:
          description: |
            Error response for any non-2xx status (e.g. operation not found, invalid project or operation ID, or server error).
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              example:
                type: "https://httpstatuses.com/404"
                title: "Not Found"
                status: 404
                detail: "Operation not found for the given operation ID."
                subsystem: api
                time: "2024-04-22T18:55:28.456076Z"
                requestId: "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715"
                remedy: "Verify the operation ID and project are correct, or list operations to find a valid ID."
                retryable: false
  /projects/{projectIdOrName}/operations/{operationId}/logs:
    get:
      summary: Ampersand List Logs for an Operation
      operationId: listOperationLogs
      tags: ["Operation"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: operationId
        in: path
        required: true
        description: Operation ID.
        schema:
          type: string
      responses:
        200:
          description: List of logs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Log"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /providers:
    get:
      summary: Ampersand List Providers
      description: |
        Returns all supported SaaS providers and their capabilities. The response is a JSON object keyed by provider name (e.g. `salesforce`, `hubspot`). Each value describes the provider's authentication type, supported operations, modules, and configuration options. No authentication is required.
      operationId: listProviders
      tags: ["Provider"]
      security: []
      responses:
        200:
          description: |
            All available providers and their capabilities.
          content:
            application/json:
              schema:
                $ref: "../catalog/catalog.yaml#/components/schemas/CatalogType"
              example:
                salesforce:
                  name: salesforce
                  displayName: Salesforce
                  authType: oauth2
                  baseURL: "https://{{.workspace}}.my.salesforce.com"
                  defaultModule: crm
                  support:
                    read: true
                    write: true
                    delete: true
                    subscribe: true
                    proxy: true
                    bulkWrite:
                      insert: true
                      update: true
                      upsert: true
                      delete: true
                    search:
                      operators:
                        equals: true
                  providerOpts: {}
                hubspot:
                  name: hubspot
                  displayName: HubSpot
                  authType: oauth2
                  baseURL: "https://api.hubapi.com"
                  defaultModule: ""
                  support:
                    read: true
                    write: true
                    delete: true
                    subscribe: true
                    proxy: true
                    bulkWrite:
                      insert: false
                      update: false
                      upsert: false
                      delete: false
                    search:
                      operators:
                        equals: true
                  providerOpts: {}
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /providers/{provider}:
    get:
      summary: Ampersand Get Provider
      description: |
        Returns information about a single provider. No authentication is required.
      operationId: getProvider
      tags: ["Provider"]
      security: []
      parameters:
      - name: provider
        in: path
        required: true
        description: The provider name (e.g. `salesforce`, `hubspot`).
        example: hubspot
        schema:
          type: string
      responses:
        200:
          description: The requested provider.
          content:
            application/json:
              schema:
                $ref: "../catalog/catalog.yaml#/components/schemas/ProviderInfo"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/api-keys:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand List API Keys
      operationId: listApiKeys
      tags: ["API Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: active
        in: query
        description: Whether to include only active API keys. If false, all API keys are included.
        schema:
          type: boolean
      responses:
        200:
          description: List of API keys
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiKey"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      x-speakeasy-ignore: true
      summary: Ampersand Create a New API Key
      operationId: createApiKey
      tags: ["API Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApiKeyRequest"
        required: true
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        404:
          description: Project not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: apiKey
  /projects/{projectIdOrName}/api-keys/{apiKey}:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand Get an API Key
      operationId: getApiKey
      tags: ["API Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: apiKey
        in: path
        required: true
        description: API key to access Ampersand APIs.
        schema:
          type: string
      responses:
        404:
          description: API key not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        200:
          description: API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    delete:
      x-speakeasy-ignore: true
      summary: Ampersand Delete an API Key
      operationId: deleteApiKey
      tags: ["API Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: apiKey
        in: path
        required: true
        description: API key to access Ampersand APIs.
        schema:
          type: string
      responses:
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        204:
          description: Deleted
    patch:
      x-speakeasy-ignore: true
      summary: Ampersand Update an API Key
      operationId: updateApiKey
      tags: ["API Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: apiKey
        in: path
        required: true
        description: API key to access Ampersand APIs.
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PatchApiKeyRequest"
        required: true
      responses:
        200:
          description: API key updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKey"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        404:
          description: Not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/connections:
    get:
      summary: Ampersand List Connections
      operationId: listConnections
      tags: ["Connection"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: provider
        in: query
        description: The provider name (e.g. "salesforce", "hubspot")
        schema:
          type: string
      - name: groupRef
        in: query
        description: The ID of the user group that has access to this installation.
        example: group-123
        schema:
          type: string
      - name: consumerRef
        in: query
        description: The consumer reference.
        schema:
          type: string
      responses:
        200:
          description: List of project connections.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Connection"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/connections:generate:
    post:
      summary: Ampersand Generate a New Connection
      description: All auth schemes are supported, but for OAuth2 Authorization Code, it is recommended that you use the [/oauth-connect 
        endpoint](https://docs.withampersand.com/reference/oauth/get-url-for-oauth-flow) instead, unless you already have the refresh token and are importing it into Ampersand.
      operationId: generateConnection
      tags: ["Connection"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GenerateConnectionRequest"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connection"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: generateConnectionParams
  /projects/{projectIdOrName}/connections/{connectionId}:
    get:
      summary: Ampersand Get a Connection
      operationId: getConnection
      tags: ["Connection"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      - name: includeCreds
        in: query
        schema:
          type: boolean
        description: Whether to include credentials for `oauth2AuthorizationCode` in the response. If true, `accessToken` and `scopes` are included. To include `refreshToken` as well, set 
          `includeRefreshToken` to true. Default is false.
      - name: includeRefreshToken
        in: query
        schema:
          type: boolean
        description: Whether to include `refreshToken` for `oauth2AuthorizationCode` credentials in the response (along with `accessToken` and `scopes`). If true, the `includeCreds` query parameter 
          will be ignored. Default is false.
      - name: refresh
        in: query
        schema:
          type: string
          enum: [force, ifExpired]
        description: Whether to refresh the access token. If value is `ifExpired`, the access token will be refreshed only if it has expired. If value is `force`, the access token will be refreshed 
          regardless of its expiration.
      responses:
        200:
          description: Connection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connection"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update a Connection.
      description: Rotate credentials or update metadata (such as the provider workspace reference) for an existing connection.
      operationId: updateConnection
      tags: ["Connection"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: The Ampersand project ID or project name.
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
        description: The ID of the connection to update. You can find this via the [list connections endpoint](https://docs.withampersand.com/reference/connection/list-connections).
        example: connection-123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectionRequest'
            examples:
              rotateApiKey:
                summary: Rotate an API key
                value:
                  updateMask: ["apiKey"]
                  connection:
                    apiKey: "new-api-key-value"
              updateBasicAuth:
                summary: Update basic auth credentials
                value:
                  updateMask: ["basicAuth"]
                  connection:
                    basicAuth:
                      username: "new-username"
                      password: "new-password"
              updateWorkspaceRef:
                summary: Update provider workspace reference
                value:
                  updateMask: ["providerWorkspaceRef"]
                  connection:
                    providerWorkspaceRef: "new-workspace-id"
      responses:
        '200':
          description: Connection updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
              example:
                id: "c3a1f9d2-7b4e-4f8a-9e6d-2c5b8a3f1e7d"
                projectId: "a1b2c3d4-e5f6-4789-a012-3456789abcde"
                provider: "salesforce"
                group:
                  groupRef: "8f2e4a6b-1c3d-4e5f-9a7b-0d8e6f2c4a1b"
                  groupName: "my-group"
                consumer:
                  consumerRef: "d4e5f6a7-b8c9-4d0e-a1f2-3b4c5d6e7f8a"
                  consumerName: "my-consumer"
                providerWorkspaceRef: "my-org.my.salesforce.com"
                authScheme: "apiKey"
                status: "working"
                createTime: "2023-07-13T21:34:44.816354Z"
                updateTime: "2024-01-15T10:22:33.000000Z"
        400:
          description: Invalid update mask or request body. The response includes the list of allowed mask values.
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
              example:
                type: "about:blank"
                title: "Bad Request"
                status: 400
                detail: "Invalid update mask"
                subsystem: "api"
                time: "2024-04-22T18:55:28.456076Z"
                requestId: "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715"
                remedy: "Allowed masks: 'providerWorkspaceRef, providerMetadata, apiKey, basicAuth, oauth2ClientCredentials, oauth2PasswordCredentials'"
                retryable: false
        default:
          description: Error (e.g. connection not found, auth scheme mismatch, or server error).
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    delete:
      summary: Ampersand Delete a Connection
      operationId: deleteConnection
      tags: ["Connection"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: connectionId
        in: path
        required: true
        schema:
          type: string
      responses:
        204:
          description: Deleted
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/destinations:
    post:
      summary: Ampersand Create a New Destination
      operationId: createDestination
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - type
              - metadata
              properties:
                name:
                  type: string
                  description: Name for the new destination. Must be unique within the project and can only contain letters, numbers and dashes.
                  example: leadConvertedWebhook
                type:
                  type: string
                  description: The type of the destination.
                  example: webhook
                  enum: [webhook, kinesis]
                secrets:
                  type: object
                  description: Secrets for the destination.
                  properties:
                    awsKeyId:
                      type: string
                      description: The AWS access key ID for the Kinesis destination.
                      example: AKIAIOSFODNN7EXAMPLE
                      x-go-type-skip-optional-pointer: true
                    awsSecretKey:
                      type: string
                      description: The AWS secret access key for the Kinesis destination.
                      example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
                      x-go-type-skip-optional-pointer: true
                    awsSessionToken:
                      type: string
                      description: The AWS session token for the Kinesis destination.
                      example: AQoEXAMPLEH4aoAH0gNCAPy...
                      x-go-type-skip-optional-pointer: true
                metadata:
                  type: object
                  properties:
                    url:
                      type: string
                      description: Webhook URL, must start with "https://".
                      example: https://webhooks.mailmonkey.com/salesforce-lead-converted
                    headers:
                      $ref: "#/components/schemas/WebhookHeaders"
                    region:
                      type: string
                      description: The AWS region where the kinesis destination is hosted.
                      example: us-east-1
                      x-go-type-skip-optional-pointer: true
                    streamName:
                      type: string
                      description: The name of the Kinesis stream to send events to.
                      example: my-kinesis-stream
                      x-go-type-skip-optional-pointer: true
                    endpointUrl:
                      type: string
                      description: The endpoint URL for the Kinesis stream.
                      example: https://kinesis.us-east-1.amazonaws.com
                      x-go-type-skip-optional-pointer: true
                    partitionKeyTemplate:
                      type: string
                      description: The template for the partition key to use when sending events to Kinesis (a JMESPath template)
                      example: "data.user_id"
                      x-go-type-skip-optional-pointer: true
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Destination"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: destination
    get:
      summary: Ampersand List Destinations
      operationId: listDestinations
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: List of destinations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Destination"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/destinations/{destination}:
    get:
      summary: Ampersand Get a Destination
      operationId: getDestination
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: destination
        in: path
        required: true
        schema:
          type: string
        description: The destination name.
        example: leadConvertedWebhook
      - name: includeSecrets
        in: query
        required: false
        description: Include secrets in the response
        schema:
          type: boolean
        example: true
      - name: rotate
        in: query
        required: false
        description: Rotate the destination secrets
        schema:
          type: boolean
        example: true
      responses:
        404:
          description: Destination not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DestinationWithSecrets"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update a Destination
      operationId: updateDestination
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: destination
        in: path
        required: true
        schema:
          type: string
        description: The destination ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - updateMask
              - destination
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: |
                    Array of field paths specifying which fields to update. Allowed values include:
                    - name
                    - metadata.url
                    - metadata.headers
                    - metadata.region
                    - metadata.streamName
                    - metadata.endpointUrl
                    - metadata.partitionKeyTemplate
                    - secrets.awsKeyId
                    - secrets.awsSecretKey
                    - secrets.awsSessionToken

                  example: ["name", "metadata.url", "metadata.region", "metadata.streamName"]
                destination:
                  type: object
                  properties:
                    name:
                      type: string
                      description: User-friendly name for the destination
                      example: leadConvertedWebhook
                    metadata:
                      type: object
                      properties:
                        url:
                          type: string
                          description: Webhook URL
                          example: https://webhooks.mailmonkey.com/salesforce-lead-converted
                        headers:
                          $ref: "#/components/schemas/WebhookHeaders"
                        region:
                          type: string
                          description: The AWS region where the kinesis destination is hosted.
                          example: us-east-1
                        streamName:
                          type: string
                          description: The name of the Kinesis stream to send events to.
                          example: my-kinesis-stream
                        endpointUrl:
                          type: string
                          description: The endpoint URL for the Kinesis stream.
                          example: https://kinesis.us-east-1.amazonaws.com
                        partitionKeyTemplate:
                          type: string
                          description: The template for the partition key to use when sending events to Kinesis (a JMESPath template)
                          example: "data.user_id"
                    secrets:
                      type: object
                      description: Secrets for the destination.
                      properties:
                        awsKeyId:
                          type: string
                          description: The AWS access key ID for the Kinesis destination.
                          example: AKIAIOSFODNN7EXAMPLE
                        awsSecretKey:
                          type: string
                          description: The AWS secret access key for the Kinesis destination.
                          example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
                        awsSessionToken:
                          type: string
                          description: The AWS session token for the Kinesis destination.
                          example: AQoEXAMPLEH4aoAH0gNCAPy...
      responses:
        404:
          description: Destination not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        200:
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Destination"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: destinationUpdate
    delete:
      summary: Ampersand Delete a Destination
      operationId: deleteDestination
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: destination
        in: path
        required: true
        schema:
          type: string
        description: The destination ID
      responses:
        204:
          description: Deleted
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /generate-upload-url:
    get:
      summary: Ampersand Generate a Signed URL to Upload a Zip File To.
      operationId: generateUploadUrl
      tags: ["Upload URL"]
      responses:
        200:
          description: Signed URL
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignedUrl"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /orgs:
    post:
      x-speakeasy-ignore: true
      summary: Ampersand Create a New Organization
      operationId: createOrg
      tags: ["Org"]
      requestBody:
        content:
          application/json:
            schema:
              required:
              - label
              type: object
              properties:
                label:
                  type: string
                  description: The organization label.
                  example: org-123
        required: true
      responses:
        201:
          description: The newly created org
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Org"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: org
  /orgs/{orgId}:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand Get an Organization
      operationId: getOrg
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      responses:
        200:
          description: Organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Org"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      x-speakeasy-ignore: true
      summary: Ampersand Update an Organization
      operationId: updateOrg
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - updateMask
              - org
              properties:
                updateMask:
                  type: array
                  items:
                    type: string
                  description: |
                    Array of field paths specifying which fields to update. Allowed values include:
                    - label
                  example: ["label"]
                org:
                  type: object
                  properties:
                    label:
                      type: string
                      description: The organization label.
                      example: org-123
      responses:
        200:
          description: Updated org
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Org"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: orgUpdate
  /orgs/{orgId}/builders:
    get:
      summary: Ampersand List Builders for an Organization
      operationId: listOrgBuilders
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      responses:
        200:
          description: List of builders that are a part of the org
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Builder"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /orgs/{orgId}/invites:
    post:
      x-speakeasy-ignore: true
      summary: Ampersand Invite a User to an Organization
      operationId: createOrgInvite
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      requestBody:
        content:
          application/json:
            schema:
              required:
              - email
              type: object
              properties:
                email:
                  type: string
                  description: The email address of the user to invite.
                  example: alice@company.com
      responses:
        201:
          description: The newly created invite
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invite"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: invite
    get:
      x-speakeasy-ignore: true
      summary: Ampersand List Invites for an Organization
      operationId: listOrgInvites
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      responses:
        200:
          description: List of invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Invite"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /orgs/{orgId}/invites/{inviteId}:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand Get an Invite
      operationId: getOrgInvite
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      - name: inviteId
        in: path
        required: true
        schema:
          type: string
      responses:
        200:
          description: Invite
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Invite"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    delete:
      x-speakeasy-ignore: true
      summary: Ampersand Revoke an Invite
      operationId: deleteOrgInvite
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      - name: inviteId
        in: path
        required: true
        schema:
          type: string
      responses:
        204:
          description: Deleted
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /orgs/{orgId}/memberships:
    post:
      summary: Ampersand Add User to an Organization
      description: Adds a builder to an organization. Two authorization modes - Org owner inviting another user, or self-joining via claimed domain (authenticated user's email domain should be claimed
        by this organization).
      operationId: addUserToOrg
      tags: ["Org"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - builderId
              properties:
                builderId:
                  type: string
                  description: The ID of the builder to add to the organization
                  example: builder-id-123
      responses:
        201:
          description: User successfully added to organization
        400:
          description: Bad Request - Membership already exists or invalid request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        403:
          description: Forbidden - Requires org:owner permission
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        404:
          description: Not Found - Organization or builder not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /my-info:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand Get Information About the Current User
      operationId: getMyInfo
      tags: ["User"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      responses:
        200:
          description: Information about the current user and their organizations and projects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuilderInfo"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /invites:accept:
    post:
      x-speakeasy-ignore: true
      summary: Ampersand Accept an Invite
      operationId: acceptInvite
      tags: ["User"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - invitedEmail
              properties:
                invitedEmail:
                  type: string
                  description: The email address that the invite was sent to
        required: true
      responses:
        200:
          description: Information about the current user and their organizations and projects
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BuilderInfo"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /orgs/{orgId}/billingAccount:
    get:
      x-speakeasy-ignore: true
      summary: Ampersand Get the Billing Account for an Organization
      operationId: getOrgBillingAccount
      tags: ["Billing Account"]
      parameters:
      - name: orgId
        in: path
        required: true
        description: ID of the organization.
        schema:
          type: string
        example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
      responses:
        200:
          description: Billing account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BillingAccount"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /billingAccounts/{billingAccountId}/portalSession:
    post:
      x-speakeasy-ignore: true
      summary: Ampersand Create a Portal Session for a Billing Account
      operationId: createBillingAccountSession
      tags: ["Billing Account"]
      parameters:
      - name: billingAccountId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - redirectUrl
              properties:
                redirectUrl:
                  type: string
                  description: The URL to redirect to once a portal session is exited.
                  example: https://dashboard.withampersand.com/the-current-page
                timeout:
                  type: integer
                  description: The number of seconds before the portal session expires.
                  example: 3600
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - url
                properties:
                  url:
                    type: string
                    description: The URL to redirect to in order to start the portal session.
                    example: https://billing.portal.com/customer/session
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/topics:
    post:
      summary: Ampersand Create a Topic
      operationId: createTopic
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: The name of the topic. Must contain only letters, numbers, and dashes.
                  example: "system-alerts"
                  maxLength: 64
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topic"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        409:
          description: Conflict - A topic with this name already exists in this project. Please choose a different name
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: topic
    get:
      summary: Ampersand List Topics
      operationId: listTopics
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      responses:
        200:
          description: List of topics
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Topic"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/topics/{topicId}:
    patch:
      summary: Ampersand Update a Topic
      operationId: updateTopic
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: topicId
        in: path
        required: true
        description: The topic ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  description: A human-readable name for the topic.
                  example: "Updated System Alerts"
      responses:
        200:
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Topic"
        404:
          description: Topic not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        409:
          description: Conflict - A topic with this name already exists in this project. Please choose a different name
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: updateTopicRequest
    delete:
      summary: Ampersand Delete a Topic
      operationId: deleteTopic
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      - name: topicId
        in: path
        required: true
        description: The topic ID.
        schema:
          type: string
      responses:
        204:
          description: Deleted
        404:
          description: Topic not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/notification-event-topic-routes:
    post:
      summary: Ampersand Create a Notification Event-topic Route
      operationId: createEventTopicRoute
      tags: ["Notification"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - eventType
              - topicId
              properties:
                eventType:
                  type: string
                  description: The type of notification event.
                  enum:
                  - "read.backfill.done"
                  - "connection.created"
                  - "connection.error"
                  - "connection.refreshed"
                  - "connection.deleted"
                  - "installation.created"
                  - "installation.updated"
                  - "installation.deleted"
                  - "read.schedule.paused"
                  - "write.async.done"
                  - "destination.webhook.disabled"
                topicId:
                  type: string
                  description: The ID of the topic to route events to.
            examples:
              route_example:
                summary: Create event-topic route
                value:
                  eventType: "installation.created"
                  topicId: "1234567890abcdef"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationEventTopicRoute"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: eventTopicRoute
    get:
      summary: Ampersand List Notification Event-topic Routes
      operationId: listEventTopicRoutes
      tags: ["Notification"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
      - name: topicId
        in: query
        required: false
        description: Filter by topic ID.
        schema:
          type: string
      - name: eventType
        in: query
        required: false
        description: Filter by notification event type.
        schema:
            # type: string
            # enum:
              # - "read.backfill.done"
              # - "connection.created"
              # - "connection.error"
              # - "installation.created"
              # - "installation.updated"
              # - "installation.deleted"
              # - "read.schedule.paused"
              # - "read.triggered.done"
              # - "destination.webhook.disabled"
          $ref: "#/components/schemas/NotificationEventType"
      responses:
        200:
          description: List of event-topic routes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/NotificationEventTopicRoute"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/notification-event-topic-routes/{routeId}:
    delete:
      summary: Ampersand Delete a Notification Event-topic Route
      operationId: deleteEventTopicRoute
      tags: ["Notification"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
      - name: routeId
        in: path
        required: true
        description: The event-topic route ID.
        schema:
          type: string
      responses:
        204:
          description: Deleted
        404:
          description: Route not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/topic-destination-routes:
    post:
      summary: Ampersand Create a Topic Destination Route
      operationId: createTopicDestinationRoute
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
        example: my-project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - topicId
              - destinationId
              properties:
                topicId:
                  type: string
                  description: The ID of the topic.
                destinationId:
                  type: string
                  description: The ID of the destination.
            examples:
              route_example:
                summary: Create topic destination route
                value:
                  topicId: "1234567890abcdef"
                  destinationId: "abcdef1234567890"
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TopicDestinationRoute"
        400:
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        404:
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        422:
          description: Unprocessable Entity
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
      x-codegen-request-body-name: topicDestinationRoute
    get:
      summary: Ampersand List Topic Destination Routes
      operationId: listTopicDestinationRoutes
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
      - name: topicId
        in: query
        required: false
        description: Filter by topic ID.
        schema:
          type: string
      - name: destinationId
        in: query
        required: false
        description: Filter by destination ID.
        schema:
          type: string
      responses:
        200:
          description: List of topic destination routes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TopicDestinationRoute"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/topic-destination-routes/{routeId}:
    delete:
      summary: Ampersand Delete a Topic Destination Route
      operationId: deleteTopicDestinationRoute
      tags: ["Destination"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        description: The Ampersand project ID or project name.
        schema:
          type: string
      - name: routeId
        in: path
        required: true
        description: The topic destination route ID.
        schema:
          type: string
      responses:
        204:
          description: Deleted
        404:
          description: Route not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/jwt-keys:
    post:
      summary: Ampersand Create a New JWT Key
      description: Creates a new JWT key for the specified project with RSA public key for token verification
      operationId: createJWTKey
      tags: ["JWT Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJWTKeyRequest'
            examples:
              example1:
                summary: Valid RSA JWT key creation
                value:
                  name: "production-key-1"
                  algorithm: "RSA"
                  publicKeyPem: |
                    -----BEGIN PUBLIC KEY-----
                    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
                    fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6
                    V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f
                    -----END PUBLIC KEY-----
      responses:
        '201':
          description: JWT key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKeyResponse'
              examples:
                example1:
                  summary: Successful key creation
                  value:
                    kid: "550e8400-e29b-41d4-a716-446655440000"
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                invalidAlgorithm:
                  summary: Unsupported algorithm
                  value:
                    type: "https://httpstatuses.com/400"
                    title: "Bad Request"
                    status: 400
                    detail: "unsupported algorithm"
                    validationIssues:
                    - field: "algorithm"
                      value: "ECDSA"
                      detail: "only RSA algorithm is supported"
                      remedy: "use 'RSA' as the algorithm"
                invalidPublicKey:
                  summary: Invalid public key format
                  value:
                    type: "https://httpstatuses.com/400"
                    title: "Bad Request"
                    status: 400
                    detail: "invalid public key"
                    validationIssues:
                    - field: "publicKeyPem"
                      detail: "invalid RSA public key in PEM format"
                      remedy: "provide a valid RSA public key in PEM format"
        '404':
          description: Project not found
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                projectNotFound:
                  summary: Project does not exist
                  value:
                    type: "https://httpstatuses.com/404"
                    title: "Not Found"
                    status: 404
                    detail: "project not found"
                    validationIssues:
                    - field: "projectId"
                      detail: "project not found"
                      remedy: "check the project ID and try again"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    get:
      summary: Ampersand List JWT Keys
      description: Retrieves all JWT keys for the specified project, with optional filtering for active keys only
      operationId: listJWTKeys
      tags: ["JWT Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: active
        in: query
        description: Filter to only return active JWT keys
        required: false
        schema:
          type: boolean
          default: false
        example: true
      responses:
        '200':
          description: List of JWT keys retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Multiple JWT keys
                  value:
                  - id: "550e8400-e29b-41d4-a716-446655440000"
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    label: "production-key-1"
                    algorithm: "RSA"
                    publicKeyPem: |
                      -----BEGIN PUBLIC KEY-----
                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
                      -----END PUBLIC KEY-----
                    active: true
                    createTime: "2024-01-15T10:30:00Z"
                    updateTime: "2024-01-15T10:30:00Z"
                  - id: "550e8400-e29b-41d4-a716-446655440001"
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    label: "development-key-1"
                    algorithm: "RSA"
                    publicKeyPem: |
                      -----BEGIN PUBLIC KEY-----
                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA5g6xh6m3iLtUfOqn/W52
                      -----END PUBLIC KEY-----
                    active: false
                    createTime: "2024-01-10T08:15:00Z"
                    updateTime: "2024-01-12T14:20:00Z"
                emptyList:
                  summary: No JWT keys found
                  value: []
        '400':
          description: Bad request - invalid project ID
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
  /projects/{projectIdOrName}/jwt-keys/{keyId}:
    get:
      summary: Ampersand Get a Specific JWT Key
      description: Retrieves a specific JWT key by its ID within the specified project
      operationId: getJWTKey
      tags: ["JWT Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      responses:
        '200':
          description: JWT key retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Single JWT key details
                  value:
                    id: "550e8400-e29b-41d4-a716-446655440000"
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    label: "production-key-1"
                    algorithm: "RSA"
                    publicKeyPem: |
                      -----BEGIN PUBLIC KEY-----
                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
                      -----END PUBLIC KEY-----
                    active: true
                    createTime: "2024-01-15T10:30:00Z"
                    updateTime: "2024-01-15T10:30:00Z"
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                keyNotFound:
                  summary: Key does not exist
                  value:
                    type: "https://httpstatuses.com/404"
                    title: "Not Found"
                    status: 404
                    detail: "JWT key not found"
                    remedy: "check the key ID and project ID are both correct, and try again"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    patch:
      summary: Ampersand Update a JWT Key
      description: Updates specific fields of a JWT key using field masks. Currently supports updating the 'active' status and 'name' field.
      operationId: updateJWTKey
      tags: ["JWT Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchJWTKeyRequest'
            examples:
              deactivateKey:
                summary: Deactivate a JWT key
                value:
                  updateMask: ["active"]
                  jwtKey:
                    active: false
              renameKey:
                summary: Rename a JWT key
                value:
                  updateMask: ["name"]
                  jwtKey:
                    name: "updated-key-name"
              updateMultiple:
                summary: Update both name and active status
                value:
                  updateMask: ["active", "name"]
                  jwtKey:
                    active: false
                    name: "deprecated-key"
      responses:
        '200':
          description: JWT key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTKey'
              examples:
                example1:
                  summary: Updated JWT key
                  value:
                    id: "550e8400-e29b-41d4-a716-446655440000"
                    projectId: "123e4567-e89b-12d3-a456-426614174000"
                    label: "updated-key-name"
                    algorithm: "RSA"
                    publicKeyPem: |
                      -----BEGIN PUBLIC KEY-----
                      MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
                      -----END PUBLIC KEY-----
                    active: false
                    createTime: "2024-01-15T10:30:00Z"
                    updateTime: "2024-01-16T15:45:00Z"
        '400':
          description: Bad request - invalid update mask or missing project/key ID
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                invalidMask:
                  summary: Invalid update mask
                  value:
                    type: "https://httpstatuses.com/400"
                    title: "Bad Request"
                    status: 400
                    detail: "Invalid update mask"
                    remedy: "Allowed masks: 'active' and 'name'"
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        '422':
          description: Unprocessable entity - value not found for mask
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                missingValue:
                  summary: Missing value for update mask
                  value:
                    type: "https://httpstatuses.com/422"
                    title: "Unprocessable Entity"
                    status: 422
                    detail: "value not found for mask"
                    validationIssues:
                    - field: "jwtKey"
                      detail: "required field missing for specified mask"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    delete:
      summary: Ampersand Delete a JWT Key
      description: Permanently deletes a JWT key from the specified project
      operationId: deleteJWTKey
      tags: ["JWT Key"]
      parameters:
      - name: projectIdOrName
        in: path
        required: true
        schema:
          type: string
        description: Ampersand Project ID or name.
      - name: keyId
        in: path
        required: true
        schema:
          type: string
        description: The JWT key ID.
      responses:
        '204':
          description: JWT key deleted successfully (no content)
        '404':
          description: JWT key not found
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
              examples:
                keyNotFound:
                  summary: Key does not exist
                  value:
                    type: "https://httpstatuses.com/404"
                    title: "Not Found"
                    status: 404
                    detail: "JWT key not found"
                    remedy: "check the key ID and project ID are both correct, and try again"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"

  /claimed-domains:
    get:
      operationId: checkClaimedDomain
      summary: Ampersand Check if a Domain is Claimed
      description: Returns claimed domain information if authenticated user is an owner of the organization that claimed the domain, or if the user's email domain matches the claimed domain.
      tags: ["Org"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      parameters:
      - name: domain
        in: query
        required: true
        description: >
          Accepts an email address, domain name, or URL. The domain will be automatically extracted:
          for emails, the portion after @ is used (e.g., "user@example.com" becomes "example.com");
          for URLs, the hostname is extracted (e.g., "https://www.example.com" becomes "example.com").
        schema:
          type: string
        example: xyz@withampersand.com
      responses:
        200:
          description: Domain claim status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ClaimedDomainResponse"
        400:
          description: Bad Request - Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        404:
          description: Domain not claimed
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
    post:
      operationId: claimDomain
      summary: Ampersand Claim a Domain
      description: Claim a domain for an organization. Accepts email, domain, or URL.
      tags: ["Org"]
      security: # Only bearer auth works for this endpoint
      - Bearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - domain
              - parentId
              - parentType
              properties:
                domain:
                  type: string
                  description: >
                    Accepts an email address, domain name, or URL. The domain will be automatically extracted:
                    for emails, the portion after @ is used (e.g., "user@example.com" becomes "example.com");
                    for URLs, the hostname is extracted (e.g., "https://www.example.com" becomes "example.com").
                  example: xyz@withampersand.com
                parentId:
                  type: string
                  description: ID of the parent entity claiming the domain
                  example: orgId
                parentType:
                  type: string
                  description: Type of the parent entity
                  example: org
        required: true
      responses:
        201:
          description: Domain claimed successfully
        400:
          description: Bad Request - Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/InputValidationProblem"
        409:
          description: Domain already claimed by another organization
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"

  /orgs/{orgId}/claimed-domains:
    get:
      operationId: listOrgClaimedDomains
      summary: Ampersand List Organization's Claimed Domains
      description: Get all domains claimed by a specific organization
      tags: ["Org"]
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
        description: Organization ID
        example: orgId
      responses:
        200:
          description: List of claimed domains for the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ClaimedDomainResponse"
        404:
          description: Organization not found
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"
        default:
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: "../problem/problem.yaml#/components/schemas/ApiProblem"

## Schema Components ##
components:
  schemas:
    Org:
      title: Organization
      required:
      - id
      - label
      - createTime
      - defaultTeamId
      type: object
      properties:
        id:
          type: string
          description: The organization ID.
          example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
        label:
          type: string
          description: The organization label.
          example: Acme Inc
        defaultTeamId:
          type: string
          description: The ID of the Everyone team for the org.
        createTime:
          type: string
          description: The time the organization was created.
          format: date-time
        updateTime:
          type: string
          description: The time the organization was updated.
          format: date-time
    # NOTE: If you change this schema, also update DestinationWithSecrets schema below.
    Destination:
      title: Destination
      required:
      - id
      - name
      - type
      - metadata
      - createTime
      type: object
      properties:
        id:
          type: string
          description: The destination ID.
        name:
          type: string
          description: User-defined name for the destination
          example: leadConvertedWebhook
        type:
          type: string
          description: The type of the destination
          example: webhook
        metadata:
          type: object
          properties:
            url:
              type: string
              description: Webhook URL
              example: https://webhooks.mailmonkey.com/salesforce-lead-converted
            headers:
              $ref: "#/components/schemas/WebhookHeaders"
            streamName:
              type: string
              description: The name of the Kinesis stream
              example: my-data-stream
            region:
              type: string
              description: The AWS region for the destination
              example: us-east-1
            partitionKeyTemplate:
              type: string
              description: Template for generating partition keys
              example: "{{.integration_id}}"
        createTime:
          type: string
          description: The time the destination was created.
          format: date-time
        updateTime:
          type: string
          description: The time the destination was updated.
          format: date-time
    # NOTE: If you change this schema, also update Destination schema above.
    DestinationWithSecrets:
      title: DestinationWithSecrets
      description: Destination object with secrets field (returned by getDestination when includeSecrets is true)
      required:
      - id
      - name
      - type
      - metadata
      - createTime
      type: object
      properties:
        id:
          type: string
          description: The destination ID.
        name:
          type: string
          description: User-defined name for the destination
          example: leadConvertedWebhook
        type:
          type: string
          description: The type of the destination
          example: webhook
        metadata:
          type: object
          properties:
            url:
              type: string
              description: Webhook URL
              example: https://webhooks.mailmonkey.com/salesforce-lead-converted
            headers:
              $ref: "#/components/schemas/WebhookHeaders"
            streamName:
              type: string
              description: The name of the Kinesis stream
              example: my-data-stream
            region:
              type: string
              description: The AWS region for the destination
              example: us-east-1
            partitionKeyTemplate:
              type: string
              description: Template for generating partition keys
              example: "{{.integration_id}}"
        createTime:
          type: string
          description: The time the destination was created.
          format: date-time
        updateTime:
          type: string
          description: The time the destination was updated.
          format: date-time
        secrets:
          type: object
          description: Destination secrets (only included when includeSecrets is true)
          properties:
            webhookSigningKey:
              type: string
              description: Webhook signing key for the destination (only included for webhook destinations)
    Project:
      title: Project
      required:
      - appName
      - createTime
      - id
      - name
      - orgId
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the project.
          example: proj_9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
        name:
          type: string
          description: The unique name for the project.
          example: mailmonkey-staging
        appName:
          type: string
          description: The display name of the application, shown to end users during the connection flow.
          example: MailMonkey
        orgId:
          type: string
          description: The ID of the organization that this project belongs to.
          example: 9f7c3e2a-61b8-4f5c-8d1a-eb24f3b05d79
        createTime:
          type: string
          description: The time the project was created.
          format: date-time
        updateTime:
          type: string
          description: The time the project was updated.
          format: date-time
        entitlements:
          type: object
          description: Plan-based feature flags for the project. These are managed by Ampersand and cannot be set via the API.
          properties:
            brandingRemoval:
              type: object
              required:
              - value
              x-go-type-skip-optional-pointer: true
              description: Controls whether Ampersand branding is removed from the embeddable UI components.
              properties:
                value:
                  type: boolean
                  description: True if Ampersand branding has been removed for this project.
    ProviderApp:
      title: Provider App
      required:
      - clientId
      - createTime
      - id
      - projectId
      - provider
      type: object
      properties:
        id:
          type: string
          description: The provider app ID.
          example: provider-app-123
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        externalRef:
          type: string
          description: The ID used by the provider to identify the app (optional).
          example: external-id-123
        provider:
          type: string
          description: The SaaS provider that this app connects to.
          example: salesforce
        clientId:
          type: string
          description: The OAuth client ID for this app.
          example: client-id-123
        scopes:
          type: array
          description: The OAuth scopes for this app.
          items:
            type: string
            example:
            - oauth
            - offline
            - crm.read
        metadata:
          $ref: "#/components/schemas/ProviderAppMetadata"
        createTime:
          type: string
          description: The time the provider app was created.
          format: date-time
        updateTime:
          type: string
          description: The time the provider app was updated.
          format: date-time
    ProviderAppMetadata:
      title: Provider App Metadata
      type: object
      description: Provider-specific configuration that extends the standard OAuth flow.
      properties:
        authQueryParams:
          type: object
          description: Additional query parameters to include in the OAuth authorization URL (e.g., optional_scope for HubSpot).
          additionalProperties:
            type: array
            items:
              type: string
          example:
            optional_scope:
            - automation.sequences.read
        providerParams:
          type: object
          description: Provider-specific string values keyed by names (e.g., packageInstallURL for Salesforce, gcpProjectId and gcpPubSubTopicName for Gmail).
          additionalProperties:
            type: string
          example:
            packageInstallURL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789
            gcpProjectId: my-gcp-project
            gcpPubSubTopicName: my-topic
    Integration:
      title: Integration
      required:
      - createTime
      - id
      - latestRevision
      - name
      - projectId
      - provider
      type: object
      properties:
        id:
          type: string
          description: The integration ID.
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        name:
          type: string
          description: The integration name.
          example: read-accounts
        provider:
          type: string
          description: The SaaS provider that this integration connects to.
          example: salesforce
        createTime:
          type: string
          description: The time the integration was created.
          format: date-time
        updateTime:
          type: string
          description: The time the integration was last updated.
          format: date-time
        latestRevision:
          $ref: "#/components/schemas/Revision"
    Revision:
      title: Revision
      required:
      - content
      - createTime
      - id
      - specVersion
      type: object
      properties:
        id:
          type: string
          description: The revision ID.
          example: revision-id-1
        specVersion:
          type: string
          description: The spec version string.
          example: 1.0.0
        createTime:
          type: string
          description: The time the revision was created.
          format: date-time
        content:
          $ref: "../manifest/manifest.yaml#/components/schemas/Integration"
    HydratedRevision:
      title: Hydrated Revision
      required:
      - content
      - createTime
      - id
      - specVersion
      type: object
      properties:
        id:
          type: string
          description: The revision ID.
          example: "f0e1d2c3-b4a5-6789-0abc-def123456789"
        specVersion:
          type: string
          description: The spec version string.
          example: 1.0.0
        createTime:
          type: string
          description: The time the revision was created.
          format: date-time
        content:
          $ref: "../manifest/manifest.yaml#/components/schemas/HydratedIntegration"
    Installation:
      title: Installation
      required:
      - config
      - connection
      - createTime
      - createdBy
      - healthStatus
      - id
      - integrationId
      - projectId
      type: object
      properties:
        id:
          type: string
          description: The installation ID.
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        integrationId:
          type: string
          description: The integration ID.
        group:
          $ref: "#/components/schemas/Group"
        healthStatus:
          type: string
          enum: [healthy, unhealthy]
          description: The health status of the installation.
          example: healthy
        lastOperationStatus:
          type: string
          enum: [success, failure, in_progress]
          description: |
            The status of the latest operation for this installation.
          example: success
        connection:
          $ref: "#/components/schemas/Connection"
        createTime:
          type: string
          description: The time the installation was created.
          format: date-time
        createdBy:
          type: string
          description: The person who did the installation, in the format of "consumer:{consumer-id}".
          example: consumer:consumer-123
        updateTime:
          type: string
          description: The time the installation was last updated with a new config.
          format: date-time
        config:
          $ref: "#/components/schemas/Config"
    JSONPatchOperation:
      title: JSON Patch Operation
      description: |
        Represents a single JSON Patch operation (RFC 6902).
        Only supports add, remove, and replace operations for config updates.
      required:
      - op
      - path
      type: object
      properties:
        op:
          type: string
          enum: [add, remove, replace]
          description: |
            The operation to perform.
            - "add": Adds a new field or replaces an existing one at the specified path
            - "remove": Removes the field at the specified path
            - "replace": Replaces the value at the specified path
          example: replace
        path:
          type: string
          description: |
            JSON Pointer path to the field to operate on (RFC 6901).
            All paths must start with "/" (e.g., "/schedule", "/selectedFields/phone").
          example: /schedule
        value:
          description: |
            The value to set for add/replace operations.
            Not used for remove operations.
          example: "*/10 * * * *"
    Config:
      title: Config
      required:
      - content
      - createTime
      - createdBy
      - id
      - revisionId
      type: object
      properties:
        id:
          type: string
          description: The config ID.
          example: config-123
        revisionId:
          type: string
          description: >
            The ID of the revision that was current when this config was created or last updated. 
          example: revision-123
        createTime:
          type: string
          description: The time the config was created.
          format: date-time
        createdBy:
          type: string
          description: The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".
          example: builder:builder-123
        content:
          $ref: "../config/config.yaml#/components/schemas/ConfigContent"
    Connection:
      title: Connection
      required:
      - id
      - createTime
      - group
      - consumer
      - projectId
      - provider
      - authScheme
      - status
      type: object
      properties:
        id:
          type: string
          description: The connection ID.
          example: connection-123
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        provider:
          type: string
          description: The SaaS provider that this Connection is for.
          example: salesforce
        providerApp:
          $ref: "#/components/schemas/ProviderApp"
        group:
          $ref: "#/components/schemas/Group"
        consumer:
          $ref: "#/components/schemas/Consumer"
        providerWorkspaceRef:
          type: string
          description: If available, the identifier for the provider workspace (e.g. the Salesforce subdomain)
          example: provider-workspace-123
        providerConsumerRef:
          type: string
          description: If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of 
            https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA)
          example: provider-consumer-123
        createTime:
          type: string
          description: The time the connection was created.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
        updateTime:
          type: string
          description: The time the connection was last updated.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
        authScheme:
          type: string
          description: The authentication scheme used for this connection.
          example: oauth2/authorizationCode
          enum: [none, apiKey, basic, oauth2/authorizationCode, oauth2/authorizationCodePKCE, oauth2/clientCredentials, oauth2/password]
        status:
          type: string
          description: |
            The status of the connection.
            - `created`: The connection has just been created or the access token was just refreshed.
            - `working`: The connection has successfully been used to make a request.
            - `bad_credentials`: The connection encountered credential-related issues when making a request, or when attempting to refresh the access token.
          example: working
          enum: [created, working, bad_credentials]
        oauth2AuthorizationCode:
          $ref: "#/components/schemas/Oauth2AuthorizationCodeTokensOnly"
        apiKey:
          type: string
          description: The API key used while making the connection.
          example: api-key-123
        providerMetadata:
          $ref: "#/components/schemas/ProviderMetadata"
    Oauth2AuthorizationCodeTokensOnly:
      title: OAuth2 AuthorizationCode Token
      type: object
      properties:
        accessToken:
          type: object
          required:
          - token
          description: The access token for the connection.
          properties:
            token:
              type: string
            issuedAt:
              type: string
              format: date-time
              example: "2024-04-22T18:55:28.456076Z"
            expiresAt:
              type: string
              format: date-time
              example: "2024-10-22T18:55:28.456076Z"
        refreshToken:
          type: object
          required:
          - token
          description: The refresh token to use for the connection.
          properties:
            token:
              type: string
            issuedAt:
              type: string
              format: date-time
              example: "2024-04-22T18:55:28.456076Z"
            expiresAt:
              type: string
              format: date-time
              example: "2024-10-22T18:55:28.456076Z"
        scopes:
          type: array
          items:
            type: string
          description: The scopes for the tokens.
    Oauth2AuthorizationCode:
      title: OAuth2 Authorization Code
      type: object
      properties:
        accessToken:
          type: object
          required:
          - token
          description: The access token for the connection.
          properties:
            token:
              type: string
            expiresAt:
              type: string
              format: date-time
            issuedAt:
              type: string
              format: date-time
        refreshToken:
          type: object
          required:
          - token
          description: The refresh token to use for the connection.
          properties:
            token:
              type: string
            expiresAt:
              type: string
              format: date-time
            issuedAt:
              type: string
              format: date-time
        scopes:
          type: array
          items:
            type: string
          description: The scopes for the tokens.
    UpdateConnectionRequest:
      title: Update Connection Request
      description: Specify which fields to update in `updateMask` and provide corresponding values in `connection`. Fields in `connection` not listed in `updateMask` are ignored.
      type: object
      required:
      - updateMask
      - connection
      properties:
        updateMask:
          type: array
          items:
            type: string
            enum:
            - providerWorkspaceRef
            - providerMetadata
            - apiKey
            - basicAuth
            - oauth2ClientCredentials
            - oauth2PasswordCredentials
          description: Fields to update. Each entry must have a corresponding value in `connection`. Credential fields (`apiKey`, `basicAuth`, `oauth2ClientCredentials`, `oauth2PasswordCredentials`) 
            must match the connection's existing auth scheme.
          example: ["apiKey"]
        connection:
          $ref: "#/components/schemas/ConnectionRequest"
    ConnectionRequest:
      title: Connection Request Body
      type: object
      properties:
        providerWorkspaceRef:
          type: string
          description: The ID of the provider workspace that this connection belongs to.
        providerMetadata:
          $ref: "#/components/schemas/ProviderMetadata"
        groupName:
          type: string
          description: The name of the user group that has access to this installation.
        groupRef:
          type: string
          description: The ID of the user group that has access to this installation.
          example: group-123
        consumerName:
          type: string
          description: The name of the consumer that has access to this installation.
        consumerRef:
          type: string
          description: The consumer reference.
        provider:
          type: string
          description: The provider name (e.g. "salesforce", "hubspot")
        apiKey:
          type: string
          description: The API key to use for the connection.
        customAuth:
          type: object
          description: Values used for custom auth input variables.
          additionalProperties:
            type: string
            nullable: false
          example:
            apiKey: "abcd1234"
            password: "secret"
        basicAuth:
          type: object
          required:
          - username
          - password
          properties:
            username:
              type: string
              description: The username to use for the connection.
            password:
              type: string
              description: The password to use for the connection.
        oauth2ClientCredentials:
          type: object
          required:
          - clientId
          - clientSecret
          properties:
            clientId:
              type: string
              description: The client ID to use for the connection.
            clientSecret:
              type: string
              description: The client secret to use for the connection.
            scopes:
              type: array
              items:
                type: string
              description: The scopes for the tokens.
        oauth2PasswordCredentials:
          type: object
          required:
          - username
          - password
          - clientId
          - clientSecret
          properties:
            username:
              type: string
              description: The username to use for the connection.
            password:
              type: string
              description: The password to use for the connection.
            clientId:
              type: string
              description: The client ID to use for the connection.
            clientSecret:
              type: string
              description: The client secret to use for the connection.
            scopes:
              type: array
              items:
                type: string
              description: The scopes for the tokens.
        oauth2AuthorizationCode:
          $ref: "#/components/schemas/Oauth2AuthorizationCode"
    GenerateConnectionRequest:
      title: Generate Connection Request
      allOf:
      - $ref: '#/components/schemas/ConnectionRequest'
      - type: object
        required:
        - groupRef
        - consumerRef
        - provider

    Group:
      title: Group
      required:
      - createTime
      - groupName
      - groupRef
      - projectId
      type: object
      properties:
        groupRef:
          type: string
          description: The ID of the user group that has access to this installation.
          example: group-123
        groupName:
          type: string
          description: The name of the user group that has access to this installation.
          example: Super Customer
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        createTime:
          type: string
          description: The time the group was created.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
        updateTime:
          type: string
          description: The time the group was last updated.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
    Consumer:
      title: Consumer
      required:
      - consumerName
      - consumerRef
      - createTime
      - projectId
      type: object
      properties:
        consumerRef:
          type: string
          description: The consumer reference.
          example: consumer-123
        consumerName:
          type: string
          description: The name of the consumer.
          example: Super Customer
        projectId:
          type: string
          description: The Ampersand project ID.
          example: project-456
        createTime:
          type: string
          description: The time the consumer was created.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
        updateTime:
          type: string
          description: The time the consumer was last updated.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
    Operation:
      title: Operation
      required:
      - projectId
      - integrationId
      - installationId
      - configId
      - actionType
      - status
      - id
      type: object
      properties:
        projectId:
          type: string
          description: The Ampersand project ID.
          example: "123e4567-e89b-12d3-a456-426614174000"
        integrationId:
          type: string
          description: The integration ID.
        configId:
          type: string
          description: The config ID.
          example: "a1b2c3d4-e5f6-4789-a012-3456789abcde"
        actionType:
          type: string
          description: |
            The type of action that was performed (`read`, `write`, or `subscribe`).
          example: read
        id:
          type: string
          description: Unique identifier for this operation. Use this to fetch operation details or list logs for debugging.
        installationId:
          type: string
          description: The Ampersand installation ID (customer instance) that this operation ran for.
        status:
          type: string
          description: |
            The status of the operation.
            - `success`: The operation completed successfully
            - `failure`: The operation failed 
            - `in_progress`: The operation is currently running
          example: success
        result:
          type: string
          description: |
            A human-readable summary of what the operation accomplished. Examples: `[contact] No new data found`, `Batch write completed (3 succeeded, 1 failed)`. May be absent.
          example: "[contact] No new data found"
        metadata:
          type: object
          description: Additional operation details (e.g. objects, retry info, backfill progress, successfulRecordIds).
          properties:
            objects:
              type: array
              items:
                type: string
            retry:
              type: object
              properties:
                attempts:
                  type: integer
                lastAttempt:
                  type: string
                  format: date-time
                lastNotified:
                  type: string
                  format: date-time
            progress:
              type: object
              description: Only present for backfill read operations.
              properties:
                installationId:
                  type: string
                objectName:
                  type: string
                operationId:
                  type: string
                recordsProcessed:
                  type: integer
                recordsEstimatedTotal:
                  type: integer
                  description: Only present for some providers (e.g. Salesforce, HubSpot).
            successfulRecordIds:
              type: array
              items:
                type: string
              description: Provider-assigned IDs of successfully created or updated records. Only present for write operations.
          example:
            objects: [contact]
            progress:
              installationId: "66438162-5299-4669-a41d-85c5a3b1a83e"
              objectName: contact
              operationId: "3efc0f0f-4bb9-498f-996c-9893d98ca4b5"
              recordsProcessed: 1250
              recordsEstimatedTotal: 5000
        createTime:
          type: string
          description: The time the operation was created.
          format: date-time
          example: 2023-07-13T21:34:44.816354Z
    BackfillProgress:
      title: BackfillProgress
      type: object
      required:
      - installationId
      - objectName
      - operationId
      - recordsProcessed
      properties:
        installationId:
          type: string
          description: The installation ID.
        objectName:
          type: string
          description: The object being synced (e.g., contact, account).
        operationId:
          type: string
          description: The ID of the backfill operation.
        recordsProcessed:
          type: integer
          description: The number of records processed so far. Updates as more records are read during the backfill.
          example: 1250
        recordsEstimatedTotal:
          type: integer
          description: The estimated total number of records to process. Only present for Salesforce and HubSpot; other connectors omit this field.
          example: 5000
        createTime:
          type: string
          format: date-time
          description: When the backfill operation started.
        updateTime:
          type: string
          format: date-time
          description: When progress was last updated.
    Log:
      title: Log
      type: object
      required:
      - timestamp
      - severity
      - message
      properties:
        timestamp:
          type: string
          description: The time the log was created.
          example: 2023-07-13T21:34:44.816354Z
        message:
          type: object
          description: The log message object.
          required:
          - msg
          properties:
            msg:
              type: string
              description: The use-readable message.
              example: "This is a log message"
            error:
              type: string
              description: The error message, if there has been an error.
            operation_id:
              type: string
              description: The operation ID.
            details:
              type: object
              description: The details of the log.
              additionalProperties:
                type: string
              example:
                "request": "GET /api/v1/users"
          additionalProperties: true
        severity:
          type: string
          description: The severity of the log.
          example: DEBUG
    SignedUrl:
      title: Signed URL
      type: object
      required:
      - url
      - bucket
      - path
      properties:
        url:
          type: string
          description: The signed URL to upload the zip file to.
        bucket:
          type: string
          description: The bucket (will match the bucket part of the url).
        path:
          type: string
          description: The path (will match the path part of the url).
    ApiKeyScopes:
      title: API Key Scopes
      type: array
      description: The scopes for the API key.
      items:
        type: string
        example:
        - full
        - frontend
    ApiKeyRequest:
      title: API Key Request
      type: object
      required:
      - label
      properties:
        label:
          type: string
          description: A short name for the API key.
          example: MailMonkey API Key
        scopes:
          $ref: "#/components/schemas/ApiKeyScopes"
    ApiKey:
      title: API Key
      type: object
      required:
      - key
      - projectId
      - label
      - scopes
      properties:
        key:
          type: string
          description: The API key.
          example: api-key-123
        label:
          type: string
          description: A short name for the API key.
          example: MailMonkey API Key
        scopes:
          $ref: "#/components/schemas/ApiKeyScopes"
        projectId:
          type: string
          description: The project ID.
          example: my-project
        active:
          type: boolean
          description: Whether the API key is active.
          example: true
    PatchApiKeyRequest:
      title: Patch API Key Request
      type: object
      required:
      - updateMask
      - apiKey
      properties:
        updateMask:
          type: array
          items:
            type: string
          description: |
            Array of field paths specifying which fields to update. Allowed values include:
            - active
            - label
            - scopes
          example: ["active", "label"]
        apiKey:
          type: object
          properties:
            label:
              type: string
              description: A short name for the API key.
              example: MailMonkey API Key
            active:
              type: boolean
              description: Whether the API key is active.
              example: true
            scopes:
              $ref: "#/components/schemas/ApiKeyScopes"
    WebhookHeaders:
      title: Webhook Headers
      type: object
      nullable: true
      description: Additional headers to add when Ampersand sends a webhook message
      additionalProperties:
        type: string
        nullable: false
      example:
        Authorization: "Bearer 1234"
    Invite:
      title: Invite
      type: object
      required:
      - id
      - invitedEmail
      - createTime
      - parentId
      - parentType
      - status
      properties:
        id:
          type: string
          description: The invite ID.
        invitedEmail:
          type: string
          description: The email address of the person invited.
        parentType:
          type: string
          enum: [org]
          description: The type of entity that the person is invited to.
        parentId:
          type: string
          description: The ID of the parent (e.g. org ID).
        status:
          type: string
          description: The status of the invite.
          enum: [pending, accepted, revoked, expired]
        createTime:
          type: string
          description: The time the invite was created.
          format: date-time
        updateTime:
          type: string
          description: The time the invite was updated.
          format: date-time
    Builder:
      title: Builder
      type: object
      required:
      - id
      - idpProvider
      - idpRef
      - createTime
      properties:
        id:
          type: string
          description: The builder ID.
          example: builder-id-123
        idpProvider:
          type: string
          description: The identity provider
          example: clerk
        idpRef:
          type: string
          description: ID used by the identity provider
        createTime:
          type: string
          description: The time that the builder joined Ampersand.
          format: date-time
        firstName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        primaryEmail:
          type: string
    BillingAccount:
      title: Billing Account
      type: object
      required:
      - id
      - displayName
      - billingProvider
      - billingProviderRef
      properties:
        id:
          type: string
          description: The billing account ID.
          example: billing-account-123
        displayName:
          type: string
          description: The display name of the billing account.
          example: Acme Inc
        billingProvider:
          type: string
          description: The billing provider that this account is associated with.
          example: stripe
        billingProviderRef:
          type: string
          description: The ID used by the billing provider to identify the account.
          example: acct_1J2k3l4m5n6o7p8q9r0s
        createTime:
          type: string
          description: The time the billing account was created.
          format: date-time
        updateTime:
          type: string
          description: The time the billing account was last updated.
          format: date-time
    BuilderInfo:
      title: Builder Info
      type: object
      required:
      - builder
      - projectRoles
      properties:
        builder:
          $ref: "#/components/schemas/Builder"
        projectRoles:
          type: object
          description: A map of project IDs to project roles for the builder.
          additionalProperties:
            type: object
            required:
            - role
            - principalType
            - principalId
            - project
            properties:
              role:
                type: string
                description: The role of the builder in the project.
                example: admin
              principalType:
                type: string
                description: The type of the principal.
                enum:
                - team
                - builder
              principalId:
                type: string
                description: The ID of the team or builder.
                example: builder-id-123
              project:
                $ref: "#/components/schemas/Project"
        orgRole:
          type: object
          required:
          - role
          - principalType
          - principalId
          - org
          properties:
            role:
              type: string
              description: The role of the builder in the org.
              example: admin
            principalType:
              type: string
              description: The type of the principal.
              enum:
              - team
              - builder
            principalId:
              type: string
              description: The ID of the team or builder.
              example: builder-id-123
            org:
              $ref: "#/components/schemas/Org"
            # This schema actually isn't used in the manifest but it is used by the GetObjectMetadata endpoint
    ObjectMetadata:
      title: Object Metadata
      type: object
      required:
      - name
      - fields
      properties:
        name:
          type: string
          description: The provider name of the object
          example: "contact"
        displayName:
          type: string
          description: Human-readable name of the object
          example: "Contact"
        mappedObjectName:
          type: string
          description: The mapped name of the object as defined in your integration config, if a mapping was applied. Only present when using the installation-scoped metadata endpoint.
          example: "people"
        fields:
          type: object
          description: Map of field metadata keyed by field name
          additionalProperties:
            $ref: "../manifest/manifest.yaml#/components/schemas/FieldMetadata"
    ProviderMetadata:
      title: Provider Metadata
      type: object
      additionalProperties:
        $ref: "#/components/schemas/ProviderMetadataInfo"
    ProviderMetadataInfo:
      title: Provider Metadata Info
      type: object
      required:
      - value
      - source
      properties:
        value:
          type: string
          description: The value of the metadata field
          example: "1234567890"
        source:
          type: string
          description: The source of the metadata field
          enum: [input, token, provider]
          example: "input"
        displayName:
          type: string
          description: The human-readable name for the field
          example: "Account ID"
    PaginationInfo:
      title: Pagination Information
      type: object
      required:
      - done
      properties:
        done:
          type: boolean
          description: If set to true, this is the last page of results for the given operation. There are no more results & there will be no nextPageToken sent when done is true.
          example: false
        nextPageToken:
          type: string
          description: If present, set this value against your 'pageToken' query parameter in the next API call, which will retrieve the next set of results.
          example: Q9JT+2qfys28V4ODN+UayA==
    UpdateMask:
      type: array
      items:
        type: string
      description: |
        Array of field paths specifying which fields to update.
        Uses dot notation for nested fields (e.g., "config.revision", "metadata.tags").

        **Field Path Rules:**
        - Use dot notation for nested objects: `parent.child.field`
        - Escape special characters: `field\.with\.dots`, `field\:with\:colons`
        - Array elements not directly addressable
        - Object names can be specified directly (e.g., "config.content.read.objects.contacts")
        - The * operator in paths like "config.content.read.objects.*" allows you to specify any object name
          - Example: "config.content.read.objects.*" pattern allows "config.content.read.objects.contacts", "config.content.read.objects.leads", etc.

      example: ["name", "config.content.read.objects.contacts", "config.content.write.objects.leads"]
    CreateJWTKeyRequest:
      type: object
      required:
      - label
      - algorithm
      - publicKeyPem
      properties:
        label:
          type: string
          description: Human-readable label for the JWT key
          minLength: 1
          maxLength: 255
          example: "production-key-1"
        algorithm:
          type: string
          description: The cryptographic JWT signing algorithm (currently only RS256 is supported)
          enum: ["RS256"]
          example: "RS256"
        publicKeyPem:
          type: string
          description: RSA public key in PEM format for JWT signature verification
          format: pem
          example: |
            -----BEGIN PUBLIC KEY-----
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
            fGnJm6gOdrj8ym3rFkEjWT2btf2QisEgQG5WQwTfEUvUNR8JW5FQ0mKJ5I4LhXq6
            V5gN6kSKs2cUdD8Ky7Lj7kqn6I3l3r3F2fK9MFjZ8tU5z4z4yHdF6W2C3k5vf3f
            -----END PUBLIC KEY-----
    JWTKeyResponse:
      type: object
      required:
      - kid
      properties:
        kid:
          type: string
          format: uuid
          description: The unique key identifier (key ID) for the created JWT key
          example: "550e8400-e29b-41d4-a716-446655440000"
    JWTKey:
      type: object
      required:
      - id
      - projectId
      - label
      - algorithm
      - publicKeyPem
      - active
      - createTime
      - updateTime
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the JWT key
          example: "550e8400-e29b-41d4-a716-446655440000"
        projectId:
          type: string
          format: uuid
          description: The project this JWT key belongs to
          example: "123e4567-e89b-12d3-a456-426614174000"
        label:
          type: string
          description: Human-readable name for the JWT key
          example: "production-key-1"
        algorithm:
          type: string
          description: The cryptographic algorithm used
          enum: ["RSA"]
          example: "RSA"
        publicKeyPem:
          type: string
          description: RSA public key in PEM format
          format: pem
          example: |
            -----BEGIN PUBLIC KEY-----
            MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4f5wg5l2hKsTeNem/V41
            -----END PUBLIC KEY-----
        active:
          type: boolean
          description: Whether the JWT key is currently active and can be used for verification
          example: true
        createTime:
          type: string
          format: date-time
          description: Timestamp when the JWT key was created
          example: "2024-01-15T10:30:00Z"
        updateTime:
          type: string
          format: date-time
          description: Timestamp when the JWT key was last updated
          example: "2024-01-15T10:30:00Z"
    PatchJWTKeyRequest:
      type: object
      required:
      - updateMask
      - jwtKey
      properties:
        updateMask:
          type: array
          description: List of field paths to update (currently supports 'active' and 'name')
          items:
            type: string
            enum: ["active", "label"]
          minItems: 1
          example: ["active", "label"]
        jwtKey:
          type: object
          description: Object containing the fields to update with their new values
          additionalProperties: true
          properties:
            active:
              type: boolean
              description: New active status for the JWT key
              example: false
            label:
              type: string
              description: New label for the JWT key
              example: "updated-key-name"
          example:
            active: false
            name: "updated-key-name"

    # Metadata schemas matching Go structs in shared/common/metadata.go
    UpsertMetadataRequest:
      type: object
      description: Request payload for upserting metadata (fields only)
      properties:
        groupRef:
          type: string
          description: The ID that your app uses to identify the group of users for this request.
          example: group-123
        fields:
          type: object
          description: Maps object names to field definitions
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/FieldDefinition'
      required:
      - groupRef
      - fields

    UpsertMetadataResponse:
      type: object
      description: Response containing results for all created/updated fields
      properties:
        success:
          type: boolean
          description: Indicates if the upsert operation was successful
        fields:
          type: object
          description: Maps object name -> field name -> upsert result
          additionalProperties:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/FieldUpsertResult'
      required:
      - success
      - fields

    FieldDefinition:
      type: object
      description: Field definition for creating or updating custom fields
      properties:
        fieldName:
          type: string
          description: The identifier of the field
          example: "My_Custom_Field"
        displayName:
          type: string
          description: The human-readable name of the field
          example: "My Custom Field"
        description:
          type: string
          description: Optional description of the field
        valueType:
          type: string
          description: The data type of the field. Valid values are string, boolean, date, datetime, singleSelect, multiSelect, int, float, reference
          example: "string"
        required:
          type: boolean
          description: Indicates if the field is required
        unique:
          type: boolean
          description: Indicates if the field must be unique across all records
        indexed:
          type: boolean
          description: Indicates if the field should be indexed for faster search
        stringOptions:
          $ref: '#/components/schemas/StringFieldOptions'
        numericOptions:
          $ref: '#/components/schemas/NumericFieldOptions'
        association:
          $ref: '#/components/schemas/AssociationDefinition'
      required:
      - fieldName
      - displayName
      - valueType

    StringFieldOptions:
      type: object
      description: Additional options for string fields
      properties:
        length:
          type: integer
          description: Maximum length of the string field
        pattern:
          type: string
          description: Regex pattern that the string field value must match
        values:
          type: array
          description: List of allowed values for enum fields
          items:
            type: string
        valuesRestricted:
          type: boolean
          description: Indicates if the field value must be limited to what's in Values
        defaultValue:
          type: string
          description: Default value for the field

    NumericFieldOptions:
      type: object
      description: Additional options for numeric fields
      properties:
        precision:
          type: integer
          description: Total number of digits (for decimal types)
        scale:
          type: integer
          description: Number of digits to the right of the decimal point (for decimal types)
        min:
          type: number
          description: Minimum value for numeric fields
        max:
          type: number
          description: Maximum value for numeric fields
        defaultValue:
          type: number
          description: Default value for the field

    AssociationDefinition:
      type: object
      description: Relationship information for a field to another object
      properties:
        associationType:
          type: string
          description: High-level association variety (e.g., 'foreignKey', 'lookup', 'ref')
          example: "foreignKey"
        targetObject:
          type: string
          description: Name of the referenced/parent object
          example: "Account"
        targetField:
          type: string
          description: Name of the referenced field on the target object
        cardinality:
          type: string
          description: Association cardinality from the referencing field's perspective
          example: "many-to-one"
        onDelete:
          type: string
          description: Behavior upon foreign object deletion
          example: "setNull"
        required:
          type: boolean
          description: If true, a referenced record must exist
        reverseLookupFieldName:
          type: string
          description: Optional inverse relationship/property name exposed on the target object
        labels:
          $ref: '#/components/schemas/AssociationLabels'
      required:
      - associationType
      - targetObject

    AssociationLabels:
      type: object
      description: UI labels for an association
      properties:
        singular:
          type: string
          description: Singular display label
        plural:
          type: string
          description: Plural display label

    FieldUpsertResult:
      type: object
      description: Result of an upsert operation for a single field
      properties:
        fieldName:
          type: string
          description: Name of the field
        action:
          type: string
          description: Action taken (create, update, none)
        metadata:
          type: object
          description: Provider-specific metadata about the field
          additionalProperties: true
        warnings:
          type: array
          description: Warnings that occurred during the upsert operation
          items:
            type: string
      required:
      - fieldName
      - action

    ClaimedDomainResponse:
      type: object
      required:
      - id
      - parentType
      - parentId
      - domain
      properties:
        id:
          type: string
          description: Unique identifier for the claimed domain
          example: 00000000-0000-0000-0000-000000000001
        parentType:
          type: string
          description: Type of the parent entity that claimed the domain
          example: org
        parentId:
          type: string
          description: ID of the parent entity that claimed the domain
          example: 00000000-0000-0000-0000-000000000001
        domain:
          type: string
          description: The normalized domain name
          example: xyz.com
    Topic:
      title: Topic
      required:
      - id
      - name
      - projectId
      - createTime
      type: object
      properties:
        id:
          type: string
          description: The topic ID.
        name:
          type: string
          description: The name of the topic. Must contain only letters, numbers, and dashes.
          example: "system-alerts"
          maxLength: 64
        projectId:
          type: string
          description: The Ampersand project ID.
        createTime:
          type: string
          format: date-time
          description: The time when the topic was created.
        updateTime:
          type: string
          format: date-time
          description: The time when the topic was last updated.
    NotificationEventTopicRoute:
      title: Notification Event Topic Route
      required:
      - id
      - eventType
      - topicId
      - projectId
      - createTime
      type: object
      properties:
        id:
          type: string
          description: The event-topic route ID.
        eventType:
          $ref: "#/components/schemas/NotificationEventType"
        topicId:
          type: string
          description: The ID of the topic to route events to.
        projectId:
          type: string
          description: The Ampersand project ID.
        createTime:
          type: string
          format: date-time
          description: The time when the event-topic route was created.
        updateTime:
          type: string
          format: date-time
          description: The time when the event-topic route was last updated.

    NotificationEventType:
      type: string
      description: The type of notification event.
      enum:
      - "connection.created"
      - "connection.error"
      - "connection.refreshed"
      - "connection.deleted"
      - "installation.created"
      - "installation.updated"
      - "installation.deleted"
      - "read.schedule.paused"
      - "read.backfill.done"
      - "read.triggered.done"
      - "read.triggered.error"
      - "write.async.done"
      - "destination.webhook.disabled"
    TopicDestinationRoute:
      title: Topic Destination Route
      required:
      - id
      - topicId
      - destinationId
      - projectId
      - createTime
      type: object
      properties:
        id:
          type: string
          description: The topic destination route ID.
        topicId:
          type: string
          description: The ID of the topic.
        destinationId:
          type: string
          description: The ID of the destination.
        projectId:
          type: string
          description: The Ampersand project ID.
        createTime:
          type: string
          format: date-time
          description: The time when the topic destination route was created.

  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: X-Api-Key
      in: header
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
- APIKeyHeader: []
- Bearer: []