> ## Documentation Index > Fetch the complete documentation index at: https://docs.withampersand.com/llms.txt > Use this file to discover all available pages before exploring further. # List providers > 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. ## OpenAPI ````yaml platform get /providers openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /providers: get: tags: - Provider summary: 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 responses: '200': description: | All available providers and their capabilities. content: application/json: schema: title: Catalog Type type: object additionalProperties: title: Provider Info type: object required: - name - baseURL - authType - support - defaultModule properties: name: type: string authType: title: Auth Type description: The type of authentication required by the provider. type: string enum: - oauth2 - apiKey - basic - jwt - custom - none x-oapi-codegen-extra-tags: validate: required baseURL: description: The base URL for making API requests. type: string x-oapi-codegen-extra-tags: validate: required defaultModule: type: string oauth2Opts: title: OAuth2 Options type: object description: >- Configuration for OAuth2.0. Must be provided if authType is oauth2. required: - grantType - tokenURL - explicitScopesRequired - explicitWorkspaceRequired - tokenMetadataFields properties: grantType: type: string enum: - authorizationCode - authorizationCodePKCE - clientCredentials - password authURL: type: string example: >- https://login.salesforce.com/services/oauth2/authorize description: The authorization URL. x-go-type-skip-optional-pointer: true tokenURL: type: string example: https://login.salesforce.com/services/oauth2/token description: The token URL. x-oapi-codegen-extra-tags: validate: required explicitScopesRequired: type: boolean description: >- Whether scopes are required to be known ahead of the OAuth flow. example: true explicitWorkspaceRequired: type: boolean description: >- Whether the workspace is required to be known ahead of the OAuth flow. example: true audience: type: array items: type: string example: - https://api.mparticle.com description: >- A list of URLs that represent the audience for the token, which is needed for some client credential grant flows. x-go-type-skip-optional-pointer: true scopeMappings: type: object description: >- Maps input scopes to their full OAuth scope values with template variable support. Scopes not in this map are passed through unchanged. Needed for some providers. additionalProperties: type: string x-go-type-skip-optional-pointer: true example: default: https://{{.workspace}}.api.com/default tokenMetadataFields: title: Token Metadata Fields type: object description: >- Fields to be used to extract token metadata from the token response. properties: workspaceRefField: type: string example: account-id x-go-type-skip-optional-pointer: true consumerRefField: type: string example: user-id x-go-type-skip-optional-pointer: true scopesField: type: string example: scopes x-go-type-skip-optional-pointer: true otherFields: type: array title: Token Metadata Fields - Other fields description: >- Additional fields to extract and transform from the token response items: type: object required: - name - displayName - path properties: name: type: string description: The internal name of the field x-go-type-skip-optional-pointer: true displayName: type: string description: The human-readable name of the field x-go-type-skip-optional-pointer: true path: type: string description: >- The path to the field in the token response (accepts dot notation for nested fields) example: owner.siteId x-go-type-skip-optional-pointer: true capture: type: string description: >- A regex expression to capture the value that we need from the path. There must be only one capture group named 'result' in the expression. If not provided, will cause an error. example: https:\/\/(?[^.]+)\.docusign\.net x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about where to retrieve Client ID and Client Secret, etc. example: https://docs.example.com/client-credentials x-go-type-skip-optional-pointer: true authURLParams: type: object additionalProperties: type: string x-go-type-skip-optional-pointer: true example: access_type: offline duration: permanent accessTokenOpts: title: Oauth2 Access Token Options type: object description: > Configuration that defines how an OAuth 2.0 access token is attached to outbound API requests. When provided, this configuration overrides the default access-token handling behavior for the connector. required: - attachmentType properties: attachmentType: type: string description: >- How the access token should be attached to requests. enum: - accessTokenHeaderAttachment x-oapi-codegen-extra-tags: validate: required header: title: Access Token Header Options type: object description: >- Configuration for access token in header. Must be provided if type is in-header. required: - name properties: name: type: string example: X-Access-Token description: >- The name of the header to be used for the access token. x-go-type-skip-optional-pointer: true valuePrefix: type: string example: 'Bearer ' description: >- The prefix to be added to the access token value when it is sent in the header. x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how access token is used. example: >- https://docs.example.com/oauth2-access-token-usage x-go-type-skip-optional-pointer: true apiKeyOpts: title: API Key Options type: object description: >- Configuration for API key. Must be provided if authType is apiKey. required: - attachmentType properties: attachmentType: type: string description: How the API key should be attached to requests. enum: - query - header x-oapi-codegen-extra-tags: validate: required query: title: API Key Query Options type: object description: >- Configuration for API key in query parameter. Must be provided if type is in-query. required: - name properties: name: type: string example: api_key description: >- The name of the query parameter to be used for the API key. x-go-type-skip-optional-pointer: true header: title: API Key Header Options type: object description: >- Configuration for API key in header. Must be provided if type is in-header. required: - name properties: name: type: string example: X-Api-Key description: >- The name of the header to be used for the API key. x-go-type-skip-optional-pointer: true valuePrefix: type: string example: 'Bearer ' description: >- The prefix to be added to the API key value when it is sent in the header. x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how to get or use an API key. example: https://docs.example.com/api-key x-go-type-skip-optional-pointer: true basicOpts: title: Basic Auth Options type: object description: Configuration for Basic Auth. Optional. properties: apiKeyAsBasic: type: boolean example: true description: >- If true, the provider uses an API key which then gets encoded as a basic auth user:pass string. x-go-type-skip-optional-pointer: true apiKeyAsBasicOpts: title: API Key as Basic Options type: object description: >- when this object is present, it means that this provider uses Basic Auth to actually collect an API key properties: fieldUsed: type: string enum: - username - password example: username description: >- whether the API key should be used as the username or password. x-go-type-skip-optional-pointer: true x-enum-varnames: - UsernameField - PasswordField keyFormat: type: string example: api:%s description: >- How to transform the API key in to a basic auth user:pass string. The %s is replaced with the API key value. x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how to get or use an API key. example: https://docs.example.com/api-key x-go-type-skip-optional-pointer: true customOpts: title: Custom Auth Options type: object description: Configuration for custom auth. Optional. properties: headers: type: array items: title: Custom Auth Header type: object description: >- A custom header to be used for authentication. Automatically added by the backend. required: - name - valueTemplate properties: name: type: string example: X-Custom-Auth description: The name of the header. valueTemplate: type: string example: Bearer {{ .token }} description: >- The value of the header, represented as a Golang text/template expression. Only the backend will interpret this. x-oapi-codegen-extra-tags: skipSubstitutions: 'true' description: >- A list of custom headers to be used for authentication. The backend will add these headers. x-go-type-skip-optional-pointer: true queryParams: type: array items: title: Custom Auth Query Parameter type: object description: >- A custom query parameter to be used for authentication. Automatically added by the backend. required: - name - valueTemplate properties: name: type: string example: custom_auth description: The name of the query parameter. valueTemplate: type: string example: '{{ .token }}' description: >- The value of the query parameter, represented as a Golang text/template expression. Only the backend will interpret this. x-oapi-codegen-extra-tags: skipSubstitutions: 'true' description: >- A list of custom query parameters to be used for authentication. The backend will add these query parameters. x-go-type-skip-optional-pointer: true inputs: type: array items: title: Custom Auth Input type: object description: >- A custom input field for authentication. This is used by the frontend to dynamically render input fields for custom auth. The backend will not interpret this. It will however receive the value of this field before making a request (in the connection secrets). required: - name - displayName properties: name: type: string example: custom_auth_input description: >- The internal identifier for the custom auth input field. displayName: type: string example: Custom Auth Input description: >- The human-readable name for the custom auth input field. prompt: type: string example: >- See Authorization section of provider docs to obtain this value description: >- Some helpful text or context to be displayed to the user when asking for this input. x-go-type-skip-optional-pointer: true docsURL: type: string example: https://docs.example.com/custom-auth-input description: >- URL with details about this authentication mechanism and how to use it. Might be specific to this field, or a general URL for the provider. Optional. x-go-type-skip-optional-pointer: true description: >- A list of custom input fields for authentication. The frontend will render these input fields and the backend will receive the values of these fields before making a request. x-go-type-skip-optional-pointer: true support: title: Support type: object description: The supported features for the provider. x-oapi-codegen-extra-tags: validate: required required: - bulkWrite - proxy - read - subscribe - write - delete - search properties: bulkWrite: title: Bulk Write Support type: object x-oapi-codegen-extra-tags: validate: required required: - insert - update - upsert - delete properties: insert: type: boolean update: type: boolean upsert: type: boolean delete: type: boolean proxy: type: boolean read: type: boolean subscribe: type: boolean write: type: boolean delete: type: boolean subscribeSupport: title: Subscribe Support type: object properties: create: type: boolean update: type: boolean delete: type: boolean passThrough: type: boolean batchWrite: required: - delete - create - update - upsert properties: delete: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer create: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer update: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer upsert: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer search: title: Search Support type: object required: - operators properties: operators: title: Supported Operators for Search Action type: object required: - equals properties: equals: type: boolean authHealthCheck: title: Auth Health Check type: object description: >- A URL to check the health of a provider's credentials. It's used to see if the credentials are valid and if the provider is reachable. required: - url properties: url: type: string description: >- a no-op URL to check the health of the credentials. The URL MUST not mutate any state. If the provider doesn't have such an endpoint, then don't provide credentialsHealthCheck. example: https://api.example.com/health-check method: type: string description: >- The HTTP method to use for the health check. If not set, defaults to GET. example: GET x-go-type-skip-optional-pointer: true successStatusCodes: type: array items: type: integer description: >- The HTTP status codes that indicate a successful health check. If not set, defaults to 200 and 204. example: - 200 - 204 x-go-type-skip-optional-pointer: true displayName: type: string example: Zendesk Chat description: >- The display name of the provider, if omitted, defaults to provider name. x-go-type-skip-optional-pointer: true postAuthInfoNeeded: type: boolean example: true description: >- If true, we require additional information after auth to start making requests. x-go-type-skip-optional-pointer: true media: title: Media properties: regular: title: Media Type Regular type: object description: Media for light/regular mode. properties: iconURL: type: string example: https://example.com/icon.png description: URL to the icon for the provider. x-go-type-skip-optional-pointer: true logoURL: type: string example: https://example.com/logo.png description: URL to the logo for the provider. x-go-type-skip-optional-pointer: true darkMode: title: Media Type Dark Mode type: object description: Media to be used in dark mode. properties: iconURL: type: string example: https://example.com/icon.png description: >- URL to the icon for the provider that is to be used in dark mode. x-go-type-skip-optional-pointer: true logoURL: type: string example: https://example.com/logo.png description: >- URL to the logo for the provider that is to be used in dark mode. x-go-type-skip-optional-pointer: true labels: title: Labels type: object additionalProperties: type: string subscribeRequirements: title: Subscribe Requirements type: object description: >- Declares which auxiliary steps a provider requires to support subscriptions, beyond the per-object subscribe call itself. properties: registration: type: boolean description: >- Whether the provider requires a one-time registration step that is shared across all subscribed objects. The subscribe method is object-scoped, so if a separate API call is needed beyond per-object configuration (e.g., registering a single webhook/endpoint that all object subscriptions hang off of), registration is required. maintenance: type: boolean description: >- Whether the subscription requires periodic maintenance. Some providers expire subscriptions/watches after a fixed TTL, so the subscription must be renewed on a schedule to remain active. postProcess: type: boolean description: >- Whether subscribing requires a third-party setup step that the connector instance itself cannot perform. Examples: Salesforce requires AWS EventBridge configuration; Gmail requires a Google Pub/Sub topic to be configured. Any configuration that must happen outside the connector falls into post-process. subscribeByAPI: type: boolean description: >- Whether the provider supports programmatic subscription via API. If false, provider may still support webhooks via manual configuration in UI. modules: title: Modules that this provider supports type: object description: The registry of provider modules. additionalProperties: title: Module Info type: object required: - displayName - baseURL - support properties: displayName: type: string baseURL: type: string support: title: Support type: object description: The supported features for the provider. x-oapi-codegen-extra-tags: validate: required required: - bulkWrite - proxy - read - subscribe - write - delete - search properties: bulkWrite: title: Bulk Write Support type: object x-oapi-codegen-extra-tags: validate: required required: - insert - update - upsert - delete properties: insert: type: boolean update: type: boolean upsert: type: boolean delete: type: boolean proxy: type: boolean read: type: boolean subscribe: type: boolean write: type: boolean delete: type: boolean subscribeSupport: title: Subscribe Support type: object properties: create: type: boolean update: type: boolean delete: type: boolean passThrough: type: boolean batchWrite: required: - delete - create - update - upsert properties: delete: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer create: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer update: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer upsert: required: - supported properties: supported: description: >- Whether this type of batch write operation is supported type: boolean defaultRecordLimit: description: >- The default number of records supported in a batch type: integer objectRecordLimits: description: >- Defines object-level overrides for batch record limits. Keys represent object names, and values specify the maximum number of records per batch for those objects. type: object additionalProperties: type: integer search: title: Search Support type: object required: - operators properties: operators: title: Supported Operators for Search Action type: object required: - equals properties: equals: type: boolean subscribeRequirements: title: Subscribe Requirements type: object description: >- Declares which auxiliary steps a provider requires to support subscriptions, beyond the per-object subscribe call itself. properties: registration: type: boolean description: >- Whether the provider requires a one-time registration step that is shared across all subscribed objects. The subscribe method is object-scoped, so if a separate API call is needed beyond per-object configuration (e.g., registering a single webhook/endpoint that all object subscriptions hang off of), registration is required. maintenance: type: boolean description: >- Whether the subscription requires periodic maintenance. Some providers expire subscriptions/watches after a fixed TTL, so the subscription must be renewed on a schedule to remain active. postProcess: type: boolean description: >- Whether subscribing requires a third-party setup step that the connector instance itself cannot perform. Examples: Salesforce requires AWS EventBridge configuration; Gmail requires a Google Pub/Sub topic to be configured. Any configuration that must happen outside the connector falls into post-process. subscribeByAPI: type: boolean description: >- Whether the provider supports programmatic subscription via API. If false, provider may still support webhooks via manual configuration in UI. metadata: title: Provider Metadata type: object description: >- Provider metadata that needs to be given by the user or fetched by the connector post authentication for the connector to work. properties: input: type: array description: Metadata provided as manual input items: title: Metadata Item (as input) type: object required: - name properties: name: type: string description: The internal identifier for the metadata field x-go-type-skip-optional-pointer: true displayName: type: string description: The human-readable name for the field x-go-type-skip-optional-pointer: true prompt: type: string description: >- Human-readable description that can contain instructions on how to collect metadata x-go-type-skip-optional-pointer: true defaultValue: type: string description: Default value for this metadata item x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how to locate this value example: https://example.com/how-to-find-subdomain x-go-type-skip-optional-pointer: true moduleDependencies: description: >- Which modules require this metadata item (see ModuleDependencies for naming clarification). title: Module Dependencies type: object additionalProperties: title: Module Dependency type: object description: Dependency for a single module. properties: {} x-go-type-skip-optional-pointer: true postAuthentication: type: array description: >- Metadata fetched by the connector post authentication items: title: Metadata Item (fetched post authentication) type: object required: - name properties: name: type: string description: The internal identifier for the metadata field x-go-type-skip-optional-pointer: true moduleDependencies: description: >- Which modules require this metadata item (see ModuleDependencies for naming clarification). title: Module Dependencies type: object additionalProperties: title: Module Dependency type: object description: Dependency for a single module. properties: {} x-go-type-skip-optional-pointer: true providerAppMetadata: title: Provider App Metadata type: object description: >- Describes the provider-app-level fields that the Ampersand dashboard should collect from the builder when creating a ProviderApp for this provider. These descriptors tell the dashboard which form fields to render; the submitted values are stored in ProviderApp.metadata. properties: authQueryParams: type: array description: >- Descriptors for fields stored in ProviderApp.metadata.authQueryParams (e.g., optional_scope for HubSpot). items: title: Metadata Item (as input) type: object required: - name properties: name: type: string description: The internal identifier for the metadata field x-go-type-skip-optional-pointer: true displayName: type: string description: The human-readable name for the field x-go-type-skip-optional-pointer: true prompt: type: string description: >- Human-readable description that can contain instructions on how to collect metadata x-go-type-skip-optional-pointer: true defaultValue: type: string description: Default value for this metadata item x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how to locate this value example: https://example.com/how-to-find-subdomain x-go-type-skip-optional-pointer: true moduleDependencies: description: >- Which modules require this metadata item (see ModuleDependencies for naming clarification). title: Module Dependencies type: object additionalProperties: title: Module Dependency type: object description: Dependency for a single module. properties: {} x-go-type-skip-optional-pointer: true providerParams: type: array description: >- Descriptors for fields stored in ProviderApp.metadata.providerParams (e.g., packageInstallURL for Salesforce, gcpProjectId for Gmail). items: title: Metadata Item (as input) type: object required: - name properties: name: type: string description: The internal identifier for the metadata field x-go-type-skip-optional-pointer: true displayName: type: string description: The human-readable name for the field x-go-type-skip-optional-pointer: true prompt: type: string description: >- Human-readable description that can contain instructions on how to collect metadata x-go-type-skip-optional-pointer: true defaultValue: type: string description: Default value for this metadata item x-go-type-skip-optional-pointer: true docsURL: type: string description: >- URL with more information about how to locate this value example: https://example.com/how-to-find-subdomain x-go-type-skip-optional-pointer: true moduleDependencies: description: >- Which modules require this metadata item (see ModuleDependencies for naming clarification). title: Module Dependencies type: object additionalProperties: title: Module Dependency type: object description: Dependency for a single module. properties: {} x-go-type-skip-optional-pointer: true 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: title: API Problem type: object allOf: - title: Problem description: > A Problem Details object (RFC 9457). Additional properties specific to the problem type may be present. type: object properties: type: type: string format: uri description: An absolute URI that identifies the problem type default: about:blank href: type: string format: uri description: >- An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML). title: type: string description: >- A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized). example: Service Unavailable status: type: integer format: int32 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. minimum: 400 maximum: 600 exclusiveMaximum: true example: 503 detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem instance: type: string format: uri description: >- An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. example: type: urn:problem-type:exampleOrganization:exampleProblem href: >- https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types title: Description of the type of problem that occurred status: 400 detail: Description of specific occurrence of the problem instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000 properties: subsystem: type: string description: The subsystem that generated the problem example: api time: type: string format: date-time description: The time the problem occurred, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' requestId: type: string description: A unique identifier for the request, useful for debugging example: 89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715 causes: type: array items: type: string description: >- A brief description of something which caused the problem example: database connection failed example: - database connection failed - database query failed - unable to fetch user description: > A list of problems that caused this problem. This can be used to represent multiple root causes. There is no guaranteed ordering of the causes. remedy: type: string description: A brief description of how to resolve the problem example: Shorten your input to be under 100 characters supportEmail: type: string format: email description: An email address to contact for support example: support@withampersand.com supportPhone: type: string description: A phone number to contact for support example: +1-555-555-5555 supportUrl: type: string format: uri description: A URL to contact for support example: https://withampersand.com/support retryable: type: boolean description: Whether the request can be retried example: false retryAfter: type: string format: date-time description: >- A timestamp after which the request can be retried, formatted as RFC-3339 example: '2024-04-22T18:55:28.456076Z' context: type: object description: Additional context for the problem additionalProperties: true example: name: Rick Sanchez security: [] components: securitySchemes: APIKeyHeader: type: apiKey name: X-Api-Key in: header Bearer: type: http scheme: bearer bearerFormat: JWT ````