# Stacks ## List stacks > Returns a list of stacks configured in the account (server stacks and lambda stacks). ```json {"openapi":"3.1.0","info":{"title":"Stacks","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"}},"parameters":{"Include":{"name":"include","in":"query","required":false,"description":"Comma-separated list of fields to project into each returned record.\nTriggers **summary projection** on supported list endpoints: the server\nreturns a minimal identity set for each record (`_id`, `name`, plus a\nresource-specific always-on set like `adaptorType` on exports/imports,\nor richer defaults on `ashares`, `audit`, `httpconnectors`, `transfers`,\netc.) and adds any listed fields that exist on the record. Listed fields\nthe record doesn't carry are silently dropped.\n\nDot notation is supported for projecting nested sub-fields — e.g.\n`include=ftp.directoryPath` on `/v1/exports` returns just that nested\nfield inside `ftp` for FTP-type exports (and omits `ftp` entirely for\nnon-FTP exports).\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n comma separator; digits are also accepted in practice. Any other\n character returns **400 `invalid_query_params`**.\n- Empty value (`include=`) or bare `include` is ignored — the full\n default record is returned.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n returns **400 `invalid_query_params`**: *\"Please provide either\n include or exclude param in the request query and not both.\"*\n- Array-bracket syntax (`include[]=...`) is not supported and can return\n a 500.\n- Only list endpoints honor projection — on GET-by-id the parameter is\n silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n `exclude` with **400 `invalid_query_params`** and a message of the form\n *\"Include or exclude query params are not applicable for ``\n resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to remove from the default response on\nsupported list endpoints. Unlike `include`, `exclude` does NOT trigger\nsummary projection — callers get the standard full-record shape with the\nnamed fields stripped out.\n\nRules:\n- Value regex is `{a-z A-Z . _}` (letters, dots, underscores) plus the\n comma separator; digits are also accepted in practice. Any other\n character returns **400 `invalid_query_params`**.\n- Empty value (`exclude=`) is ignored.\n- Certain protected identity fields **cannot be stripped** — e.g.\n `exclude=name` on `/v1/exports` is silently ignored and `name` remains\n in the response. Protected sets vary per resource.\n- `include` and `exclude` are **mutually exclusive**. Passing both\n returns **400 `invalid_query_params`**: *\"Please provide either\n include or exclude param in the request query and not both.\"*\n- Only list endpoints honor stripping — on GET-by-id the parameter is\n silently ignored.\n- A small set of list endpoints explicitly reject both `include` and\n `exclude` with **400 `invalid_query_params`** and a message of the form\n *\"Include or exclude query params are not applicable for ``\n resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}}},"schemas":{"Response":{"type":"object","description":"Response schema for stack operations.\n\nContains the complete stack configuration. Secrets (system token,\nAWS secret access key) are masked as \"******\" in responses.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the stack"},"name":{"type":"string","description":"Human-readable name for the stack"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version"},"server":{"type":"object","description":"Server stack configuration. Only present when `type` is \"server\"\nand `hostURI` is set.\n","properties":{"systemToken":{"type":"string","description":"System token for authenticating with the server stack.\n\nAlways masked as \"******\" in standard responses. Use the\ndedicated `/stacks/{_id}/systemToken` endpoint to retrieve\nthe actual value.\n"},"hostURI":{"type":"string","description":"Base URI of the server"},"ipRanges":{"type":"array","description":"Allowed IP ranges","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Lambda stack configuration. Only present when `type` is \"lambda\".\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID"},"secretAccessKey":{"type":"string","description":"AWS secret access key. Always masked as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed"},"functionName":{"type":"string","description":"Name or ARN of the Lambda function"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"description":"Programming language of the Lambda function"}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was last modified"}}}},"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/stacks":{"get":{"summary":"List stacks","description":"Returns a list of stacks configured in the account (server stacks and lambda stacks).","operationId":"listStacks","tags":["Stacks"],"parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Successfully retrieved list of stacks.","headers":{"Link":{"description":"RFC-5988 pagination links. When more pages remain, includes a `<...>; rel=\"next\"` entry;\nabsent on the final page.\n","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Response"}}}}},"204":{"description":"No stacks exist in the account."},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}} ``` ## Create a stack > Creates a new stack.\ > \- For \`type=server\`, provide \`server.hostURI\` (and optional \`server.ipRanges\`).\ > \- For \`type=lambda\`, provide AWS credentials and function details under \`lambda\`.
```json {"openapi":"3.1.0","info":{"title":"Stacks","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":{"Request":{"type":"object","description":"Request schema for creating or updating a stack.\n\nStacks provide execution environments for custom scripts, hooks, and wrappers\nin integrator.io. Two types are supported:\n\n- **server**: A self-hosted server stack with a system token for authentication\n- **lambda**: An AWS Lambda function stack with AWS credentials\n","properties":{"name":{"type":"string","description":"Human-readable name for the stack.\n"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment.\n\n- **server**: Self-hosted server that communicates via HTTP with a system token\n- **lambda**: AWS Lambda function invoked directly via AWS SDK\n"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version for the stack. Currently only \"twoDotZero\" is supported.\n"},"server":{"type":"object","description":"Configuration for server-type stacks.\n\nRequired when `type` is \"server\". The system token is auto-generated\non creation and cannot be set directly.\n","properties":{"hostURI":{"type":"string","description":"The base URI of the server hosting the stack.\n\nMust be a valid, reachable HTTP(S) endpoint.\n"},"ipRanges":{"type":"array","description":"Allowed IP ranges for the server stack.\n\nIf specified, only requests from these IP ranges will be accepted.\n","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Configuration for AWS Lambda-type stacks.\n\nRequired when `type` is \"lambda\". All fields except `language` are required.\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for invoking the Lambda function.\n"},"secretAccessKey":{"type":"string","description":"AWS secret access key. This is a write-only field — responses\nwill mask it as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed.\n"},"functionName":{"type":"string","description":"Name or ARN of the AWS Lambda function.\n"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"default":"Node.js","description":"Programming language of the Lambda function.\n"}}}},"required":["name","type"]},"Response":{"type":"object","description":"Response schema for stack operations.\n\nContains the complete stack configuration. Secrets (system token,\nAWS secret access key) are masked as \"******\" in responses.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the stack"},"name":{"type":"string","description":"Human-readable name for the stack"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version"},"server":{"type":"object","description":"Server stack configuration. Only present when `type` is \"server\"\nand `hostURI` is set.\n","properties":{"systemToken":{"type":"string","description":"System token for authenticating with the server stack.\n\nAlways masked as \"******\" in standard responses. Use the\ndedicated `/stacks/{_id}/systemToken` endpoint to retrieve\nthe actual value.\n"},"hostURI":{"type":"string","description":"Base URI of the server"},"ipRanges":{"type":"array","description":"Allowed IP ranges","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Lambda stack configuration. Only present when `type` is \"lambda\".\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID"},"secretAccessKey":{"type":"string","description":"AWS secret access key. Always masked as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed"},"functionName":{"type":"string","description":"Name or ARN of the Lambda function"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"description":"Programming language of the Lambda function"}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was last modified"}}},"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/stacks":{"post":{"summary":"Create a stack","description":"Creates a new stack.\n- For `type=server`, provide `server.hostURI` (and optional `server.ipRanges`).\n- For `type=lambda`, provide AWS credentials and function details under `lambda`.\n","operationId":"createStack","tags":["Stacks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"Stack created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}} ``` ## Get a stack > Returns a single stack by id. ```json {"openapi":"3.1.0","info":{"title":"Stacks","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":{"Response":{"type":"object","description":"Response schema for stack operations.\n\nContains the complete stack configuration. Secrets (system token,\nAWS secret access key) are masked as \"******\" in responses.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the stack"},"name":{"type":"string","description":"Human-readable name for the stack"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version"},"server":{"type":"object","description":"Server stack configuration. Only present when `type` is \"server\"\nand `hostURI` is set.\n","properties":{"systemToken":{"type":"string","description":"System token for authenticating with the server stack.\n\nAlways masked as \"******\" in standard responses. Use the\ndedicated `/stacks/{_id}/systemToken` endpoint to retrieve\nthe actual value.\n"},"hostURI":{"type":"string","description":"Base URI of the server"},"ipRanges":{"type":"array","description":"Allowed IP ranges","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Lambda stack configuration. Only present when `type` is \"lambda\".\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID"},"secretAccessKey":{"type":"string","description":"AWS secret access key. Always masked as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed"},"functionName":{"type":"string","description":"Name or ARN of the Lambda function"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"description":"Programming language of the Lambda function"}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was last modified"}}},"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":{"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/stacks/{_id}":{"get":{"summary":"Get a stack","description":"Returns a single stack by id.","operationId":"getStackById","tags":["Stacks"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"Stack id."}],"responses":{"200":{"description":"Stack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Update a stack > Updates a stack by id.\ > \- You can update \`name\`, \`framework\`, and the config object for the active \`type\`.\ > \- Secrets are write-only: provide a new secret value in the request to replace it; responses return masked values.
```json {"openapi":"3.1.0","info":{"title":"Stacks","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":{"Request":{"type":"object","description":"Request schema for creating or updating a stack.\n\nStacks provide execution environments for custom scripts, hooks, and wrappers\nin integrator.io. Two types are supported:\n\n- **server**: A self-hosted server stack with a system token for authentication\n- **lambda**: An AWS Lambda function stack with AWS credentials\n","properties":{"name":{"type":"string","description":"Human-readable name for the stack.\n"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment.\n\n- **server**: Self-hosted server that communicates via HTTP with a system token\n- **lambda**: AWS Lambda function invoked directly via AWS SDK\n"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version for the stack. Currently only \"twoDotZero\" is supported.\n"},"server":{"type":"object","description":"Configuration for server-type stacks.\n\nRequired when `type` is \"server\". The system token is auto-generated\non creation and cannot be set directly.\n","properties":{"hostURI":{"type":"string","description":"The base URI of the server hosting the stack.\n\nMust be a valid, reachable HTTP(S) endpoint.\n"},"ipRanges":{"type":"array","description":"Allowed IP ranges for the server stack.\n\nIf specified, only requests from these IP ranges will be accepted.\n","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Configuration for AWS Lambda-type stacks.\n\nRequired when `type` is \"lambda\". All fields except `language` are required.\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID for invoking the Lambda function.\n"},"secretAccessKey":{"type":"string","description":"AWS secret access key. This is a write-only field — responses\nwill mask it as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed.\n"},"functionName":{"type":"string","description":"Name or ARN of the AWS Lambda function.\n"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"default":"Node.js","description":"Programming language of the Lambda function.\n"}}}},"required":["name","type"]},"Response":{"type":"object","description":"Response schema for stack operations.\n\nContains the complete stack configuration. Secrets (system token,\nAWS secret access key) are masked as \"******\" in responses.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the stack"},"name":{"type":"string","description":"Human-readable name for the stack"},"type":{"type":"string","enum":["server","lambda"],"description":"Type of stack execution environment"},"framework":{"type":"string","enum":["twoDotZero"],"description":"Framework version"},"server":{"type":"object","description":"Server stack configuration. Only present when `type` is \"server\"\nand `hostURI` is set.\n","properties":{"systemToken":{"type":"string","description":"System token for authenticating with the server stack.\n\nAlways masked as \"******\" in standard responses. Use the\ndedicated `/stacks/{_id}/systemToken` endpoint to retrieve\nthe actual value.\n"},"hostURI":{"type":"string","description":"Base URI of the server"},"ipRanges":{"type":"array","description":"Allowed IP ranges","items":{"type":"string"}}}},"lambda":{"type":"object","description":"Lambda stack configuration. Only present when `type` is \"lambda\".\n","properties":{"accessKeyId":{"type":"string","description":"AWS access key ID"},"secretAccessKey":{"type":"string","description":"AWS secret access key. Always masked as \"******\".\n"},"awsRegion":{"type":"string","enum":["us-east-1","us-east-2","us-west-1","us-west-2","ap-northeast-2","ap-southeast-1","ap-southeast-2","ap-northeast-1","ap-south-1","eu-central-1","eu-west-1"],"description":"AWS region where the Lambda function is deployed"},"functionName":{"type":"string","description":"Name or ARN of the Lambda function"},"language":{"type":"string","enum":["Node.js","C#","Java","Other"],"description":"Programming language of the Lambda function"}}},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the stack was last modified"}}},"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/stacks/{_id}":{"put":{"summary":"Update a stack","description":"Updates a stack by id.\n- You can update `name`, `framework`, and the config object for the active `type`.\n- Secrets are write-only: provide a new secret value in the request to replace it; responses return masked values.\n","operationId":"updateStack","tags":["Stacks"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"Stack id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Updated stack.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"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 a stack > Deletes a stack. The stack is soft-deleted and retained in the recycle bin\ > for 30 days before permanent removal. ```json {"openapi":"3.1.0","info":{"title":"Stacks","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/stacks/{_id}":{"delete":{"summary":"Delete a stack","description":"Deletes a stack. The stack is soft-deleted and retained in the recycle bin\nfor 30 days before permanent removal.","operationId":"deleteStack","tags":["Stacks"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"Stack id."}],"responses":{"204":{"description":"Stack deleted."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}} ``` ## Get stack system token (server stacks only) > Returns the \*\*actual\*\* \`systemToken\` for a server stack.\ > Note: \`server.systemToken\` on the normal stack response is masked (\`\*\*\*\*\*\*\`). Use this endpoint to retrieve the real token.
```json {"openapi":"3.1.0","info":{"title":"Stacks","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":{"SystemTokenResponse":{"type":"object","description":"Response containing the actual system token value for a server stack.\n\nThis endpoint returns the unmasked token, unlike the standard stack\nresponse which always masks it as \"******\".\n","properties":{"systemToken":{"type":"string","description":"The actual system token value for authenticating with the server stack.\n"}}}},"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/stacks/{_id}/systemToken":{"get":{"summary":"Get stack system token (server stacks only)","description":"Returns the **actual** `systemToken` for a server stack.\nNote: `server.systemToken` on the normal stack response is masked (`******`). Use this endpoint to retrieve the real token.\n","operationId":"getStackSystemToken","tags":["Stacks"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"Stack id."}],"responses":{"200":{"description":"System token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SystemTokenResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Stack not found (or not a server stack)."}}}}}} ``` ## Recycle stack system token (server stacks only) > Rotates (recycles) the server stack's system token.\ > After this operation, any clients using the old token must be updated to use the new token.
```json {"openapi":"3.1.0","info":{"title":"Stacks","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"]}}}}}},"paths":{"/v1/stacks/{_id}/systemToken":{"delete":{"summary":"Recycle stack system token (server stacks only)","description":"Rotates (recycles) the server stack's system token.\nAfter this operation, any clients using the old token must be updated to use the new token.\n","operationId":"recycleStackSystemToken","tags":["Stacks"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"Stack id."}],"responses":{"204":{"description":"Token recycled successfully."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Stack not found (or not a server stack)."}}}}}} ``` ## List dependencies of a stack > 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":"Stacks","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/stacks/{_id}/dependencies":{"get":{"operationId":"listStackDependencies","tags":["Stacks"],"summary":"List dependencies of a stack","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/stacks.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.