Ampersand Integration API
The Integration API from Ampersand — 4 operation(s) for integration.
OpenAPI Specification
openapi: 3.0.1
info:
title: Ampersand public API Key Integration API
version: 1.0.0
servers:
- url: https://api.withampersand.com/v1
security:
- APIKeyHeader: []
- Bearer: []
tags:
- name: Integration
paths:
/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
components:
schemas:
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
securitySchemes:
APIKeyHeader:
type: apiKey
name: X-Api-Key
in: header
Bearer:
type: http
scheme: bearer
bearerFormat: JWT