Ampersand API

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.googl

# --- truncated at 32 KB (224 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ampersand/refs/heads/main/openapi/ampersand-api-openapi-original.yml