# Async Helpers ## List async helpers > Returns an array of all async helper resources in the account.\ > \ > AI guidance:\ > \- The response includes the full object shape for each async helper,\ > including the nested \`http.submit\`, \`http.status\`, and \`http.result\`\ > configurations.\ > \- Use this to discover which async helpers exist before referencing\ > them in export configurations. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AsyncHelper":{"type":"object","description":"An async helper defines how integrator.io interacts with an external\nsystem's asynchronous job API. It coordinates three phases: submitting a\nrequest, polling for status, and retrieving the result.\n\nAI guidance:\n- The `http.submit.sameAsStatus` flag controls whether the submit step\n reuses the status export's configuration. When `true`, no separate\n submit export is needed.\n- The `http.status._exportId` references an export resource that defines\n the HTTP call used to poll the remote job's status.\n- The `http.status.inProgressValues` and `http.status.doneValues` arrays\n determine how integrator.io interprets the polled status response.\n- `http.result._exportId` is optional -- when omitted, the final status\n poll response is used as the result.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the async helper."},"name":{"type":"string","description":"Human-readable name for the async helper."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"When the async helper was last modified."},"http":{"type":"object","description":"HTTP configuration for the three phases of the async helper:\nsubmit, status, and result.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request to the\nexternal system.\n","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the same export\nconfiguration as the status step (i.e. the same endpoint\nis used to both initiate and poll the job). When `false`,\nyou must configure `resourcePath` and optionally\n`transform` to define a separate submit call.\n"},"resourcePath":{"type":"string","description":"JSONPath or dot-notation path to extract the async job\nidentifier from the submit response. Only used when\n`sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit\nresponse before extracting the resource path.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the external system's async job status.\nThe referenced export defines the HTTP call; the path and value\narrays tell integrator.io how to interpret the response.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nthe status polling call.\n"},"statusPath":{"type":"string","description":"JSONPath or dot-notation path to extract the status value\nfrom the poll response.\n"},"inProgressValues":{"type":"array","description":"Status values that indicate the remote job is still running.\nThe poller continues while the extracted status matches any\nof these values.\n","items":{"type":"string"}},"doneValues":{"type":"array","description":"Status values that indicate the remote job completed\nsuccessfully with data available for retrieval.\n","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Status values that indicate the remote job completed but\nproduced no data (e.g. an empty result set). Optional.\n","items":{"type":"string"}},"errorValues":{"type":"array","description":"Status values that indicate the remote job failed. When\nmatched, integrator.io treats the poll as an error. Optional.\n","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the final result once the status\nindicates completion. If `_exportId` is omitted, the last\nstatus poll response is used as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nretrieving the async job's result. Optional -- if omitted,\nthe result is taken from the final status poll response.\n"}}}},"required":["submit","status"]}},"required":["_id","name","http"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/asynchelpers":{"get":{"operationId":"listAsyncHelpers","tags":["Async Helpers"],"summary":"List async helpers","description":"Returns an array of all async helper resources in the account.\n\nAI guidance:\n- The response includes the full object shape for each async helper,\n including the nested `http.submit`, `http.status`, and `http.result`\n configurations.\n- Use this to discover which async helpers exist before referencing\n them in export configurations.","responses":{"200":{"description":"Array of async helper objects.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AsyncHelper"}}}}},"204":{"description":"No async helpers exist in the account."},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` ## Create an async helper > Creates a new async helper resource.\ > \ > AI guidance:\ > \- Required fields: \`name\`, \`http.submit.sameAsStatus\`,\ > \`http.status.\_exportId\`, \`http.status.statusPath\`,\ > \`http.status.inProgressValues\`, \`http.status.doneValues\`.\ > \- The referenced \`http.status.\_exportId\` must be an existing export\ > resource; the server validates the reference.\ > \- If \`http.submit.sameAsStatus\` is \`false\`, you should also set\ > \`http.submit.resourcePath\` to extract the async job identifier. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AsyncHelperRequest":{"type":"object","description":"Request body for creating or replacing an async helper resource. All\nrequired fields must be present for both POST (create) and PUT (replace)\noperations.\n\nAI guidance:\n- `http.submit.sameAsStatus` is always required. Set to `true` when the\n same endpoint handles both submission and status polling.\n- `http.status._exportId` must reference an existing export resource.\n- `http.status.statusPath` tells integrator.io where in the poll response\n to find the status value.\n- For the result phase, omit `http.result._exportId` if the final status\n poll response already contains the data you need.\n","properties":{"name":{"type":"string","description":"Human-readable name for the async helper."},"http":{"type":"object","description":"HTTP configuration for the three async phases: submit, status, and\nresult.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request.","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the status export's\nconfiguration. When `false`, configure `resourcePath`\nand optionally `transform`.\n"},"resourcePath":{"type":"string","description":"Path to extract the async job identifier from the submit\nresponse. Only used when `sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit response.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the remote job's status.","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID for the status polling call."},"statusPath":{"type":"string","description":"Path to extract the status value from the poll response."},"inProgressValues":{"type":"array","description":"Values indicating the remote job is still running.","items":{"type":"string"}},"doneValues":{"type":"array","description":"Values indicating the remote job completed successfully.","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Values indicating completion with no data. Optional.","items":{"type":"string"}},"errorValues":{"type":"array","description":"Values indicating the remote job failed. Optional.","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the result. Omit `_exportId` to use\nthe last status poll response as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID for retrieving the result. Optional."}}}},"required":["submit","status"]}},"required":["name","http"]},"AsyncHelper":{"type":"object","description":"An async helper defines how integrator.io interacts with an external\nsystem's asynchronous job API. It coordinates three phases: submitting a\nrequest, polling for status, and retrieving the result.\n\nAI guidance:\n- The `http.submit.sameAsStatus` flag controls whether the submit step\n reuses the status export's configuration. When `true`, no separate\n submit export is needed.\n- The `http.status._exportId` references an export resource that defines\n the HTTP call used to poll the remote job's status.\n- The `http.status.inProgressValues` and `http.status.doneValues` arrays\n determine how integrator.io interprets the polled status response.\n- `http.result._exportId` is optional -- when omitted, the final status\n poll response is used as the result.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the async helper."},"name":{"type":"string","description":"Human-readable name for the async helper."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"When the async helper was last modified."},"http":{"type":"object","description":"HTTP configuration for the three phases of the async helper:\nsubmit, status, and result.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request to the\nexternal system.\n","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the same export\nconfiguration as the status step (i.e. the same endpoint\nis used to both initiate and poll the job). When `false`,\nyou must configure `resourcePath` and optionally\n`transform` to define a separate submit call.\n"},"resourcePath":{"type":"string","description":"JSONPath or dot-notation path to extract the async job\nidentifier from the submit response. Only used when\n`sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit\nresponse before extracting the resource path.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the external system's async job status.\nThe referenced export defines the HTTP call; the path and value\narrays tell integrator.io how to interpret the response.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nthe status polling call.\n"},"statusPath":{"type":"string","description":"JSONPath or dot-notation path to extract the status value\nfrom the poll response.\n"},"inProgressValues":{"type":"array","description":"Status values that indicate the remote job is still running.\nThe poller continues while the extracted status matches any\nof these values.\n","items":{"type":"string"}},"doneValues":{"type":"array","description":"Status values that indicate the remote job completed\nsuccessfully with data available for retrieval.\n","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Status values that indicate the remote job completed but\nproduced no data (e.g. an empty result set). Optional.\n","items":{"type":"string"}},"errorValues":{"type":"array","description":"Status values that indicate the remote job failed. When\nmatched, integrator.io treats the poll as an error. Optional.\n","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the final result once the status\nindicates completion. If `_exportId` is omitted, the last\nstatus poll response is used as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nretrieving the async job's result. Optional -- if omitted,\nthe result is taken from the final status poll response.\n"}}}},"required":["submit","status"]}},"required":["_id","name","http"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/asynchelpers":{"post":{"operationId":"createAsyncHelper","tags":["Async Helpers"],"summary":"Create an async helper","description":"Creates a new async helper resource.\n\nAI guidance:\n- Required fields: `name`, `http.submit.sameAsStatus`,\n `http.status._exportId`, `http.status.statusPath`,\n `http.status.inProgressValues`, `http.status.doneValues`.\n- The referenced `http.status._exportId` must be an existing export\n resource; the server validates the reference.\n- If `http.submit.sameAsStatus` is `false`, you should also set\n `http.submit.resourcePath` to extract the async job identifier.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncHelperRequest"}}}},"responses":{"201":{"description":"Async helper created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncHelper"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Get an async helper > Returns a single async helper resource by its ID.\ > \ > AI guidance:\ > \- An invalid (non-ObjectId) \`\_id\` returns 400 \`invalid\_ref\`.\ > \- A valid but non-existent \`\_id\` returns 404 \`invalid\_ref\` with message\ > \`"AsyncHelper not found."\`. If the resource was recently deleted, the\ > message may reference the recycle bin. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AsyncHelper":{"type":"object","description":"An async helper defines how integrator.io interacts with an external\nsystem's asynchronous job API. It coordinates three phases: submitting a\nrequest, polling for status, and retrieving the result.\n\nAI guidance:\n- The `http.submit.sameAsStatus` flag controls whether the submit step\n reuses the status export's configuration. When `true`, no separate\n submit export is needed.\n- The `http.status._exportId` references an export resource that defines\n the HTTP call used to poll the remote job's status.\n- The `http.status.inProgressValues` and `http.status.doneValues` arrays\n determine how integrator.io interprets the polled status response.\n- `http.result._exportId` is optional -- when omitted, the final status\n poll response is used as the result.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the async helper."},"name":{"type":"string","description":"Human-readable name for the async helper."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"When the async helper was last modified."},"http":{"type":"object","description":"HTTP configuration for the three phases of the async helper:\nsubmit, status, and result.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request to the\nexternal system.\n","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the same export\nconfiguration as the status step (i.e. the same endpoint\nis used to both initiate and poll the job). When `false`,\nyou must configure `resourcePath` and optionally\n`transform` to define a separate submit call.\n"},"resourcePath":{"type":"string","description":"JSONPath or dot-notation path to extract the async job\nidentifier from the submit response. Only used when\n`sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit\nresponse before extracting the resource path.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the external system's async job status.\nThe referenced export defines the HTTP call; the path and value\narrays tell integrator.io how to interpret the response.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nthe status polling call.\n"},"statusPath":{"type":"string","description":"JSONPath or dot-notation path to extract the status value\nfrom the poll response.\n"},"inProgressValues":{"type":"array","description":"Status values that indicate the remote job is still running.\nThe poller continues while the extracted status matches any\nof these values.\n","items":{"type":"string"}},"doneValues":{"type":"array","description":"Status values that indicate the remote job completed\nsuccessfully with data available for retrieval.\n","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Status values that indicate the remote job completed but\nproduced no data (e.g. an empty result set). Optional.\n","items":{"type":"string"}},"errorValues":{"type":"array","description":"Status values that indicate the remote job failed. When\nmatched, integrator.io treats the poll as an error. Optional.\n","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the final result once the status\nindicates completion. If `_exportId` is omitted, the last\nstatus poll response is used as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nretrieving the async job's result. Optional -- if omitted,\nthe result is taken from the final status poll response.\n"}}}},"required":["submit","status"]}},"required":["_id","name","http"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/asynchelpers/{_id}":{"get":{"operationId":"getAsyncHelperById","tags":["Async Helpers"],"summary":"Get an async helper","description":"Returns a single async helper resource by its ID.\n\nAI guidance:\n- An invalid (non-ObjectId) `_id` returns 400 `invalid_ref`.\n- A valid but non-existent `_id` returns 404 `invalid_ref` with message\n `\"AsyncHelper not found.\"`. If the resource was recently deleted, the\n message may reference the recycle bin.","parameters":[{"name":"_id","in":"path","required":true,"description":"Async helper ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"The async helper record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncHelper"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Update an async helper > Updates an existing async helper with the provided data. This is a full\ > replacement -- all required fields must be included in the request body.\ > \ > AI guidance:\ > \- This is a PUT (full replacement), not a PATCH. Omitted optional fields\ > are removed from the resource.\ > \- The same required fields as POST apply: \`name\`,\ > \`http.submit.sameAsStatus\`, \`http.status.\_exportId\`,\ > \`http.status.statusPath\`, \`http.status.inProgressValues\`,\ > \`http.status.doneValues\`.\ > \- PATCH exists for this resource but has an empty property whitelist,\ > making it effectively unusable. Use PUT for all updates. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AsyncHelperRequest":{"type":"object","description":"Request body for creating or replacing an async helper resource. All\nrequired fields must be present for both POST (create) and PUT (replace)\noperations.\n\nAI guidance:\n- `http.submit.sameAsStatus` is always required. Set to `true` when the\n same endpoint handles both submission and status polling.\n- `http.status._exportId` must reference an existing export resource.\n- `http.status.statusPath` tells integrator.io where in the poll response\n to find the status value.\n- For the result phase, omit `http.result._exportId` if the final status\n poll response already contains the data you need.\n","properties":{"name":{"type":"string","description":"Human-readable name for the async helper."},"http":{"type":"object","description":"HTTP configuration for the three async phases: submit, status, and\nresult.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request.","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the status export's\nconfiguration. When `false`, configure `resourcePath`\nand optionally `transform`.\n"},"resourcePath":{"type":"string","description":"Path to extract the async job identifier from the submit\nresponse. Only used when `sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit response.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the remote job's status.","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID for the status polling call."},"statusPath":{"type":"string","description":"Path to extract the status value from the poll response."},"inProgressValues":{"type":"array","description":"Values indicating the remote job is still running.","items":{"type":"string"}},"doneValues":{"type":"array","description":"Values indicating the remote job completed successfully.","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Values indicating completion with no data. Optional.","items":{"type":"string"}},"errorValues":{"type":"array","description":"Values indicating the remote job failed. Optional.","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the result. Omit `_exportId` to use\nthe last status poll response as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID for retrieving the result. Optional."}}}},"required":["submit","status"]}},"required":["name","http"]},"AsyncHelper":{"type":"object","description":"An async helper defines how integrator.io interacts with an external\nsystem's asynchronous job API. It coordinates three phases: submitting a\nrequest, polling for status, and retrieving the result.\n\nAI guidance:\n- The `http.submit.sameAsStatus` flag controls whether the submit step\n reuses the status export's configuration. When `true`, no separate\n submit export is needed.\n- The `http.status._exportId` references an export resource that defines\n the HTTP call used to poll the remote job's status.\n- The `http.status.inProgressValues` and `http.status.doneValues` arrays\n determine how integrator.io interprets the polled status response.\n- `http.result._exportId` is optional -- when omitted, the final status\n poll response is used as the result.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the async helper."},"name":{"type":"string","description":"Human-readable name for the async helper."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"When the async helper was last modified."},"http":{"type":"object","description":"HTTP configuration for the three phases of the async helper:\nsubmit, status, and result.\n","properties":{"submit":{"type":"object","description":"Configuration for submitting the initial async request to the\nexternal system.\n","properties":{"sameAsStatus":{"type":"boolean","description":"When `true`, the submit step reuses the same export\nconfiguration as the status step (i.e. the same endpoint\nis used to both initiate and poll the job). When `false`,\nyou must configure `resourcePath` and optionally\n`transform` to define a separate submit call.\n"},"resourcePath":{"type":"string","description":"JSONPath or dot-notation path to extract the async job\nidentifier from the submit response. Only used when\n`sameAsStatus` is `false`.\n"},"transform":{"type":"object","description":"Optional transformation rules applied to the submit\nresponse before extracting the resource path.\n"}},"required":["sameAsStatus"]},"status":{"type":"object","description":"Configuration for polling the external system's async job status.\nThe referenced export defines the HTTP call; the path and value\narrays tell integrator.io how to interpret the response.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nthe status polling call.\n"},"statusPath":{"type":"string","description":"JSONPath or dot-notation path to extract the status value\nfrom the poll response.\n"},"inProgressValues":{"type":"array","description":"Status values that indicate the remote job is still running.\nThe poller continues while the extracted status matches any\nof these values.\n","items":{"type":"string"}},"doneValues":{"type":"array","description":"Status values that indicate the remote job completed\nsuccessfully with data available for retrieval.\n","items":{"type":"string"}},"doneWithoutDataValues":{"type":"array","description":"Status values that indicate the remote job completed but\nproduced no data (e.g. an empty result set). Optional.\n","items":{"type":"string"}},"errorValues":{"type":"array","description":"Status values that indicate the remote job failed. When\nmatched, integrator.io treats the poll as an error. Optional.\n","items":{"type":"string"}}},"required":["_exportId","statusPath","inProgressValues","doneValues"]},"result":{"type":"object","description":"Configuration for retrieving the final result once the status\nindicates completion. If `_exportId` is omitted, the last\nstatus poll response is used as the result.\n","properties":{"_exportId":{"type":"string","format":"objectId","description":"Export resource ID that defines the HTTP configuration for\nretrieving the async job's result. Optional -- if omitted,\nthe result is taken from the final status poll response.\n"}}}},"required":["submit","status"]}},"required":["_id","name","http"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/asynchelpers/{_id}":{"put":{"operationId":"updateAsyncHelper","tags":["Async Helpers"],"summary":"Update an async helper","description":"Updates an existing async helper with the provided data. This is a full\nreplacement -- all required fields must be included in the request body.\n\nAI guidance:\n- This is a PUT (full replacement), not a PATCH. Omitted optional fields\n are removed from the resource.\n- The same required fields as POST apply: `name`,\n `http.submit.sameAsStatus`, `http.status._exportId`,\n `http.status.statusPath`, `http.status.inProgressValues`,\n `http.status.doneValues`.\n- PATCH exists for this resource but has an empty property whitelist,\n making it effectively unusable. Use PUT for all updates.","parameters":[{"name":"_id","in":"path","required":true,"description":"Async helper ID.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncHelperRequest"}}}},"responses":{"200":{"description":"Async helper updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncHelper"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Delete an async helper > Deletes an async helper. The resource is soft-deleted and retained in\ > the recycle bin for 30 days before permanent removal.\ > \ > AI guidance:\ > \- After deletion, \`GET /v1/asynchelpers/{\_id}\` returns 404 with a\ > message referencing the recycle bin.\ > \- To recover a deleted async helper, use the recycle bin API within\ > the retention period. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/asynchelpers/{_id}":{"delete":{"operationId":"deleteAsyncHelper","tags":["Async Helpers"],"summary":"Delete an async helper","description":"Deletes an async helper. The resource is soft-deleted and retained in\nthe recycle bin for 30 days before permanent removal.\n\nAI guidance:\n- After deletion, `GET /v1/asynchelpers/{_id}` returns 404 with a\n message referencing the recycle bin.\n- To recover a deleted async helper, use the recycle bin API within\n the retention period.","parameters":[{"name":"_id","in":"path","required":true,"description":"Async helper ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Async helper deleted successfully."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## List dependencies of an async helper > Returns the set of resources that depend on the specified resource.\ > The response is an object whose keys are dependent-resource types\ > (e.g. \`flows\`, \`imports\`) and whose values are arrays of dependency\ > entries.\ > \ > AI guidance:\ > \- An empty object \`{}\` means no other resources depend on the target.\ > This is also returned for a well-formatted but nonexistent id. ```json {"openapi":"3.1.0","info":{"title":"Async Helpers","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"paths":{"type":"array","description":"JSON-path-style pointers within the dependent resource's document\nthat reference the target resource.\n","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of ids that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of id strings.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/asynchelpers/{_id}/dependencies":{"get":{"operationId":"listAsyncHelperDependencies","tags":["Async Helpers"],"summary":"List dependencies of an async helper","description":"Returns the set of resources that depend on the specified resource.\nThe response is an object whose keys are dependent-resource types\n(e.g. `flows`, `imports`) and whose values are arrays of dependency\nentries.\n\nAI guidance:\n- An empty object `{}` means no other resources depend on the target.\n This is also returned for a well-formatted but nonexistent id.","parameters":[{"name":"_id","in":"path","required":true,"description":"Resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.celigo.com/api/api-reference/async-helpers.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.