# APIs

## List APIs

> Returns a list of all APIs configured in the account.\
> If no APIs exist in the account, a 204 response with no body will be returned.<br>

```json
{"openapi":"3.1.0","info":{"title":"APIs","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 `<resource>`\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 `<resource>`\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 API operations.\n\nContains the complete API configuration including metadata, script/builder settings,\nand integration-specific configurations.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the API"},"name":{"type":"string","description":"Human-readable name for the API"},"description":{"type":"string","description":"Optional detailed description of the API"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration (builder or script)"},"version":{"type":"string","description":"Version identifier for the API endpoint"},"disabled":{"type":"boolean","description":"Whether the API is disabled"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was last modified"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"},"apim":{"$ref":"#/components/schemas/Apim"}}},"Script":{"type":"object","description":"Script configuration for script-mode APIs.\n\nIn script mode, you provide a custom JavaScript function that receives the request\nobject and returns the response. This gives you complete control over the API behavior.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource containing the implementation.\n\nThe script must exist in your account and be accessible to the user.\n"},"function":{"type":"string","description":"Name of the function to invoke within the script.\n\nThis function receives the request object and must return a response object\nwith statusCode, headers, and body properties.\n"}},"required":["_scriptId","function"]},"Builder":{"type":"object","description":"Builder configuration for visual API construction.\n\nThe builder mode allows you to define your API using visual configuration:\n- Define the request structure (method, path, parameters)\n- Transform incoming requests\n- Route requests through processing logic\n- Map and transform responses\n","properties":{"request":{"$ref":"#/components/schemas/ApiRequest"},"routers":{"type":"array","description":"Optional routers for conditional processing logic.\n\nRouters allow you to direct requests to different processing branches\nbased on criteria. This enables complex business logic within the API.\n","items":{"$ref":"#/components/schemas/Router"}},"responseRouter":{"$ref":"#/components/schemas/ResponseRouter"},"responses":{"type":"array","description":"Response configurations defining how to format and return data.\n\nMust include exactly one 'success' response and one 'fail' response.\nAdditional custom responses can be added for specific scenarios.\n","items":{"$ref":"#/components/schemas/ApiResponse"}}},"required":["request"]},"ApiRequest":{"type":"object","description":"Configuration for the API request structure in builder mode.\n\nDefines how the API endpoint receives data:\n- HTTP method and URI path\n- Expected parameters (path, query, headers)\n- Request body schema\n- Optional request transformation logic\n","properties":{"name":{"type":"string","maxLength":200,"description":"Display name for the request configuration.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of what the request does.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9:_*\\/\\-\\.]*$","description":"URI path relative to the version.\n\nFull endpoint URL will be: `/{version}{relativeURI}`\nCan include path parameters using colon notation: `/customers/:id`\nFirst path segment must be alphanumeric, dash, or underscore only.\n"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method for the API endpoint.\n"},"headers":{"type":"array","description":"Expected request headers.\n\nDocuments headers that clients should send. Headers are optional by default.\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"description":{"type":"string","maxLength":10240,"description":"Description of the header's purpose"}}}},"pathParams":{"type":"array","description":"Path parameters defined in the relativeURI.\n\nDocuments the parameters that are part of the URL path (e.g., :id, :customerId).\nThese should match the parameters defined in the relativeURI.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"description":"Parameter name (without the colon prefix)"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"queryParams":{"type":"array","description":"Expected query string parameters.\n\nDocuments parameters that can be passed in the URL query string.\nQuery parameters are optional by default.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_\\-:\\/]*$","description":"Query parameter name"},"dataType":{"type":"string","enum":["string","number","boolean"],"description":"Expected data type of the parameter"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the expected request body structure.\n\nUsed for documentation and validation of the request payload.\nTypically used with POST, PUT, and PATCH methods.\n","additionalProperties":true},"mockRequest":{"type":"object","description":"Mock request data for testing the API.\n\nProvides sample data to test the API without making actual calls.\nCan include body, headers, pathParams, and queryParams.\n","properties":{"body":{"type":"object","description":"Sample request body"},"headers":{"type":"object","description":"Sample headers"},"pathParams":{"type":"object","description":"Sample path parameters"},"queryParams":{"type":"object","description":"Sample query parameters"}},"additionalProperties":false},"transform":{"type":"object","description":"Optional transformation to apply to the incoming request.\n\nTransforms the request data before it is processed by routers or responses.\nUseful for normalizing data or extracting specific fields.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to a script for custom transformation logic"},"function":{"type":"string","description":"Function name in the script to execute"}}}},"required":["relativeURI","method"]},"Router":{"type":"object","description":"Configuration for conditional routing within builder-mode APIs.\n\nRouters evaluate the request and route it to different processing branches.\nThis enables complex business logic and conditional processing within your API.\n\nNote: Unlike flows, APIs only support \"first_matching_branch\" routing.\n","properties":{"id":{"type":"string","description":"Unique identifier for this router within the API.\n\nUsed to reference this router from other routers and branches.\n"},"name":{"type":"string","description":"Human-readable name for the router.\n"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch"],"description":"Routing strategy for APIs.\n\nAPIs only support \"first_matching_branch\" which routes to the first\nbranch whose criteria match.\n","default":"first_matching_branch"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to evaluate routing criteria.\n\n- **input_filters**: Use declarative filter expressions\n- **script**: Use custom JavaScript for complex logic\n","default":"input_filters"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the branch name"}}},"branches":{"type":"array","description":"List of branches that define different processing paths.\n\nEach branch has its own criteria and processing steps. Requests are\nevaluated against branch criteria in the order defined.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Branch name"},"inputFilter":{"type":"object","description":"Filter criteria to determine if this branch should be selected.\n\nUses Celigo's expression-based filter format.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"nextRouterId":{"type":"string","description":"Next router to chain to (or \"apiRouter\" for final routing)"},"pageProcessors":{"type":"array","description":"Processing steps to execute in this branch","items":{"type":"object","properties":{"type":{"type":"string","enum":["export","import"],"description":"Type of processor"},"_exportId":{"type":"string","format":"objectId","description":"Export resource reference (when type=\"export\")"},"_importId":{"type":"string","format":"objectId","description":"Import resource reference (when type=\"import\")"},"hooks":{"type":"object","description":"Custom scripts for processing"}}}}}}}},"required":["branches"]},"ResponseRouter":{"type":"object","description":"Configuration for routing to different response configurations.\n\nThe response router determines which response configuration to use based on\nthe processing results. This allows you to return different responses based\non different conditions or outcomes.\n\nMust have id=\"apiRouter\" to serve as the final routing step before returning\nto the caller.\n","properties":{"id":{"type":"string","description":"Identifier for the response router.\n\nMust be \"apiRouter\" to indicate this is the final router before\nreturning the API response.\n","enum":["apiRouter"]},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to determine which response to use.\n\n- **input_filters**: Use declarative filter expressions on each response\n- **script**: Use custom JavaScript to return the response id\n"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n\nThe script function should return the id of the response to use.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the response id.\n\nThe function receives the processing results and should return\na string matching one of the response ids.\n"}}}},"required":["id"]},"ApiResponse":{"type":"object","description":"Configuration for an API response in builder mode.\n\nDefines how to format and return data to the caller. Each API must have:\n- Exactly one 'success' response (for successful operations)\n- Exactly one 'fail' response (for errors)\n- Zero or more 'custom' responses (for specific scenarios)\n","properties":{"id":{"type":"string","description":"Unique identifier for this response within the API.\n\nUsed to route to this response from the response router.\n"},"name":{"type":"string","maxLength":200,"description":"Display name for the response.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of when this response is used.\n"},"type":{"type":"string","enum":["success","fail","custom"],"description":"Type of response.\n\n- **success**: Default response for successful operations (required, exactly one)\n- **fail**: Default response for errors (required, exactly one)\n- **custom**: Additional responses for specific scenarios (optional, multiple allowed)\n"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code to return.\n\nCommon codes:\n- 200: Success\n- 201: Created\n- 400: Bad Request\n- 404: Not Found\n- 500: Internal Server Error\n"},"headers":{"type":"array","description":"Response headers to include.\n\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"value":{"type":"string","maxLength":256,"description":"Header value (can include handlebars templates)"},"description":{"type":"string","maxLength":10240,"description":"Description of the header"}}}},"inputFilter":{"type":"object","description":"Optional filter to determine when this response should be used.\n\nApplied when routing to this response from the response router.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the response body structure.\n\nUsed for documentation and OpenAPI specification generation.\n","additionalProperties":true},"mockInput":{"type":"object","description":"Mock data to use when testing this response.\n\nProvides sample data that would come from processing logic.\nMaximum size: 1MB\n","additionalProperties":true},"mappings":{"type":"array","description":"Field mappings to transform data into the response format.\n\nMaps data from processing results to the response body structure.\n","items":{"type":"object","properties":{"generate":{"type":"string","description":"Target field path in the response"},"extract":{"type":"string","description":"Source field path from input data"},"hardcodedValue":{"description":"Static value to use"}}}},"lookups":{"type":"array","description":"Lookup tables for data enrichment or transformation.\n\nStatic key-value mappings to transform values during response generation.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the lookup"},"map":{"type":"object","description":"Key-value mapping object"},"default":{"type":"string","description":"Default value if key not found"},"allowFailures":{"type":"boolean","description":"Whether to continue if lookup fails"}}}},"hooks":{"type":"object","description":"Custom scripts to run during response processing.\n","properties":{"preMap":{"type":"object","description":"Script to run before applying mappings.\n\nCan modify the input data before it's mapped to the response.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}},"postMap":{"type":"object","description":"Script to run after applying mappings.\n\nCan modify the response data after mappings are applied.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}}}}},"required":["id","name","type"]},"Shipworks":{"type":"object","description":"ShipWorks integration configuration.\n\nShipWorks is a shipping management platform. This configuration stores\nauthentication credentials for ShipWorks-specific API integrations.\n","properties":{"username":{"type":"string","description":"ShipWorks username for authentication.\n"},"password":{"type":"string","description":"ShipWorks password for authentication.\n\nWhen retrieving, this will be masked as \"******\" if a password is set.\nWhen creating/updating, provide the actual password value.\n"}},"required":["username","password"]},"Apim":{"type":"array","description":"API Management (APIM) integration metadata.\n\nTracks the publication status of this API to external API management systems\nand portals. Used for generating and syncing OpenAPI specifications.\n","items":{"type":"object","properties":{"apiId":{"type":"string","description":"Unique identifier in the API management system.\n"},"flowId":{"type":"string","description":"Associated flow identifier in the API management system.\n"},"status":{"type":"string","enum":["oaspending","published"],"description":"Publication status.\n\n- **oaspending**: OpenAPI spec generation/update is pending\n- **published**: API is published to the management system\n"},"definitionVersion":{"type":"string","enum":["v4"],"description":"Version of the API definition format.\n\nCurrently only \"v4\" is supported.\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/apis":{"get":{"summary":"List APIs","description":"Returns a list of all APIs configured in the account.\nIf no APIs exist in the account, a 204 response with no body will be returned.\n","operationId":"listApis","tags":["APIs"],"parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Successfully retrieved list of APIs","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 APIs exist in the account"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create an API

> Creates a new API configuration that exposes integration logic as a RESTful endpoint.\
> \
> You can create either a builder-mode API (visual configuration) or a script-mode API\
> (custom JavaScript function).<br>

```json
{"openapi":"3.1.0","info":{"title":"APIs","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 an API.\n\nAPIs can be configured in two modes:\n- **builder**: Visual configuration with request/response mapping and transformations\n- **script**: Custom JavaScript function for complete control\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the API.\n\nDisplayed in the UI and logs to help identify the API's purpose.\n"},"description":{"type":"string","description":"Optional detailed description of what the API does.\n\nUse this to document the API's purpose, expected inputs/outputs, and any special considerations.\n"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration.\n\n- **builder**: Use visual configuration with request/response mapping\n- **script**: Use custom JavaScript for complete control\n"},"version":{"type":"string","default":"v1","pattern":"^[a-zA-Z0-9\\-_\\.]+$","description":"Version identifier for the API endpoint.\n\nThis becomes part of the URL path: `/{version}/{relativeURI}`\nOnly alphanumeric characters, dashes, underscores, and dots are allowed.\n"},"disabled":{"type":"boolean","default":false,"description":"Whether the API is disabled.\n\nDisabled APIs cannot be invoked and will return a 404 error.\n"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"}},"required":["type"]},"Script":{"type":"object","description":"Script configuration for script-mode APIs.\n\nIn script mode, you provide a custom JavaScript function that receives the request\nobject and returns the response. This gives you complete control over the API behavior.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource containing the implementation.\n\nThe script must exist in your account and be accessible to the user.\n"},"function":{"type":"string","description":"Name of the function to invoke within the script.\n\nThis function receives the request object and must return a response object\nwith statusCode, headers, and body properties.\n"}},"required":["_scriptId","function"]},"Builder":{"type":"object","description":"Builder configuration for visual API construction.\n\nThe builder mode allows you to define your API using visual configuration:\n- Define the request structure (method, path, parameters)\n- Transform incoming requests\n- Route requests through processing logic\n- Map and transform responses\n","properties":{"request":{"$ref":"#/components/schemas/ApiRequest"},"routers":{"type":"array","description":"Optional routers for conditional processing logic.\n\nRouters allow you to direct requests to different processing branches\nbased on criteria. This enables complex business logic within the API.\n","items":{"$ref":"#/components/schemas/Router"}},"responseRouter":{"$ref":"#/components/schemas/ResponseRouter"},"responses":{"type":"array","description":"Response configurations defining how to format and return data.\n\nMust include exactly one 'success' response and one 'fail' response.\nAdditional custom responses can be added for specific scenarios.\n","items":{"$ref":"#/components/schemas/ApiResponse"}}},"required":["request"]},"ApiRequest":{"type":"object","description":"Configuration for the API request structure in builder mode.\n\nDefines how the API endpoint receives data:\n- HTTP method and URI path\n- Expected parameters (path, query, headers)\n- Request body schema\n- Optional request transformation logic\n","properties":{"name":{"type":"string","maxLength":200,"description":"Display name for the request configuration.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of what the request does.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9:_*\\/\\-\\.]*$","description":"URI path relative to the version.\n\nFull endpoint URL will be: `/{version}{relativeURI}`\nCan include path parameters using colon notation: `/customers/:id`\nFirst path segment must be alphanumeric, dash, or underscore only.\n"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method for the API endpoint.\n"},"headers":{"type":"array","description":"Expected request headers.\n\nDocuments headers that clients should send. Headers are optional by default.\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"description":{"type":"string","maxLength":10240,"description":"Description of the header's purpose"}}}},"pathParams":{"type":"array","description":"Path parameters defined in the relativeURI.\n\nDocuments the parameters that are part of the URL path (e.g., :id, :customerId).\nThese should match the parameters defined in the relativeURI.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"description":"Parameter name (without the colon prefix)"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"queryParams":{"type":"array","description":"Expected query string parameters.\n\nDocuments parameters that can be passed in the URL query string.\nQuery parameters are optional by default.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_\\-:\\/]*$","description":"Query parameter name"},"dataType":{"type":"string","enum":["string","number","boolean"],"description":"Expected data type of the parameter"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the expected request body structure.\n\nUsed for documentation and validation of the request payload.\nTypically used with POST, PUT, and PATCH methods.\n","additionalProperties":true},"mockRequest":{"type":"object","description":"Mock request data for testing the API.\n\nProvides sample data to test the API without making actual calls.\nCan include body, headers, pathParams, and queryParams.\n","properties":{"body":{"type":"object","description":"Sample request body"},"headers":{"type":"object","description":"Sample headers"},"pathParams":{"type":"object","description":"Sample path parameters"},"queryParams":{"type":"object","description":"Sample query parameters"}},"additionalProperties":false},"transform":{"type":"object","description":"Optional transformation to apply to the incoming request.\n\nTransforms the request data before it is processed by routers or responses.\nUseful for normalizing data or extracting specific fields.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to a script for custom transformation logic"},"function":{"type":"string","description":"Function name in the script to execute"}}}},"required":["relativeURI","method"]},"Router":{"type":"object","description":"Configuration for conditional routing within builder-mode APIs.\n\nRouters evaluate the request and route it to different processing branches.\nThis enables complex business logic and conditional processing within your API.\n\nNote: Unlike flows, APIs only support \"first_matching_branch\" routing.\n","properties":{"id":{"type":"string","description":"Unique identifier for this router within the API.\n\nUsed to reference this router from other routers and branches.\n"},"name":{"type":"string","description":"Human-readable name for the router.\n"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch"],"description":"Routing strategy for APIs.\n\nAPIs only support \"first_matching_branch\" which routes to the first\nbranch whose criteria match.\n","default":"first_matching_branch"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to evaluate routing criteria.\n\n- **input_filters**: Use declarative filter expressions\n- **script**: Use custom JavaScript for complex logic\n","default":"input_filters"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the branch name"}}},"branches":{"type":"array","description":"List of branches that define different processing paths.\n\nEach branch has its own criteria and processing steps. Requests are\nevaluated against branch criteria in the order defined.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Branch name"},"inputFilter":{"type":"object","description":"Filter criteria to determine if this branch should be selected.\n\nUses Celigo's expression-based filter format.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"nextRouterId":{"type":"string","description":"Next router to chain to (or \"apiRouter\" for final routing)"},"pageProcessors":{"type":"array","description":"Processing steps to execute in this branch","items":{"type":"object","properties":{"type":{"type":"string","enum":["export","import"],"description":"Type of processor"},"_exportId":{"type":"string","format":"objectId","description":"Export resource reference (when type=\"export\")"},"_importId":{"type":"string","format":"objectId","description":"Import resource reference (when type=\"import\")"},"hooks":{"type":"object","description":"Custom scripts for processing"}}}}}}}},"required":["branches"]},"ResponseRouter":{"type":"object","description":"Configuration for routing to different response configurations.\n\nThe response router determines which response configuration to use based on\nthe processing results. This allows you to return different responses based\non different conditions or outcomes.\n\nMust have id=\"apiRouter\" to serve as the final routing step before returning\nto the caller.\n","properties":{"id":{"type":"string","description":"Identifier for the response router.\n\nMust be \"apiRouter\" to indicate this is the final router before\nreturning the API response.\n","enum":["apiRouter"]},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to determine which response to use.\n\n- **input_filters**: Use declarative filter expressions on each response\n- **script**: Use custom JavaScript to return the response id\n"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n\nThe script function should return the id of the response to use.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the response id.\n\nThe function receives the processing results and should return\na string matching one of the response ids.\n"}}}},"required":["id"]},"ApiResponse":{"type":"object","description":"Configuration for an API response in builder mode.\n\nDefines how to format and return data to the caller. Each API must have:\n- Exactly one 'success' response (for successful operations)\n- Exactly one 'fail' response (for errors)\n- Zero or more 'custom' responses (for specific scenarios)\n","properties":{"id":{"type":"string","description":"Unique identifier for this response within the API.\n\nUsed to route to this response from the response router.\n"},"name":{"type":"string","maxLength":200,"description":"Display name for the response.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of when this response is used.\n"},"type":{"type":"string","enum":["success","fail","custom"],"description":"Type of response.\n\n- **success**: Default response for successful operations (required, exactly one)\n- **fail**: Default response for errors (required, exactly one)\n- **custom**: Additional responses for specific scenarios (optional, multiple allowed)\n"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code to return.\n\nCommon codes:\n- 200: Success\n- 201: Created\n- 400: Bad Request\n- 404: Not Found\n- 500: Internal Server Error\n"},"headers":{"type":"array","description":"Response headers to include.\n\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"value":{"type":"string","maxLength":256,"description":"Header value (can include handlebars templates)"},"description":{"type":"string","maxLength":10240,"description":"Description of the header"}}}},"inputFilter":{"type":"object","description":"Optional filter to determine when this response should be used.\n\nApplied when routing to this response from the response router.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the response body structure.\n\nUsed for documentation and OpenAPI specification generation.\n","additionalProperties":true},"mockInput":{"type":"object","description":"Mock data to use when testing this response.\n\nProvides sample data that would come from processing logic.\nMaximum size: 1MB\n","additionalProperties":true},"mappings":{"type":"array","description":"Field mappings to transform data into the response format.\n\nMaps data from processing results to the response body structure.\n","items":{"type":"object","properties":{"generate":{"type":"string","description":"Target field path in the response"},"extract":{"type":"string","description":"Source field path from input data"},"hardcodedValue":{"description":"Static value to use"}}}},"lookups":{"type":"array","description":"Lookup tables for data enrichment or transformation.\n\nStatic key-value mappings to transform values during response generation.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the lookup"},"map":{"type":"object","description":"Key-value mapping object"},"default":{"type":"string","description":"Default value if key not found"},"allowFailures":{"type":"boolean","description":"Whether to continue if lookup fails"}}}},"hooks":{"type":"object","description":"Custom scripts to run during response processing.\n","properties":{"preMap":{"type":"object","description":"Script to run before applying mappings.\n\nCan modify the input data before it's mapped to the response.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}},"postMap":{"type":"object","description":"Script to run after applying mappings.\n\nCan modify the response data after mappings are applied.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}}}}},"required":["id","name","type"]},"Shipworks":{"type":"object","description":"ShipWorks integration configuration.\n\nShipWorks is a shipping management platform. This configuration stores\nauthentication credentials for ShipWorks-specific API integrations.\n","properties":{"username":{"type":"string","description":"ShipWorks username for authentication.\n"},"password":{"type":"string","description":"ShipWorks password for authentication.\n\nWhen retrieving, this will be masked as \"******\" if a password is set.\nWhen creating/updating, provide the actual password value.\n"}},"required":["username","password"]},"Response":{"type":"object","description":"Response schema for API operations.\n\nContains the complete API configuration including metadata, script/builder settings,\nand integration-specific configurations.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the API"},"name":{"type":"string","description":"Human-readable name for the API"},"description":{"type":"string","description":"Optional detailed description of the API"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration (builder or script)"},"version":{"type":"string","description":"Version identifier for the API endpoint"},"disabled":{"type":"boolean","description":"Whether the API is disabled"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was last modified"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"},"apim":{"$ref":"#/components/schemas/Apim"}}},"Apim":{"type":"array","description":"API Management (APIM) integration metadata.\n\nTracks the publication status of this API to external API management systems\nand portals. Used for generating and syncing OpenAPI specifications.\n","items":{"type":"object","properties":{"apiId":{"type":"string","description":"Unique identifier in the API management system.\n"},"flowId":{"type":"string","description":"Associated flow identifier in the API management system.\n"},"status":{"type":"string","enum":["oaspending","published"],"description":"Publication status.\n\n- **oaspending**: OpenAPI spec generation/update is pending\n- **published**: API is published to the management system\n"},"definitionVersion":{"type":"string","enum":["v4"],"description":"Version of the API definition format.\n\nCurrently only \"v4\" is supported.\n"}}}},"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/apis":{"post":{"summary":"Create an API","description":"Creates a new API configuration that exposes integration logic as a RESTful endpoint.\n\nYou can create either a builder-mode API (visual configuration) or a script-mode API\n(custom JavaScript function).\n","operationId":"createApi","tags":["APIs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"API 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"}}}}}}
```

## List month-to-date API invocation counts

> Returns one invocation-counter record per resource + method + relativeURI in the current month.\
> Counts API-style invocations across every resource type that exposes an HTTP-callable endpoint:\
> custom APIs (builder and script), individual exports/imports called via \`/invoke\`, virtual\
> imports, and APIM-fronted invocations.\
> \
> The endpoint aggregates — it does not return one record per individual call. Each entry rolls\
> up every invocation of that (resource, method, URI) triple in the current month. Counters reset\
> on the 1st of each month; there is no pagination and no historical-months filter on this path.\
> \
> AI guidance:\
> \- Use this when you need "what ran this month" for billing or capacity checks. For plan-level\
> &#x20; entitlement limits, pair with \`GET /v1/licenseEntitlementUsage\`.\
> \- \`ioInvocationCount\` bills against the Celigo subscription; \`apimInvocationCount\` is billed\
> &#x20; separately for external APIM passthrough. Sum both when computing total call volume.\
> \- To find the resource behind a row, read \`metadata.\_resourceId\` (present for exports/imports)\
> &#x20; or parse the resource id out of \`relativeURI\` (virtual imports embed the connection id).\
> \- When reporting against the paid entitlement, focus on entries that count toward billing.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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 `<resource>`\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 `<resource>`\n  resource.\"* Known rejections: `/v1/ediprofiles`, `/v1/environments`,\n  `/v1/iClients`, `/v1/lookupcaches`, `/v1/tags`.","schema":{"type":"string"}}},"schemas":{"ApisUsageResponse":{"type":"object","description":"Month-to-date invocation counters for every API endpoint that has been called in the account.\nReturned by `GET /v1/apis/usage`. Each entry in `usages[]` represents one resource + method +\nrelativeURI triple — the same export or import invoked via two different methods yields two\nentries. Counters are cumulative for the month named in `month` / `year` and reset on the 1st.","properties":{"usages":{"type":"array","description":"Per-endpoint invocation records. Empty array when the account hasn't invoked any API endpoints\nthis month. Includes entries for every resource that can be invoked as an API —\ncustom APIs, individual exports/imports (`/v1/exports/{id}/invoke`, `/v1/imports/{id}/invoke`),\nvirtual imports, and script APIs.","items":{"$ref":"#/components/schemas/ApisUsageEntry"}},"externalApimCount":{"type":"integer","description":"Account-wide count of invocations that arrived through an external API Management layer\n(APIM) in front of integrator.io for the current month. Aggregate counterpart to the\nper-endpoint `apimInvocationCount` values in `usages[]`. Absent on some responses when the\naccount has never been routed through an external APIM."}},"required":["usages"]},"ApisUsageEntry":{"type":"object","description":"One month's invocation record for a single API-callable endpoint. Keyed by the\nresource + HTTP method + relativeURI combination — the same export invoked via two HTTP methods\nproduces two separate entries.","properties":{"_id":{"type":"string","format":"objectId","description":"Unique id of this usage record (not the resource id — see `metadata._resourceId`)."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method the endpoint was called with."},"relativeURI":{"type":"string","description":"The endpoint path (relative to `https://api.integrator.io`) that was invoked. Common shapes:\n`/v1/exports/{_exportId}/invoke`, `/v1/imports/{_importId}/invoke`,\n`/v1/connections/{_connectionId}/import` for virtual imports,\n`/v1/apis/{_apiId}/request` for script-mode APIs, and\n`/apis/v1/<relativeURI>` for builder-mode APIs."},"metadata":{"type":"object","description":"Human-readable labeling of the resource behind this usage record.","properties":{"_resourceId":{"type":"string","format":"objectId","description":"Id of the underlying export, import, or API resource. Omitted for some resource types\n(e.g. connection-scoped virtual imports) where the URL itself fully identifies the target."},"name":{"type":"string","description":"Display name of the resource at the time of invocation."},"type":{"type":"string","enum":["export","import","virtualImport","script","apiBuilder"],"description":"Resource flavor. `virtualImport` is a connection-scoped import (connector-embedded).\n`script` is a script-mode API. `apiBuilder` is a builder-mode API."}},"required":["name","type"]},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Calendar month (1 = January) the counters cover."},"year":{"type":"integer","description":"Four-digit year the counters cover."},"ioInvocationCount":{"type":"integer","description":"Number of times the endpoint was invoked through integrator.io's own API front door. This is\nthe counter that bills against the subscription's API invocation entitlement."},"apimInvocationCount":{"type":"integer","description":"Number of times the endpoint was invoked through an external API Management layer (APIM) in\nfront of integrator.io. Billed separately from `ioInvocationCount`."},"createdAt":{"type":"string","format":"date-time","description":"When this monthly counter record was first created (the first invocation of the month)."}},"required":["_id","method","relativeURI","metadata","month","year","ioInvocationCount","apimInvocationCount"]}},"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/apis/usage":{"get":{"operationId":"listApisUsage","tags":["APIs"],"summary":"List month-to-date API invocation counts","description":"Returns one invocation-counter record per resource + method + relativeURI in the current month.\nCounts API-style invocations across every resource type that exposes an HTTP-callable endpoint:\ncustom APIs (builder and script), individual exports/imports called via `/invoke`, virtual\nimports, and APIM-fronted invocations.\n\nThe endpoint aggregates — it does not return one record per individual call. Each entry rolls\nup every invocation of that (resource, method, URI) triple in the current month. Counters reset\non the 1st of each month; there is no pagination and no historical-months filter on this path.\n\nAI guidance:\n- Use this when you need \"what ran this month\" for billing or capacity checks. For plan-level\n  entitlement limits, pair with `GET /v1/licenseEntitlementUsage`.\n- `ioInvocationCount` bills against the Celigo subscription; `apimInvocationCount` is billed\n  separately for external APIM passthrough. Sum both when computing total call volume.\n- To find the resource behind a row, read `metadata._resourceId` (present for exports/imports)\n  or parse the resource id out of `relativeURI` (virtual imports embed the connection id).\n- When reporting against the paid entitlement, focus on entries that count toward billing.","parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"}],"responses":{"200":{"description":"Usage breakdown for the current month. `usages[]` is empty when no endpoints have been invoked yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApisUsageResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Get an API

> Returns the complete configuration of a specific API.<br>

```json
{"openapi":"3.1.0","info":{"title":"APIs","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 API operations.\n\nContains the complete API configuration including metadata, script/builder settings,\nand integration-specific configurations.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the API"},"name":{"type":"string","description":"Human-readable name for the API"},"description":{"type":"string","description":"Optional detailed description of the API"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration (builder or script)"},"version":{"type":"string","description":"Version identifier for the API endpoint"},"disabled":{"type":"boolean","description":"Whether the API is disabled"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was last modified"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"},"apim":{"$ref":"#/components/schemas/Apim"}}},"Script":{"type":"object","description":"Script configuration for script-mode APIs.\n\nIn script mode, you provide a custom JavaScript function that receives the request\nobject and returns the response. This gives you complete control over the API behavior.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource containing the implementation.\n\nThe script must exist in your account and be accessible to the user.\n"},"function":{"type":"string","description":"Name of the function to invoke within the script.\n\nThis function receives the request object and must return a response object\nwith statusCode, headers, and body properties.\n"}},"required":["_scriptId","function"]},"Builder":{"type":"object","description":"Builder configuration for visual API construction.\n\nThe builder mode allows you to define your API using visual configuration:\n- Define the request structure (method, path, parameters)\n- Transform incoming requests\n- Route requests through processing logic\n- Map and transform responses\n","properties":{"request":{"$ref":"#/components/schemas/ApiRequest"},"routers":{"type":"array","description":"Optional routers for conditional processing logic.\n\nRouters allow you to direct requests to different processing branches\nbased on criteria. This enables complex business logic within the API.\n","items":{"$ref":"#/components/schemas/Router"}},"responseRouter":{"$ref":"#/components/schemas/ResponseRouter"},"responses":{"type":"array","description":"Response configurations defining how to format and return data.\n\nMust include exactly one 'success' response and one 'fail' response.\nAdditional custom responses can be added for specific scenarios.\n","items":{"$ref":"#/components/schemas/ApiResponse"}}},"required":["request"]},"ApiRequest":{"type":"object","description":"Configuration for the API request structure in builder mode.\n\nDefines how the API endpoint receives data:\n- HTTP method and URI path\n- Expected parameters (path, query, headers)\n- Request body schema\n- Optional request transformation logic\n","properties":{"name":{"type":"string","maxLength":200,"description":"Display name for the request configuration.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of what the request does.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9:_*\\/\\-\\.]*$","description":"URI path relative to the version.\n\nFull endpoint URL will be: `/{version}{relativeURI}`\nCan include path parameters using colon notation: `/customers/:id`\nFirst path segment must be alphanumeric, dash, or underscore only.\n"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method for the API endpoint.\n"},"headers":{"type":"array","description":"Expected request headers.\n\nDocuments headers that clients should send. Headers are optional by default.\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"description":{"type":"string","maxLength":10240,"description":"Description of the header's purpose"}}}},"pathParams":{"type":"array","description":"Path parameters defined in the relativeURI.\n\nDocuments the parameters that are part of the URL path (e.g., :id, :customerId).\nThese should match the parameters defined in the relativeURI.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"description":"Parameter name (without the colon prefix)"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"queryParams":{"type":"array","description":"Expected query string parameters.\n\nDocuments parameters that can be passed in the URL query string.\nQuery parameters are optional by default.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_\\-:\\/]*$","description":"Query parameter name"},"dataType":{"type":"string","enum":["string","number","boolean"],"description":"Expected data type of the parameter"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the expected request body structure.\n\nUsed for documentation and validation of the request payload.\nTypically used with POST, PUT, and PATCH methods.\n","additionalProperties":true},"mockRequest":{"type":"object","description":"Mock request data for testing the API.\n\nProvides sample data to test the API without making actual calls.\nCan include body, headers, pathParams, and queryParams.\n","properties":{"body":{"type":"object","description":"Sample request body"},"headers":{"type":"object","description":"Sample headers"},"pathParams":{"type":"object","description":"Sample path parameters"},"queryParams":{"type":"object","description":"Sample query parameters"}},"additionalProperties":false},"transform":{"type":"object","description":"Optional transformation to apply to the incoming request.\n\nTransforms the request data before it is processed by routers or responses.\nUseful for normalizing data or extracting specific fields.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to a script for custom transformation logic"},"function":{"type":"string","description":"Function name in the script to execute"}}}},"required":["relativeURI","method"]},"Router":{"type":"object","description":"Configuration for conditional routing within builder-mode APIs.\n\nRouters evaluate the request and route it to different processing branches.\nThis enables complex business logic and conditional processing within your API.\n\nNote: Unlike flows, APIs only support \"first_matching_branch\" routing.\n","properties":{"id":{"type":"string","description":"Unique identifier for this router within the API.\n\nUsed to reference this router from other routers and branches.\n"},"name":{"type":"string","description":"Human-readable name for the router.\n"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch"],"description":"Routing strategy for APIs.\n\nAPIs only support \"first_matching_branch\" which routes to the first\nbranch whose criteria match.\n","default":"first_matching_branch"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to evaluate routing criteria.\n\n- **input_filters**: Use declarative filter expressions\n- **script**: Use custom JavaScript for complex logic\n","default":"input_filters"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the branch name"}}},"branches":{"type":"array","description":"List of branches that define different processing paths.\n\nEach branch has its own criteria and processing steps. Requests are\nevaluated against branch criteria in the order defined.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Branch name"},"inputFilter":{"type":"object","description":"Filter criteria to determine if this branch should be selected.\n\nUses Celigo's expression-based filter format.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"nextRouterId":{"type":"string","description":"Next router to chain to (or \"apiRouter\" for final routing)"},"pageProcessors":{"type":"array","description":"Processing steps to execute in this branch","items":{"type":"object","properties":{"type":{"type":"string","enum":["export","import"],"description":"Type of processor"},"_exportId":{"type":"string","format":"objectId","description":"Export resource reference (when type=\"export\")"},"_importId":{"type":"string","format":"objectId","description":"Import resource reference (when type=\"import\")"},"hooks":{"type":"object","description":"Custom scripts for processing"}}}}}}}},"required":["branches"]},"ResponseRouter":{"type":"object","description":"Configuration for routing to different response configurations.\n\nThe response router determines which response configuration to use based on\nthe processing results. This allows you to return different responses based\non different conditions or outcomes.\n\nMust have id=\"apiRouter\" to serve as the final routing step before returning\nto the caller.\n","properties":{"id":{"type":"string","description":"Identifier for the response router.\n\nMust be \"apiRouter\" to indicate this is the final router before\nreturning the API response.\n","enum":["apiRouter"]},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to determine which response to use.\n\n- **input_filters**: Use declarative filter expressions on each response\n- **script**: Use custom JavaScript to return the response id\n"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n\nThe script function should return the id of the response to use.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the response id.\n\nThe function receives the processing results and should return\na string matching one of the response ids.\n"}}}},"required":["id"]},"ApiResponse":{"type":"object","description":"Configuration for an API response in builder mode.\n\nDefines how to format and return data to the caller. Each API must have:\n- Exactly one 'success' response (for successful operations)\n- Exactly one 'fail' response (for errors)\n- Zero or more 'custom' responses (for specific scenarios)\n","properties":{"id":{"type":"string","description":"Unique identifier for this response within the API.\n\nUsed to route to this response from the response router.\n"},"name":{"type":"string","maxLength":200,"description":"Display name for the response.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of when this response is used.\n"},"type":{"type":"string","enum":["success","fail","custom"],"description":"Type of response.\n\n- **success**: Default response for successful operations (required, exactly one)\n- **fail**: Default response for errors (required, exactly one)\n- **custom**: Additional responses for specific scenarios (optional, multiple allowed)\n"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code to return.\n\nCommon codes:\n- 200: Success\n- 201: Created\n- 400: Bad Request\n- 404: Not Found\n- 500: Internal Server Error\n"},"headers":{"type":"array","description":"Response headers to include.\n\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"value":{"type":"string","maxLength":256,"description":"Header value (can include handlebars templates)"},"description":{"type":"string","maxLength":10240,"description":"Description of the header"}}}},"inputFilter":{"type":"object","description":"Optional filter to determine when this response should be used.\n\nApplied when routing to this response from the response router.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the response body structure.\n\nUsed for documentation and OpenAPI specification generation.\n","additionalProperties":true},"mockInput":{"type":"object","description":"Mock data to use when testing this response.\n\nProvides sample data that would come from processing logic.\nMaximum size: 1MB\n","additionalProperties":true},"mappings":{"type":"array","description":"Field mappings to transform data into the response format.\n\nMaps data from processing results to the response body structure.\n","items":{"type":"object","properties":{"generate":{"type":"string","description":"Target field path in the response"},"extract":{"type":"string","description":"Source field path from input data"},"hardcodedValue":{"description":"Static value to use"}}}},"lookups":{"type":"array","description":"Lookup tables for data enrichment or transformation.\n\nStatic key-value mappings to transform values during response generation.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the lookup"},"map":{"type":"object","description":"Key-value mapping object"},"default":{"type":"string","description":"Default value if key not found"},"allowFailures":{"type":"boolean","description":"Whether to continue if lookup fails"}}}},"hooks":{"type":"object","description":"Custom scripts to run during response processing.\n","properties":{"preMap":{"type":"object","description":"Script to run before applying mappings.\n\nCan modify the input data before it's mapped to the response.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}},"postMap":{"type":"object","description":"Script to run after applying mappings.\n\nCan modify the response data after mappings are applied.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}}}}},"required":["id","name","type"]},"Shipworks":{"type":"object","description":"ShipWorks integration configuration.\n\nShipWorks is a shipping management platform. This configuration stores\nauthentication credentials for ShipWorks-specific API integrations.\n","properties":{"username":{"type":"string","description":"ShipWorks username for authentication.\n"},"password":{"type":"string","description":"ShipWorks password for authentication.\n\nWhen retrieving, this will be masked as \"******\" if a password is set.\nWhen creating/updating, provide the actual password value.\n"}},"required":["username","password"]},"Apim":{"type":"array","description":"API Management (APIM) integration metadata.\n\nTracks the publication status of this API to external API management systems\nand portals. Used for generating and syncing OpenAPI specifications.\n","items":{"type":"object","properties":{"apiId":{"type":"string","description":"Unique identifier in the API management system.\n"},"flowId":{"type":"string","description":"Associated flow identifier in the API management system.\n"},"status":{"type":"string","enum":["oaspending","published"],"description":"Publication status.\n\n- **oaspending**: OpenAPI spec generation/update is pending\n- **published**: API is published to the management system\n"},"definitionVersion":{"type":"string","enum":["v4"],"description":"Version of the API definition format.\n\nCurrently only \"v4\" is supported.\n"}}}},"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/apis/{_id}":{"get":{"summary":"Get an API","description":"Returns the complete configuration of a specific API.\n","operationId":"getApiById","tags":["APIs"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the API","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"API retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update an API

> Updates an existing API with the provided configuration.\
> This is used for major updates to an API's structure or behavior.<br>

```json
{"openapi":"3.1.0","info":{"title":"APIs","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 an API.\n\nAPIs can be configured in two modes:\n- **builder**: Visual configuration with request/response mapping and transformations\n- **script**: Custom JavaScript function for complete control\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the API.\n\nDisplayed in the UI and logs to help identify the API's purpose.\n"},"description":{"type":"string","description":"Optional detailed description of what the API does.\n\nUse this to document the API's purpose, expected inputs/outputs, and any special considerations.\n"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration.\n\n- **builder**: Use visual configuration with request/response mapping\n- **script**: Use custom JavaScript for complete control\n"},"version":{"type":"string","default":"v1","pattern":"^[a-zA-Z0-9\\-_\\.]+$","description":"Version identifier for the API endpoint.\n\nThis becomes part of the URL path: `/{version}/{relativeURI}`\nOnly alphanumeric characters, dashes, underscores, and dots are allowed.\n"},"disabled":{"type":"boolean","default":false,"description":"Whether the API is disabled.\n\nDisabled APIs cannot be invoked and will return a 404 error.\n"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"}},"required":["type"]},"Script":{"type":"object","description":"Script configuration for script-mode APIs.\n\nIn script mode, you provide a custom JavaScript function that receives the request\nobject and returns the response. This gives you complete control over the API behavior.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource containing the implementation.\n\nThe script must exist in your account and be accessible to the user.\n"},"function":{"type":"string","description":"Name of the function to invoke within the script.\n\nThis function receives the request object and must return a response object\nwith statusCode, headers, and body properties.\n"}},"required":["_scriptId","function"]},"Builder":{"type":"object","description":"Builder configuration for visual API construction.\n\nThe builder mode allows you to define your API using visual configuration:\n- Define the request structure (method, path, parameters)\n- Transform incoming requests\n- Route requests through processing logic\n- Map and transform responses\n","properties":{"request":{"$ref":"#/components/schemas/ApiRequest"},"routers":{"type":"array","description":"Optional routers for conditional processing logic.\n\nRouters allow you to direct requests to different processing branches\nbased on criteria. This enables complex business logic within the API.\n","items":{"$ref":"#/components/schemas/Router"}},"responseRouter":{"$ref":"#/components/schemas/ResponseRouter"},"responses":{"type":"array","description":"Response configurations defining how to format and return data.\n\nMust include exactly one 'success' response and one 'fail' response.\nAdditional custom responses can be added for specific scenarios.\n","items":{"$ref":"#/components/schemas/ApiResponse"}}},"required":["request"]},"ApiRequest":{"type":"object","description":"Configuration for the API request structure in builder mode.\n\nDefines how the API endpoint receives data:\n- HTTP method and URI path\n- Expected parameters (path, query, headers)\n- Request body schema\n- Optional request transformation logic\n","properties":{"name":{"type":"string","maxLength":200,"description":"Display name for the request configuration.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of what the request does.\n"},"relativeURI":{"type":"string","maxLength":131072,"pattern":"^\\/[a-zA-Z0-9:_*\\/\\-\\.]*$","description":"URI path relative to the version.\n\nFull endpoint URL will be: `/{version}{relativeURI}`\nCan include path parameters using colon notation: `/customers/:id`\nFirst path segment must be alphanumeric, dash, or underscore only.\n"},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"description":"HTTP method for the API endpoint.\n"},"headers":{"type":"array","description":"Expected request headers.\n\nDocuments headers that clients should send. Headers are optional by default.\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"description":{"type":"string","maxLength":10240,"description":"Description of the header's purpose"}}}},"pathParams":{"type":"array","description":"Path parameters defined in the relativeURI.\n\nDocuments the parameters that are part of the URL path (e.g., :id, :customerId).\nThese should match the parameters defined in the relativeURI.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"description":"Parameter name (without the colon prefix)"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"queryParams":{"type":"array","description":"Expected query string parameters.\n\nDocuments parameters that can be passed in the URL query string.\nQuery parameters are optional by default.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_\\-:\\/]*$","description":"Query parameter name"},"dataType":{"type":"string","enum":["string","number","boolean"],"description":"Expected data type of the parameter"},"description":{"type":"string","maxLength":10240,"description":"Description of the parameter"}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the expected request body structure.\n\nUsed for documentation and validation of the request payload.\nTypically used with POST, PUT, and PATCH methods.\n","additionalProperties":true},"mockRequest":{"type":"object","description":"Mock request data for testing the API.\n\nProvides sample data to test the API without making actual calls.\nCan include body, headers, pathParams, and queryParams.\n","properties":{"body":{"type":"object","description":"Sample request body"},"headers":{"type":"object","description":"Sample headers"},"pathParams":{"type":"object","description":"Sample path parameters"},"queryParams":{"type":"object","description":"Sample query parameters"}},"additionalProperties":false},"transform":{"type":"object","description":"Optional transformation to apply to the incoming request.\n\nTransforms the request data before it is processed by routers or responses.\nUseful for normalizing data or extracting specific fields.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to a script for custom transformation logic"},"function":{"type":"string","description":"Function name in the script to execute"}}}},"required":["relativeURI","method"]},"Router":{"type":"object","description":"Configuration for conditional routing within builder-mode APIs.\n\nRouters evaluate the request and route it to different processing branches.\nThis enables complex business logic and conditional processing within your API.\n\nNote: Unlike flows, APIs only support \"first_matching_branch\" routing.\n","properties":{"id":{"type":"string","description":"Unique identifier for this router within the API.\n\nUsed to reference this router from other routers and branches.\n"},"name":{"type":"string","description":"Human-readable name for the router.\n"},"routeRecordsTo":{"type":"string","enum":["first_matching_branch"],"description":"Routing strategy for APIs.\n\nAPIs only support \"first_matching_branch\" which routes to the first\nbranch whose criteria match.\n","default":"first_matching_branch"},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to evaluate routing criteria.\n\n- **input_filters**: Use declarative filter expressions\n- **script**: Use custom JavaScript for complex logic\n","default":"input_filters"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the branch name"}}},"branches":{"type":"array","description":"List of branches that define different processing paths.\n\nEach branch has its own criteria and processing steps. Requests are\nevaluated against branch criteria in the order defined.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Branch name"},"inputFilter":{"type":"object","description":"Filter criteria to determine if this branch should be selected.\n\nUses Celigo's expression-based filter format.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"nextRouterId":{"type":"string","description":"Next router to chain to (or \"apiRouter\" for final routing)"},"pageProcessors":{"type":"array","description":"Processing steps to execute in this branch","items":{"type":"object","properties":{"type":{"type":"string","enum":["export","import"],"description":"Type of processor"},"_exportId":{"type":"string","format":"objectId","description":"Export resource reference (when type=\"export\")"},"_importId":{"type":"string","format":"objectId","description":"Import resource reference (when type=\"import\")"},"hooks":{"type":"object","description":"Custom scripts for processing"}}}}}}}},"required":["branches"]},"ResponseRouter":{"type":"object","description":"Configuration for routing to different response configurations.\n\nThe response router determines which response configuration to use based on\nthe processing results. This allows you to return different responses based\non different conditions or outcomes.\n\nMust have id=\"apiRouter\" to serve as the final routing step before returning\nto the caller.\n","properties":{"id":{"type":"string","description":"Identifier for the response router.\n\nMust be \"apiRouter\" to indicate this is the final router before\nreturning the API response.\n","enum":["apiRouter"]},"routeRecordsUsing":{"type":"string","enum":["input_filters","script"],"description":"Method used to determine which response to use.\n\n- **input_filters**: Use declarative filter expressions on each response\n- **script**: Use custom JavaScript to return the response id\n"},"script":{"type":"object","description":"Script configuration when routeRecordsUsing=\"script\".\n\nThe script function should return the id of the response to use.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name that returns the response id.\n\nThe function receives the processing results and should return\na string matching one of the response ids.\n"}}}},"required":["id"]},"ApiResponse":{"type":"object","description":"Configuration for an API response in builder mode.\n\nDefines how to format and return data to the caller. Each API must have:\n- Exactly one 'success' response (for successful operations)\n- Exactly one 'fail' response (for errors)\n- Zero or more 'custom' responses (for specific scenarios)\n","properties":{"id":{"type":"string","description":"Unique identifier for this response within the API.\n\nUsed to route to this response from the response router.\n"},"name":{"type":"string","maxLength":200,"description":"Display name for the response.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional description of when this response is used.\n"},"type":{"type":"string","enum":["success","fail","custom"],"description":"Type of response.\n\n- **success**: Default response for successful operations (required, exactly one)\n- **fail**: Default response for errors (required, exactly one)\n- **custom**: Additional responses for specific scenarios (optional, multiple allowed)\n"},"statusCode":{"type":"integer","minimum":100,"maximum":599,"description":"HTTP status code to return.\n\nCommon codes:\n- 200: Success\n- 201: Created\n- 400: Bad Request\n- 404: Not Found\n- 500: Internal Server Error\n"},"headers":{"type":"array","description":"Response headers to include.\n\nOnly alphanumeric characters, hyphens, and underscores are allowed in header names.\n","items":{"type":"object","properties":{"key":{"type":"string","maxLength":256,"pattern":"^[a-zA-Z0-9_-]+$","description":"Header name"},"value":{"type":"string","maxLength":256,"description":"Header value (can include handlebars templates)"},"description":{"type":"string","maxLength":10240,"description":"Description of the header"}}}},"inputFilter":{"type":"object","description":"Optional filter to determine when this response should be used.\n\nApplied when routing to this response from the response router.\n","properties":{"version":{"type":"string","enum":["1"],"description":"Filter version"},"rules":{"type":"array","description":"Filter rules in Celigo expression-based filter format.\n\nArray-based DSL where the first element is an operator (e.g., \"equals\", \"and\", \"or\"),\nfollowed by operands which can be nested expressions.\n","items":{}}}},"bodySchema":{"type":"object","description":"JSON Schema describing the response body structure.\n\nUsed for documentation and OpenAPI specification generation.\n","additionalProperties":true},"mockInput":{"type":"object","description":"Mock data to use when testing this response.\n\nProvides sample data that would come from processing logic.\nMaximum size: 1MB\n","additionalProperties":true},"mappings":{"type":"array","description":"Field mappings to transform data into the response format.\n\nMaps data from processing results to the response body structure.\n","items":{"type":"object","properties":{"generate":{"type":"string","description":"Target field path in the response"},"extract":{"type":"string","description":"Source field path from input data"},"hardcodedValue":{"description":"Static value to use"}}}},"lookups":{"type":"array","description":"Lookup tables for data enrichment or transformation.\n\nStatic key-value mappings to transform values during response generation.\n","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the lookup"},"map":{"type":"object","description":"Key-value mapping object"},"default":{"type":"string","description":"Default value if key not found"},"allowFailures":{"type":"boolean","description":"Whether to continue if lookup fails"}}}},"hooks":{"type":"object","description":"Custom scripts to run during response processing.\n","properties":{"preMap":{"type":"object","description":"Script to run before applying mappings.\n\nCan modify the input data before it's mapped to the response.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}},"postMap":{"type":"object","description":"Script to run after applying mappings.\n\nCan modify the response data after mappings are applied.\n","properties":{"_scriptId":{"type":"string","format":"objectId","description":"Reference to the script resource"},"function":{"type":"string","description":"Function name to execute"}}}}}},"required":["id","name","type"]},"Shipworks":{"type":"object","description":"ShipWorks integration configuration.\n\nShipWorks is a shipping management platform. This configuration stores\nauthentication credentials for ShipWorks-specific API integrations.\n","properties":{"username":{"type":"string","description":"ShipWorks username for authentication.\n"},"password":{"type":"string","description":"ShipWorks password for authentication.\n\nWhen retrieving, this will be masked as \"******\" if a password is set.\nWhen creating/updating, provide the actual password value.\n"}},"required":["username","password"]},"Response":{"type":"object","description":"Response schema for API operations.\n\nContains the complete API configuration including metadata, script/builder settings,\nand integration-specific configurations.\n","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the API"},"name":{"type":"string","description":"Human-readable name for the API"},"description":{"type":"string","description":"Optional detailed description of the API"},"type":{"type":"string","enum":["builder","script"],"description":"Type of API configuration (builder or script)"},"version":{"type":"string","description":"Version identifier for the API endpoint"},"disabled":{"type":"boolean","description":"Whether the API is disabled"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the API was last modified"},"script":{"$ref":"#/components/schemas/Script"},"builder":{"$ref":"#/components/schemas/Builder"},"shipworks":{"$ref":"#/components/schemas/Shipworks"},"apim":{"$ref":"#/components/schemas/Apim"}}},"Apim":{"type":"array","description":"API Management (APIM) integration metadata.\n\nTracks the publication status of this API to external API management systems\nand portals. Used for generating and syncing OpenAPI specifications.\n","items":{"type":"object","properties":{"apiId":{"type":"string","description":"Unique identifier in the API management system.\n"},"flowId":{"type":"string","description":"Associated flow identifier in the API management system.\n"},"status":{"type":"string","enum":["oaspending","published"],"description":"Publication status.\n\n- **oaspending**: OpenAPI spec generation/update is pending\n- **published**: API is published to the management system\n"},"definitionVersion":{"type":"string","enum":["v4"],"description":"Version of the API definition format.\n\nCurrently only \"v4\" is supported.\n"}}}},"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/apis/{_id}":{"put":{"summary":"Update an API","description":"Updates an existing API with the provided configuration.\nThis is used for major updates to an API's structure or behavior.\n","operationId":"updateApi","tags":["APIs"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the API","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"API updated successfully","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 an API

> Deletes an API. The API is soft-deleted and retained in the recycle bin for\
> 30 days before permanent removal. The endpoint will no longer be accessible\
> for invocation.<br>

```json
{"openapi":"3.1.0","info":{"title":"APIs","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/apis/{_id}":{"delete":{"summary":"Delete an API","description":"Deletes an API. The API is soft-deleted and retained in the recycle bin for\n30 days before permanent removal. The endpoint will no longer be accessible\nfor invocation.\n","operationId":"deleteApi","tags":["APIs"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the API","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"API deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Patch an API

> Partially updates an API using a JSON Patch document (RFC 6902).\
> Only the \`replace\` operation is supported, and only on the following\
> whitelisted paths:\
> \
> \| Path | Description |\
> \|------|-------------|\
> \| \`/name\` | API display name |\
> \| \`/description\` | API description |\
> \| \`/disabled\` | Enable or disable the API (boolean) |\
> \
> All other paths are rejected with \`422\`.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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":{"JsonPatchRequest":{"type":"array","description":"A JSON Patch document (RFC 6902). Send an array of patch\noperations. Only the `replace` operation is supported, and only\non whitelisted fields — all other paths are rejected with 422.","minItems":1,"items":{"$ref":"#/components/schemas/JsonPatchOperation"}},"JsonPatchOperation":{"type":"object","description":"A single JSON Patch operation (RFC 6902).","required":["op","path"],"properties":{"op":{"type":"string","enum":["replace"],"description":"The operation to perform. Only `replace` is supported."},"path":{"type":"string","description":"JSON Pointer (RFC 6901) to the field to patch. Only\nwhitelisted paths are accepted — unlisted paths return\n`422` with `\"<path> is not a whitelisted property\"`."},"value":{"description":"The new value to set at the given path."}}},"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"}}}},"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/apis/{_id}":{"patch":{"summary":"Patch an API","description":"Partially updates an API using a JSON Patch document (RFC 6902).\nOnly the `replace` operation is supported, and only on the following\nwhitelisted paths:\n\n| Path | Description |\n|------|-------------|\n| `/name` | API display name |\n| `/description` | API description |\n| `/disabled` | Enable or disable the API (boolean) |\n\nAll other paths are rejected with `422`.","operationId":"patchApi","tags":["APIs"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the API","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonPatchRequest"}}}},"responses":{"204":{"description":"API patched successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Convert a JSON object to JSON Schema

> Accepts a sample JSON object and returns its inferred JSON Schema definition.\
> Useful for bootstrapping request/response schemas in builder-mode APIs from\
> real payload samples.\
> \
> The input must be a non-empty JSON object (not an array or primitive). The\
> returned schema uses \`type: "object"\` with \`properties\` derived from the\
> sample's keys and value types.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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/apis/schema":{"put":{"operationId":"convertJsonToSchema","tags":["APIs"],"summary":"Convert a JSON object to JSON Schema","description":"Accepts a sample JSON object and returns its inferred JSON Schema definition.\nUseful for bootstrapping request/response schemas in builder-mode APIs from\nreal payload samples.\n\nThe input must be a non-empty JSON object (not an array or primitive). The\nreturned schema uses `type: \"object\"` with `properties` derived from the\nsample's keys and value types.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Any sample JSON object to convert into JSON Schema."}}}},"responses":{"200":{"description":"JSON Schema generated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"properties":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}},"400":{"description":"The request body is not a valid JSON object (e.g. array, string, number).","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"The request body is an empty object (`{}`).","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}}}}
```

## Update the grouping for one or more APIs

> Assigns or removes an API grouping for the specified API resources. Pass an\
> \`\_apiGroupingId\` to assign the APIs to that group, or pass \`null\` to unset\
> the current grouping.\
> \
> API IDs that do not exist are silently accepted — no error is returned for\
> nonexistent references.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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/apis/updateApiGrouping":{"put":{"operationId":"updateApiGrouping","tags":["APIs"],"summary":"Update the grouping for one or more APIs","description":"Assigns or removes an API grouping for the specified API resources. Pass an\n`_apiGroupingId` to assign the APIs to that group, or pass `null` to unset\nthe current grouping.\n\nAPI IDs that do not exist are silently accepted — no error is returned for\nnonexistent references.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["_apiIds"],"properties":{"_apiIds":{"type":"array","items":{"type":"string"},"description":"List of API resource IDs to update."},"_apiGroupingId":{"type":["string","null"],"description":"The grouping ID to assign. Pass `null` or omit to remove the\ncurrent grouping from the specified APIs."}}}}}},"responses":{"204":{"description":"API grouping updated successfully (no body returned)."},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## List recent request/response logs for an API

> Returns the recent invocation traces captured for the named API. Each entry is a decoded\
> request/response pair — masked for credentials — that the runtime stored when the API was\
> called via its public endpoint. Use this to audit what the API has handled and to triage\
> errors without re-invoking the API.\
> \
> Traces are \*\*file-backed\*\*: a missing entry on the detail endpoint returns 404\
> (\`file\_not\_found\`). Retention and capture scope are controlled server-side; an empty\
> \`requests\[]\` simply means nothing is currently stored for this API. Two invocation sources do\
> \*\*not\*\* populate this log:\
> \- Test-runs via \`POST /v1/apis/{\_id}/test/run\` never surface here.\
> \- Script-mode API invocations via \`POST /v1/apis/{\_id}/request\` also do not surface here\
> &#x20; despite counting toward \`/v1/apis/usage\`. Only \*\*builder-mode\*\* invocations against the\
> &#x20; public endpoint (\`<https://api.integrator.io/apis/{version}{relativeURI}\\`>) populate logs.\
> \
> List entries are \*\*summaries\*\* (\`key\`, \`time\`, \`method\`, \`statusCode\`) — to see the decoded\
> request/response payload, follow up with \`GET /v1/apis/{\_id}/logs/{key}\`.\
> \
> AI guidance:\
> \- Use the list to locate the invocation you want (filter client-side on \`statusCode\` or \`time\`),\
> &#x20; then fetch the full envelope by \`key\`. The list does not carry headers or bodies.\
> \- \`statusCode\` is returned as a \*\*string\*\* in list entries but as an integer on the detail\
> &#x20; endpoint — handle both if you aggregate.\
> \- For per-step debug of the exports/imports inside an API pipeline, use\
> &#x20; \`GET /v1/apis/{\_id}/{\_stepId}/requests\` instead (requires \`debugUntil\` on the step).\
> \- Credential values are masked as \`\*\*\*\*\*\*\*\*\` before storage — the originals are not recoverable.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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":{"ApiLogsResponse":{"type":"object","description":"Request log envelope returned by `GET /v1/apis/{_id}/logs`. Contains the recent API invocation\ntraces for the API identified by `_id`. The `requests[]` array is empty when no invocations\nhave been logged — either the API has never been called, or debug capture is off, or the\nretention window has elapsed. Each entry is a full decoded request/response pair.","properties":{"requests":{"type":"array","description":"Invocation summaries, newest first. Each entry has just `{key, time, method, statusCode}`;\nthe decoded request/response payload lives behind `GET /v1/apis/{_id}/logs/{key}`.","items":{"$ref":"#/components/schemas/ApiLogEntry"}}},"required":["requests"]},"ApiLogEntry":{"type":"object","description":"Summary row returned in the `GET /v1/apis/{_id}/logs` listing. Carries just enough to identify\neach invocation (when it ran, how it ended) so the caller can pick which ones to inspect in\nfull via `GET /v1/apis/{_id}/logs/{key}`. Full request/response payloads are **not** in the\nlist — only in the detail fetch.","properties":{"key":{"type":"string","description":"Opaque log key. Pass to `GET /v1/apis/{_id}/logs/{key}` to retrieve the full decoded\ntransaction. Structure is `<seq>-<id>-<status>-<method>` (e.g.\n`5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST`). The embedded `<id>` also\nappears as `id` on the detail response."},"time":{"type":"integer","format":"int64","description":"Epoch milliseconds when the invocation was handled."},"method":{"type":"string","description":"HTTP method of the inbound request (`GET`, `POST`, ...)."},"statusCode":{"type":"string","description":"HTTP status code the API returned to the caller, as a **string** (e.g. `\"200\"`). Note: on\nthe detail endpoint this same value is exposed as an integer under `response.statusCode` —\nthe list surfaces it as a string."}},"required":["key","time","method","statusCode"]}},"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/apis/{_id}/logs":{"get":{"operationId":"listApiLogs","tags":["APIs"],"summary":"List recent request/response logs for an API","description":"Returns the recent invocation traces captured for the named API. Each entry is a decoded\nrequest/response pair — masked for credentials — that the runtime stored when the API was\ncalled via its public endpoint. Use this to audit what the API has handled and to triage\nerrors without re-invoking the API.\n\nTraces are **file-backed**: a missing entry on the detail endpoint returns 404\n(`file_not_found`). Retention and capture scope are controlled server-side; an empty\n`requests[]` simply means nothing is currently stored for this API. Two invocation sources do\n**not** populate this log:\n- Test-runs via `POST /v1/apis/{_id}/test/run` never surface here.\n- Script-mode API invocations via `POST /v1/apis/{_id}/request` also do not surface here\n  despite counting toward `/v1/apis/usage`. Only **builder-mode** invocations against the\n  public endpoint (`https://api.integrator.io/apis/{version}{relativeURI}`) populate logs.\n\nList entries are **summaries** (`key`, `time`, `method`, `statusCode`) — to see the decoded\nrequest/response payload, follow up with `GET /v1/apis/{_id}/logs/{key}`.\n\nAI guidance:\n- Use the list to locate the invocation you want (filter client-side on `statusCode` or `time`),\n  then fetch the full envelope by `key`. The list does not carry headers or bodies.\n- `statusCode` is returned as a **string** in list entries but as an integer on the detail\n  endpoint — handle both if you aggregate.\n- For per-step debug of the exports/imports inside an API pipeline, use\n  `GET /v1/apis/{_id}/{_stepId}/requests` instead (requires `debugUntil` on the step).\n- Credential values are masked as `********` before storage — the originals are not recoverable.","parameters":[{"name":"_id","in":"path","required":true,"description":"The API id.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Trace envelope. `requests[]` is empty when no invocations are currently stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiLogsResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"API id does not exist (`invalid_ref` / \"Api not found.\")."}}}}}}
```

## Get one request/response log entry by key

> Returns the full decoded request/response envelope for one API invocation, looked up by the\
> opaque \`key\` values surfaced in \`GET /v1/apis/{\_id}/logs\`. Matches the exact entry whose key is\
> provided — there is no partial-match or range query on this endpoint.\
> \
> Unlike the parent list (which only carries \`{key, time, method, statusCode}\`), this endpoint\
> returns the complete payload: request method/url/headers/body/queryParams/clientAddress,\
> response status/headers/body/responseTime, and (for builder-mode APIs) the\
> \`inputToResponseBubble\` snapshot of what the response-mapper saw. Sensitive header values\
> (\`authorization\`, OAuth bearer tokens) are masked as \`\*\*\*\*\*\*\*\*\` before storage.\
> \
> AI guidance:\
> \- Use this to reproduce a caller's request offline (copy \`request.method\`, \`request.url\`,\
> &#x20; \`request.headers\`, \`request.body\` — substituting real credentials for the masked values).\
> \- For builder APIs where the mapper didn't produce the expected output, inspect\
> &#x20; \`inputToResponseBubble.sourceRecord\` to see what the response stage actually received.\
> \- \`response.statusCode\` is an \*\*integer\*\* here but the sibling list endpoint surfaces the same\
> &#x20; value as a string — handle both shapes if you aggregate across both calls.\
> \- 404 \`file\_not\_found\` signals the key has expired from retention, was purged, or was never\
> &#x20; captured — it's not an auth failure, so do not retry on 404.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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":{"ApiLogDetail":{"type":"object","description":"Full decoded request/response envelope for one API invocation, returned by\n`GET /v1/apis/{_id}/logs/{key}`. Sensitive header values (`authorization`, OAuth bearer tokens,\nand similar) are masked with `********` before storage — the originals are not recoverable.\nThe `inputToResponseBubble` block reveals the Celigo-internal state handed to the\nresponse-mapping stage; it's absent for script-mode APIs and pre-mapping failures.","properties":{"time":{"type":"integer","format":"int64","description":"Epoch milliseconds when the invocation was handled."},"request":{"type":"object","description":"The inbound HTTP request the API received, as decoded by the runtime.","properties":{"method":{"type":"string","description":"HTTP method of the inbound request."},"url":{"type":"string","description":"The path the caller hit, relative to `https://api.integrator.io`. Includes the API\n`{version}` and the API's configured `relativeURI` (e.g. `/apis/v1/hubspot`).\nQuery-string credentials are masked before storage."},"httpVersion":{"type":"string","description":"HTTP protocol version the caller negotiated (e.g. `1.1`, `2`)."},"headers":{"type":"object","description":"Inbound headers. The `authorization` header (and other credential headers) are masked.","additionalProperties":{"type":"string"}},"queryParams":{"type":"object","description":"Parsed query-string parameters. Empty object when none were sent.","additionalProperties":true},"body":{"type":"string","description":"Request body as received, verbatim string (JSON payloads arrive already serialized —\nparse with `JSON.parse` when you need structured data). Empty string for bodyless\nmethods."},"clientAddress":{"type":"string","description":"IP the request arrived from, as the Celigo edge saw it. IPv6 format; may be a\nprivate/loopback address (e.g. `::ffff:127.0.0.6`) when routed through an internal\nproxy rather than the public internet."},"size":{"type":"integer","description":"Byte size the runtime recorded for the request. Often `0` — this field is not consistently populated."}}},"response":{"type":"object","description":"The outbound HTTP response the API produced.","properties":{"statusCode":{"type":"integer","description":"HTTP status code returned to the caller, as an **integer** here. Note the list endpoint\n(`GET /v1/apis/{_id}/logs`) exposes the same value as a string."},"statusMessage":{"type":"string","description":"HTTP status reason phrase (`OK`, `Bad Request`, ...)."},"headers":{"type":"object","description":"Response headers sent to the caller.","additionalProperties":{"type":"string"}},"body":{"type":"string","description":"Response body as sent. String form; parse as JSON/XML per the `content-type` header."},"size":{"type":"integer","description":"Byte size of the serialized response body."},"responseTime":{"type":"integer","description":"Total time in milliseconds from request arrival to response flush."}}},"inputToResponseBubble":{"type":"object","description":"Builder-mode APIs only. Snapshot of the state handed to the response-mapping stage — the\nparsed input records plus any execution/configuration errors collected along the pipeline.\nUse this to debug response-mapping issues (\"what did the mapper actually see?\"). Absent on\nscript-mode APIs.","properties":{"sourceRecord":{"description":"Array of records (or single-record object) that the response-mapper was given as input."},"executionErrors":{"type":"array","description":"Runtime errors raised during processing (e.g. script exceptions, lookup failures).","items":{"type":"object","additionalProperties":true}},"configurationErrors":{"type":"array","description":"Configuration errors detected before execution (e.g. missing required mapping fields).","items":{"type":"object","additionalProperties":true}}}},"key":{"type":"string","description":"Echoes the `key` path parameter. Same structure as in the list (`<seq>-<id>-<status>-<method>`)."},"id":{"type":"string","description":"Shorter internal id for this log record. Appears embedded in the `key` string as the second\nsegment. Not independently useful to the caller, but handy for correlating with audit or\nmonitoring logs that reference only the short id."}},"required":["time","request","response","key","id"]}},"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/apis/{_id}/logs/{key}":{"get":{"operationId":"getApiLogByKey","tags":["APIs"],"summary":"Get one request/response log entry by key","description":"Returns the full decoded request/response envelope for one API invocation, looked up by the\nopaque `key` values surfaced in `GET /v1/apis/{_id}/logs`. Matches the exact entry whose key is\nprovided — there is no partial-match or range query on this endpoint.\n\nUnlike the parent list (which only carries `{key, time, method, statusCode}`), this endpoint\nreturns the complete payload: request method/url/headers/body/queryParams/clientAddress,\nresponse status/headers/body/responseTime, and (for builder-mode APIs) the\n`inputToResponseBubble` snapshot of what the response-mapper saw. Sensitive header values\n(`authorization`, OAuth bearer tokens) are masked as `********` before storage.\n\nAI guidance:\n- Use this to reproduce a caller's request offline (copy `request.method`, `request.url`,\n  `request.headers`, `request.body` — substituting real credentials for the masked values).\n- For builder APIs where the mapper didn't produce the expected output, inspect\n  `inputToResponseBubble.sourceRecord` to see what the response stage actually received.\n- `response.statusCode` is an **integer** here but the sibling list endpoint surfaces the same\n  value as a string — handle both shapes if you aggregate across both calls.\n- 404 `file_not_found` signals the key has expired from retention, was purged, or was never\n  captured — it's not an auth failure, so do not retry on 404.","parameters":[{"name":"_id","in":"path","required":true,"description":"The API id.","schema":{"type":"string","format":"objectId"}},{"name":"key","in":"path","required":true,"description":"Opaque log key from the parent `GET /v1/apis/{_id}/logs` listing. Encodes status + method\n(e.g. `…-200-POST`) — use the `key` exactly as returned; do not construct one manually.","schema":{"type":"string"}}],"responses":{"200":{"description":"The decoded request/response envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiLogDetail"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"description":"Either the API id doesn't exist (`invalid_ref` / \"Api not found.\") or the key isn't in\nretention (`file_not_found` / \"We are unable to find the file for the given fileName.\")."}}}}}}
```

## List dependencies of an API

> 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.\
> &#x20; This is also returned for a well-formatted but nonexistent id.

```json
{"openapi":"3.1.0","info":{"title":"APIs","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/apis/{_id}/dependencies":{"get":{"operationId":"listApiDependencies","tags":["APIs"],"summary":"List dependencies of an API","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/apis.md?ask=<question>
```

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.