{ "openapi": "3.0.1", "info": { "title": "Ampersand public read API", "version": "1.0.0" }, "servers": [ { "url": "https://read.withampersand.com/v1" } ], "paths": { "/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}": { "post": { "summary": "Trigger a read", "description": "Triggers reading data from a SaaS instance. See [Trigger a read](https://docs.withampersand.com/define-integrations/read-actions#trigger-a-read) for details. If you want scheduled reads or automatic backfills instead, you [can define them in the manifest](https://docs.withampersand.com/read-actions#defining-reads).", "operationId": "triggerRead", "tags": [ "Read" ], "parameters": [ { "name": "projectIdOrName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "objectName", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Read Request", "required": true, "content": { "application/json": { "schema": { "title": "Read Request", "required": [ "groupRef", "mode" ], "type": "object", "properties": { "groupRef": { "type": "string", "description": "The ID of the user group whose SaaS instance you'd like to read data from. This is the ID that was provided during installation creation." }, "mode": { "type": "string", "description": "The mode of read operation. Currently only asynchronus operation is supported.", "enum": [ "async" ], "example": "async" }, "sinceTimestamp": { "type": "string", "description": "The UTC timestamp from which to read data. If omitted, we will read all data.", "example": "2024-07-01T18:22:30.323771761Z" }, "untilTimestamp": { "type": "string", "description": "The UTC timestamp until which to read data.", "example": "2024-07-05T18:22:30.323771761Z" } } } } } }, "responses": { "201": { "description": "The success response", "content": { "application/json": { "schema": { "title": "Read Result Async", "type": "object", "required": [ "operationId" ], "properties": { "operationId": { "type": "string", "description": "The operation ID", "example": "60deaf48-3856-4a2b-bfd4-3de85125eca8" } } } } } }, "400": { "description": "The failure response for bad request.", "content": { "application/json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } } } } }, "/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:pause": { "post": { "summary": "Pause reads for an installation", "description": "Pauses all scheduled reads for an installation. If reads are already paused, this will be a no-op. Accepts specific objects to pause reads for in the request body.", "operationId": "pauseReads", "tags": [ "Read" ], "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" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "objects": { "type": "array", "items": { "type": "string", "example": [ "account", "contact" ], "description": "The names of the objects (mapped or unmapped) to pause reads for. If not provided, all objects will be paused." } }, "note": { "type": "string", "description": "A note to accompany the pause." } } } } } }, "responses": { "204": { "description": "Reads paused successfully" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "title": "Input Validation Problem", "type": "object", "allOf": [ { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } ], "properties": { "issues": { "type": "array", "items": { "title": "Input Validation Issue", "type": "object", "description": "An issue detected during input validation.\n", "allOf": [ { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } ], "properties": { "in": { "type": "string", "description": "The location of the invalid input", "enum": [ "body", "header", "path", "query" ] }, "name": { "type": "string", "description": "The name of the invalid input" }, "value": { "description": "The value of the erroneous input" } } } } }, "example": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "The input message is incorrect", "instance": "123456-1234-1235-4567489798", "issues": [ { "type": "about:blank", "detail": "exampleNumericProperty should be numeric", "in": "path", "name": "exampleNumericProperty", "value": "abc" }, { "type": "about:blank", "title": "Input isn't valid with respect to schema", "detail": "examplePropertyWithPattern a2345678901 doesn't match pattern '^\\d{11}$'", "in": "body", "name": "items[0].examplePropertyWithPattern", "value": "a2345678901" } ] } } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } } } } }, "/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}:unpause": { "post": { "summary": "Unpause reads for an installation", "description": "Unpauses all scheduled reads for an installation. If no reads were paused, this will be a no-op. Accepts specific objects to unpause reads for in the request body.", "operationId": "unpauseReads", "tags": [ "Read" ], "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" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "objects": { "type": "array", "items": { "type": "string", "description": "The names of the objects to unpause reads for.", "example": [ "account", "contact" ] } }, "note": { "type": "string", "description": "A note to accompany the unpause." } } } } } }, "responses": { "204": { "description": "Reads unpaused successfully" }, "400": { "description": "Bad Request", "content": { "application/problem+json": { "schema": { "title": "Input Validation Problem", "type": "object", "allOf": [ { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } ], "properties": { "issues": { "type": "array", "items": { "title": "Input Validation Issue", "type": "object", "description": "An issue detected during input validation.\n", "allOf": [ { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } ], "properties": { "in": { "type": "string", "description": "The location of the invalid input", "enum": [ "body", "header", "path", "query" ] }, "name": { "type": "string", "description": "The name of the invalid input" }, "value": { "description": "The value of the erroneous input" } } } } }, "example": { "type": "about:blank", "title": "Bad Request", "status": 400, "detail": "The input message is incorrect", "instance": "123456-1234-1235-4567489798", "issues": [ { "type": "about:blank", "detail": "exampleNumericProperty should be numeric", "in": "path", "name": "exampleNumericProperty", "value": "abc" }, { "type": "about:blank", "title": "Input isn't valid with respect to schema", "detail": "examplePropertyWithPattern a2345678901 doesn't match pattern '^\\d{11}$'", "in": "body", "name": "items[0].examplePropertyWithPattern", "value": "a2345678901" } ] } } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } } } } }, "/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}:deliverResults": { "post": { "summary": "Deliver results", "description": "This endpoint is deprecated. If you wish you trigger a read (including backfills), use the [trigger a read](https://docs.withampersand.com/reference/read/trigger-a-read) endpoint instead.", "operationId": "deliverResults", "tags": [ "Read" ], "parameters": [ { "name": "projectIdOrName", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "integrationId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "objectName", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "ResultDeliveryRequestBody", "required": true, "content": { "application/json": { "schema": { "title": "Result Delivery Request", "required": [ "groupRef", "pages" ], "type": "object", "properties": { "groupRef": { "type": "string", "description": "The ID of the user group whose SaaS instance you'd like to receive results from. This is the ID that was provided during installation creation." }, "pages": { "type": "integer", "description": "The number of pages you are ready to receive from the group's SaaS instance.", "minimum": 0 } } } } } }, "responses": { "204": { "description": "The success response" }, "400": { "description": "The failure response for bad request.", "content": { "application/json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } }, "default": { "description": "Error", "content": { "application/problem+json": { "schema": { "title": "API Problem", "type": "object", "allOf": [ { "title": "Problem", "description": "A Problem Details object (RFC 9457).\n\nAdditional properties specific to the problem type may be present.\n", "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\nroot causes. There is no guaranteed ordering of the causes.\n" }, "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" } } } } } } } } } } }, "components": { "schemas": { "ReadRequest": { "title": "Read Request", "required": [ "groupRef", "mode" ], "type": "object", "properties": { "groupRef": { "type": "string", "description": "The ID of the user group whose SaaS instance you'd like to read data from. This is the ID that was provided during installation creation." }, "mode": { "type": "string", "description": "The mode of read operation. Currently only asynchronus operation is supported.", "enum": [ "async" ], "example": "async" }, "sinceTimestamp": { "type": "string", "description": "The UTC timestamp from which to read data. If omitted, we will read all data.", "example": "2024-07-01T18:22:30.323771761Z" }, "untilTimestamp": { "type": "string", "description": "The UTC timestamp until which to read data.", "example": "2024-07-05T18:22:30.323771761Z" } } }, "ReadResultAsync": { "title": "Read Result Async", "type": "object", "required": [ "operationId" ], "properties": { "operationId": { "type": "string", "description": "The operation ID", "example": "60deaf48-3856-4a2b-bfd4-3de85125eca8" } } }, "ResultDeliveryRequestBody": { "title": "Result Delivery Request", "required": [ "groupRef", "pages" ], "type": "object", "properties": { "groupRef": { "type": "string", "description": "The ID of the user group whose SaaS instance you'd like to receive results from. This is the ID that was provided during installation creation." }, "pages": { "type": "integer", "description": "The number of pages you are ready to receive from the group's SaaS instance.", "minimum": 0 } } } }, "securitySchemes": { "APIKeyHeader": { "type": "apiKey", "name": "X-Api-Key", "in": "header" }, "APIKeyQueryParam": { "type": "apiKey", "name": "apiKey", "in": "query" }, "Bearer": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "security": [ { "APIKeyHeader": [] } ] }