# Lookup Caches

## List lookup caches

> Returns a list of all lookup caches configured in the account.\
> If no lookup caches exist, a 204 response with no body will be returned.\
> \
> Requires a valid Lookup Cache license.<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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 lookup cache operations.\n\nContains the cache configuration, metadata, and current size information.\n","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the lookup cache"},"_userId":{"type":"string","format":"objectId","description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the lookup cache"},"description":{"type":"string","description":"Description of the lookup cache's purpose"},"includeDataInTemplatesAndCloning":{"type":"boolean","description":"Whether cached data is included in templates and cloning"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this lookup cache belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this lookup cache is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this lookup cache was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the cache's origin"},"externalId":{"type":"string","description":"External identifier for this lookup cache"},"size":{"type":"number","minimum":0,"description":"Current size of the lookup cache in bytes.\n\nMaximum allowed size is 50 MB per cache. The per-environment\naggregate limit across all caches is 1 GB.\n"},"sizeInMB":{"type":"string","description":"Human-readable representation of the cache size, rounded up to\nthe nearest 5 MB increment. Returns \"0 MB\" for empty caches,\n\"<N MB\" for caches under 50 MB, and \"50 MB\" for caches at or\nover the limit.\n"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was soft-deleted.\n\nOnly present for deleted caches. The cache will be permanently\nremoved 30 days after this timestamp.\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/lookupcaches":{"get":{"summary":"List lookup caches","description":"Returns a list of all lookup caches configured in the account.\nIf no lookup caches exist, a 204 response with no body will be returned.\n\nRequires a valid Lookup Cache license.\n","operationId":"listLookupCaches","tags":["Lookup Caches"],"responses":{"200":{"description":"Successfully retrieved list of lookup caches","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 lookup caches exist in the account"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create a lookup cache

> Creates a new empty lookup cache.\
> \
> The cache is created with size 0 and can be populated through\
> the data management endpoints. The per-environment aggregate size\
> limit is validated on creation (1 GB for new caches).<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a lookup cache.\n\nLookup caches are in-memory key-value stores used during integration\nprocessing for fast lookups, deduplication, and cross-reference resolution.\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the lookup cache.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the lookup cache's purpose.\n"},"includeDataInTemplatesAndCloning":{"type":"boolean","default":false,"description":"Whether to include the cached data when this lookup cache is used\nin templates or cloned to another environment.\n\nWhen false (default), only the cache metadata is included — the actual\nkey-value data is not transferred. Set to true if the cached data is\npart of the integration's configuration (e.g., static reference tables).\n"},"externalId":{"type":"string","description":"External identifier for correlating this lookup cache with an external system.\n\nCan be used to look up caches by external reference via the `externalId`\nquery parameter on the list endpoint.\n"}}},"Response":{"type":"object","description":"Response schema for lookup cache operations.\n\nContains the cache configuration, metadata, and current size information.\n","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the lookup cache"},"_userId":{"type":"string","format":"objectId","description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the lookup cache"},"description":{"type":"string","description":"Description of the lookup cache's purpose"},"includeDataInTemplatesAndCloning":{"type":"boolean","description":"Whether cached data is included in templates and cloning"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this lookup cache belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this lookup cache is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this lookup cache was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the cache's origin"},"externalId":{"type":"string","description":"External identifier for this lookup cache"},"size":{"type":"number","minimum":0,"description":"Current size of the lookup cache in bytes.\n\nMaximum allowed size is 50 MB per cache. The per-environment\naggregate limit across all caches is 1 GB.\n"},"sizeInMB":{"type":"string","description":"Human-readable representation of the cache size, rounded up to\nthe nearest 5 MB increment. Returns \"0 MB\" for empty caches,\n\"<N MB\" for caches under 50 MB, and \"50 MB\" for caches at or\nover the limit.\n"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was soft-deleted.\n\nOnly present for deleted caches. The cache will be permanently\nremoved 30 days after this timestamp.\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"]}}}}}},"paths":{"/v1/lookupcaches":{"post":{"summary":"Create a lookup cache","description":"Creates a new empty lookup cache.\n\nThe cache is created with size 0 and can be populated through\nthe data management endpoints. The per-environment aggregate size\nlimit is validated on creation (1 GB for new caches).\n","operationId":"createLookupCache","tags":["Lookup Caches"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"Lookup cache created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Get a lookup cache

> Returns the configuration and metadata of a specific lookup cache,\
> including its current size.\
> \
> Requires a valid Lookup Cache license.<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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 lookup cache operations.\n\nContains the cache configuration, metadata, and current size information.\n","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the lookup cache"},"_userId":{"type":"string","format":"objectId","description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the lookup cache"},"description":{"type":"string","description":"Description of the lookup cache's purpose"},"includeDataInTemplatesAndCloning":{"type":"boolean","description":"Whether cached data is included in templates and cloning"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this lookup cache belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this lookup cache is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this lookup cache was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the cache's origin"},"externalId":{"type":"string","description":"External identifier for this lookup cache"},"size":{"type":"number","minimum":0,"description":"Current size of the lookup cache in bytes.\n\nMaximum allowed size is 50 MB per cache. The per-environment\naggregate limit across all caches is 1 GB.\n"},"sizeInMB":{"type":"string","description":"Human-readable representation of the cache size, rounded up to\nthe nearest 5 MB increment. Returns \"0 MB\" for empty caches,\n\"<N MB\" for caches under 50 MB, and \"50 MB\" for caches at or\nover the limit.\n"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was soft-deleted.\n\nOnly present for deleted caches. The cache will be permanently\nremoved 30 days after this timestamp.\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/lookupcaches/{_id}":{"get":{"summary":"Get a lookup cache","description":"Returns the configuration and metadata of a specific lookup cache,\nincluding its current size.\n\nRequires a valid Lookup Cache license.\n","operationId":"getLookupCacheById","tags":["Lookup Caches"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the lookup cache","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Lookup cache retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Response"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update a lookup cache

> Updates an existing lookup cache's configuration.\
> \
> This updates metadata such as name, description, and template settings.\
> To manage the actual cached data, use the data management endpoints.<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","version":"1.0.0"},"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Request schema for creating or updating a lookup cache.\n\nLookup caches are in-memory key-value stores used during integration\nprocessing for fast lookups, deduplication, and cross-reference resolution.\n","properties":{"name":{"type":"string","maxLength":200,"description":"Human-readable name for the lookup cache.\n"},"description":{"type":"string","maxLength":10240,"description":"Optional detailed description of the lookup cache's purpose.\n"},"includeDataInTemplatesAndCloning":{"type":"boolean","default":false,"description":"Whether to include the cached data when this lookup cache is used\nin templates or cloned to another environment.\n\nWhen false (default), only the cache metadata is included — the actual\nkey-value data is not transferred. Set to true if the cached data is\npart of the integration's configuration (e.g., static reference tables).\n"},"externalId":{"type":"string","description":"External identifier for correlating this lookup cache with an external system.\n\nCan be used to look up caches by external reference via the `externalId`\nquery parameter on the list endpoint.\n"}}},"Response":{"type":"object","description":"Response schema for lookup cache operations.\n\nContains the cache configuration, metadata, and current size information.\n","properties":{"_id":{"type":"string","format":"objectId","description":"Unique identifier for the lookup cache"},"_userId":{"type":"string","format":"objectId","description":"Identifier of the owning user"},"name":{"type":"string","description":"Human-readable name for the lookup cache"},"description":{"type":"string","description":"Description of the lookup cache's purpose"},"includeDataInTemplatesAndCloning":{"type":"boolean","description":"Whether cached data is included in templates and cloning"},"_integrationId":{"type":"string","format":"objectId","description":"Integration this lookup cache belongs to"},"_connectorId":{"type":"string","format":"objectId","description":"Connector this lookup cache is associated with"},"_templateId":{"type":"string","format":"objectId","description":"Template this lookup cache was created from"},"_sourceId":{"type":"string","format":"objectId","description":"Source identifier for tracking the cache's origin"},"externalId":{"type":"string","description":"External identifier for this lookup cache"},"size":{"type":"number","minimum":0,"description":"Current size of the lookup cache in bytes.\n\nMaximum allowed size is 50 MB per cache. The per-environment\naggregate limit across all caches is 1 GB.\n"},"sizeInMB":{"type":"string","description":"Human-readable representation of the cache size, rounded up to\nthe nearest 5 MB increment. Returns \"0 MB\" for empty caches,\n\"<N MB\" for caches under 50 MB, and \"50 MB\" for caches at or\nover the limit.\n"},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was created"},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was last modified"},"deletedAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the lookup cache was soft-deleted.\n\nOnly present for deleted caches. The cache will be permanently\nremoved 30 days after this timestamp.\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"}}}}}},"paths":{"/v1/lookupcaches/{_id}":{"put":{"summary":"Update a lookup cache","description":"Updates an existing lookup cache's configuration.\n\nThis updates metadata such as name, description, and template settings.\nTo manage the actual cached data, use the data management endpoints.\n","operationId":"updateLookupCache","tags":["Lookup Caches"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the lookup cache","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Lookup cache 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"}}}}}}
```

## Delete a lookup cache

> Deletes a lookup cache and all its data. The cache is soft-deleted\
> and retained for 30 days before permanent removal.<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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/lookupcaches/{_id}":{"delete":{"summary":"Delete a lookup cache","description":"Deletes a lookup cache and all its data. The cache is soft-deleted\nand retained for 30 days before permanent removal.\n","operationId":"deleteLookupCache","tags":["Lookup Caches"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the lookup cache","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Lookup cache deleted successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Patch a lookup cache

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

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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/lookupcaches/{_id}":{"patch":{"summary":"Patch a lookup cache","description":"Partially updates a lookup cache 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` | Cache display name |\n| `/description` | Cache description |\n\nAll other paths are rejected with `422`.","operationId":"patchLookupCache","tags":["Lookup Caches"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the lookup cache","required":true,"schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonPatchRequest"}}}},"responses":{"204":{"description":"Lookup cache patched successfully"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## Preview cloning a lookup cache

> Returns a preview of the resources that would be created by cloning the specified lookup cache.\
> Lookup caches have no transitive dependencies, so the response contains only the cache itself.\
> No resources are created by this endpoint.<br>

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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":{"ClonePreviewResponse":{"type":"object","description":"Preview of the resources that would be created by a clone operation.\nEach object in the `objects` array represents a resource that will be\ncloned, including the target resource and all transitive dependencies\n(connections, scripts, exports, imports, etc.).\n","properties":{"objects":{"type":"array","description":"List of resources that would be created by the clone. Always includes\nthe target resource and may include transitive dependencies such as\nconnections, scripts, exports, imports, async helpers, and lookup caches.\n","items":{"type":"object","properties":{"model":{"type":"string","description":"The model type of the resource. Observed values include\nAsyncHelper, Connection, Export, Flow, Import, Integration,\nLookupCache, and Script.\n"},"doc":{"type":"object","description":"The full resource document that would be created by the clone.","additionalProperties":true}},"required":["model","doc"]}},"stackRequired":{"type":"boolean","description":"Whether the clone requires a stack (connector-level) environment to proceed."},"_stackId":{"type":["string","null"],"description":"The stack id associated with the resource, or null if no stack is involved."}},"required":["objects","stackRequired","_stackId"]},"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/lookupcaches/{_id}/clone/preview":{"get":{"summary":"Preview cloning a lookup cache","description":"Returns a preview of the resources that would be created by cloning the specified lookup cache.\nLookup caches have no transitive dependencies, so the response contains only the cache itself.\nNo resources are created by this endpoint.\n","operationId":"previewCloneLookupCache","tags":["Lookup Caches"],"parameters":[{"name":"_id","in":"path","description":"The unique identifier of the lookup cache to preview cloning","required":true,"schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Clone preview retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClonePreviewResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Upsert entries into a lookup cache

> Writes key-value entries to a lookup cache. Keys that already exist are\
> overwritten; new keys are created. Keys are strings; values may be strings or\
> objects — arrays at the top level are rejected (wrap them in an object). One\
> invalid value fails the entire batch with \`400 invalid\_value\`.\
> \
> The service rejects batches larger than \~1000 entries or \~5 MB of JSON.\
> Callers uploading more than that should split their payload; the Celigo CLI\
> auto-batches at 1000 entries / 5 MB and concatenates the per-key results.\
> \
> AI guidance:\
> \- Check the cache's \`size\` field before large uploads — each cache is capped\
> &#x20; at 50 MB and the per-environment aggregate is 1 GB.\
> \- Read-back is eventual via \`POST .../getData\`; a successful 200 here means\
> &#x20; the entries are durably stored.\
> \- Use this for small-to-medium batches. The parallel \`s3Key\`-based upload\
> &#x20; path (not documented here) is reserved for the UI's bulk-import flow.

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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":{"LookupCacheDataUpsertRequest":{"type":"object","description":"Request body for upserting key-value entries into a lookup cache. `data` must be\na non-empty array. Keys already present are overwritten; new keys are created.\n\nThe service rejects batches larger than ~1000 entries or ~5 MB — callers inserting\nmore than that should split into multiple requests (the Celigo CLI auto-batches\nat 1000 entries / 5 MB).","properties":{"data":{"type":"array","minItems":1,"description":"Entries to upsert. Must contain at least one item.","items":{"$ref":"#/components/schemas/LookupCacheDataEntry"}}},"required":["data"]},"LookupCacheDataEntry":{"type":"object","description":"A single key-value pair stored in a lookup cache. Keys are strings; values are\neither strings or objects — the cache preserves whichever JSON shape was\nupserted. Top-level arrays are **rejected** at upsert with\n`400 invalid_value \"The value provided corresponding to the key: <k> is invalid\"`;\ncallers that need to store an array should wrap it in an object\n(e.g. `{ \"items\": [...] }`).","properties":{"key":{"type":"string","description":"Lookup key. Treated as an opaque string by the cache — case-sensitive, no\nnormalization. The same cache can hold multiple entries that differ only in\ncase (e.g. `CA` and `ca`)."},"value":{"description":"Value associated with the key. May be a string or an object; nested arrays\ninside an object are fine. Top-level arrays are rejected — wrap them.\nConsumers should check the runtime type before use.","oneOf":[{"title":"String value","type":"string"},{"title":"Object value","type":"object","additionalProperties":true}]}},"required":["key","value"]},"LookupCacheDataUpsertResponse":{"type":"object","description":"Response from a successful lookup-cache upsert. Contains a per-key success flag\nfor every entry in the request — in the same order as submitted.","properties":{"success":{"type":"boolean","description":"Whether the request as a whole was accepted."},"data":{"type":"array","description":"Per-key results, one entry per submitted key.","items":{"$ref":"#/components/schemas/LookupCacheKeyResult"}}},"required":["success","data"]},"LookupCacheKeyResult":{"type":"object","description":"Per-key result returned by the upsert and delete-keys endpoints. The `success`\nflag reflects whether the individual key operation succeeded; the wrapping\nresponse's `success` flag reflects whether the request as a whole was accepted.\n\nFor deletes, `success: true` is returned even for keys that did not exist in the\ncache — the API does not distinguish between \"deleted\" and \"absent.\"","properties":{"key":{"type":"string","description":"The key this result applies to."},"success":{"type":"boolean","description":"Whether the operation on this key succeeded."}},"required":["key","success"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/lookupcaches/{_id}/data":{"post":{"operationId":"upsertLookupCacheData","tags":["Lookup Caches"],"summary":"Upsert entries into a lookup cache","description":"Writes key-value entries to a lookup cache. Keys that already exist are\noverwritten; new keys are created. Keys are strings; values may be strings or\nobjects — arrays at the top level are rejected (wrap them in an object). One\ninvalid value fails the entire batch with `400 invalid_value`.\n\nThe service rejects batches larger than ~1000 entries or ~5 MB of JSON.\nCallers uploading more than that should split their payload; the Celigo CLI\nauto-batches at 1000 entries / 5 MB and concatenates the per-key results.\n\nAI guidance:\n- Check the cache's `size` field before large uploads — each cache is capped\n  at 50 MB and the per-environment aggregate is 1 GB.\n- Read-back is eventual via `POST .../getData`; a successful 200 here means\n  the entries are durably stored.\n- Use this for small-to-medium batches. The parallel `s3Key`-based upload\n  path (not documented here) is reserved for the UI's bulk-import flow.","parameters":[{"name":"_id","in":"path","required":true,"description":"Lookup cache id.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataUpsertRequest"}}}},"responses":{"200":{"description":"Entries were upserted; response carries per-key success flags.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataUpsertResponse"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Delete specific keys from a lookup cache

> Removes named keys from a lookup cache. Send the keys to delete in the request\
> body. To wipe every entry instead, call \`DELETE /v1/lookupcaches/{\_id}/data/purge\`.\
> \
> Send the request with \`Content-Type: application/json\`. The body must be a\
> JSON object with a \`keys\` property; a request with no body is rejected as\
> \`missing\_parameter\`.\
> \
> AI guidance:\
> \- Silent-accept: the response reports \`success: true\` for every submitted key,\
> &#x20; including keys that did not exist in the cache. If you need to distinguish\
> &#x20; "deleted" from "absent," read the cache first.\
> \- An empty \`keys: \[]\` array is accepted and returns \`{success: true, data: \[]}\`.\
> \- The deletion is synchronous and durable — a subsequent read will not see the\
> &#x20; deleted keys.

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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":{"LookupCacheDataDeleteRequest":{"type":"object","description":"Request body for deleting specific keys from a lookup cache. The `keys` array\nmay be empty (the endpoint returns `{success: true, data: []}`), but the field\nitself must be present — a request body missing `keys` is rejected with\n`missing_parameter`.\n\nTo remove every entry from a cache instead, call\n`DELETE /v1/lookupcaches/{_id}/data/purge`.","properties":{"keys":{"type":"array","description":"Keys to remove from the cache.","items":{"type":"string"}}},"required":["keys"]},"LookupCacheDataDeleteResponse":{"type":"object","description":"Response from a successful delete-keys call. Mirrors the upsert response shape:\none per-key result entry per submitted key, in submission order.\n\nNote: `success: true` is returned for every submitted key regardless of whether\nit actually existed in the cache — the endpoint does not distinguish between\n\"deleted\" and \"absent.\" Callers that need that distinction should read the\ncache first.","properties":{"success":{"type":"boolean","description":"Whether the request as a whole was accepted."},"data":{"type":"array","description":"Per-key results, one entry per submitted key.","items":{"$ref":"#/components/schemas/LookupCacheKeyResult"}}},"required":["success","data"]},"LookupCacheKeyResult":{"type":"object","description":"Per-key result returned by the upsert and delete-keys endpoints. The `success`\nflag reflects whether the individual key operation succeeded; the wrapping\nresponse's `success` flag reflects whether the request as a whole was accepted.\n\nFor deletes, `success: true` is returned even for keys that did not exist in the\ncache — the API does not distinguish between \"deleted\" and \"absent.\"","properties":{"key":{"type":"string","description":"The key this result applies to."},"success":{"type":"boolean","description":"Whether the operation on this key succeeded."}},"required":["key","success"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/lookupcaches/{_id}/data":{"delete":{"operationId":"deleteLookupCacheDataKeys","tags":["Lookup Caches"],"summary":"Delete specific keys from a lookup cache","description":"Removes named keys from a lookup cache. Send the keys to delete in the request\nbody. To wipe every entry instead, call `DELETE /v1/lookupcaches/{_id}/data/purge`.\n\nSend the request with `Content-Type: application/json`. The body must be a\nJSON object with a `keys` property; a request with no body is rejected as\n`missing_parameter`.\n\nAI guidance:\n- Silent-accept: the response reports `success: true` for every submitted key,\n  including keys that did not exist in the cache. If you need to distinguish\n  \"deleted\" from \"absent,\" read the cache first.\n- An empty `keys: []` array is accepted and returns `{success: true, data: []}`.\n- The deletion is synchronous and durable — a subsequent read will not see the\n  deleted keys.","parameters":[{"name":"_id","in":"path","required":true,"description":"Lookup cache id.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataDeleteRequest"}}}},"responses":{"200":{"description":"Delete accepted; response carries per-key results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataDeleteResponse"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Read entries from a lookup cache

> Returns entries stored in a lookup cache. Called as \`POST\` (not \`GET\`) so the\
> query — explicit keys or a prefix — can travel in the request body.\
> \
> Body variants:\
> &#x20; \- omitted or \`{}\` → first page of all entries (up to \~1000, unordered).\
> &#x20; \- \`{keys: \[...]}\` → one entry per requested key. Hits carry \`value\`; misses\
> &#x20;   carry \`error: {message}\` — missing keys are \*\*reported\*\*, not silently\
> &#x20;   omitted. Branch on \`error\` vs \`value\` when consuming the response.\
> &#x20; \- \`{startsWith: "prefix"}\` → every entry whose key begins with \`prefix\`\
> &#x20;   (case-sensitive).\
> \
> \`keys\` and \`startsWith\` are treated as mutually exclusive client-side; if both\
> are supplied the server honors \`keys\` and ignores \`startsWith\`.\
> \
> AI guidance:\
> \- There is no pagination cursor for no-filter reads. For caches larger than\
> &#x20; \~1000 entries, design your keys with a prefix scheme and iterate using\
> &#x20; \`startsWith\`.\
> \- Case matters: \`CA\` and \`ca\` are different keys.\
> \- Related: upsert via \`POST .../data\`; remove via \`DELETE .../data\` or\
> &#x20; \`DELETE .../data/purge\`.

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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":{"LookupCacheDataReadRequest":{"type":"object","description":"Request body for reading entries from a lookup cache.\n\nAll fields are optional. If omitted, the endpoint returns the first page of the\ncache (up to ~1000 entries, unordered). `keys` and `startsWith` should be\ntreated as mutually exclusive — if both are supplied the server honors `keys`\nand ignores `startsWith`. An empty JSON body (`{}`) is equivalent to calling\nthe endpoint with no body.","properties":{"keys":{"type":"array","description":"Explicit keys to fetch. The response returns one `data[]` entry per\nrequested key: hits carry `value`, misses carry `error: {message}` — both\nsurface in the same array. Branch on the presence of `error` vs `value`\nwhen consuming the response.","items":{"type":"string"}},"startsWith":{"type":"string","description":"Key prefix filter. Returns every entry whose key begins with the supplied\nstring (case-sensitive). Useful for namespaced keys like\n`tenant-42/customer-…`."}}},"LookupCacheDataReadResponse":{"type":"object","description":"Response from a successful lookup-cache read. Contains the matching entries.\n\nWhen no filter is supplied, the response contains the first page of the cache\n(up to ~1000 entries). The API does not currently expose a pagination cursor for\nlarge caches — callers that need to iterate a cache larger than the page limit\nshould use `startsWith` to narrow the result set, or key their data with a known\nprefix scheme.","properties":{"success":{"type":"boolean","description":"Whether the request succeeded."},"data":{"type":"array","description":"Per-key results, one entry per key returned by the read. Hits carry `key` + `value`\n(`LookupCacheDataEntry`); misses on `keys[]`-filtered reads carry `key` + `error`\n(`LookupCacheDataMissingEntry`). Callers should switch on the presence of `error`\nvs `value` to distinguish. Order is not guaranteed.","items":{"oneOf":[{"$ref":"#/components/schemas/LookupCacheDataEntry"},{"$ref":"#/components/schemas/LookupCacheDataMissingEntry"}]}}},"required":["success","data"]},"LookupCacheDataEntry":{"type":"object","description":"A single key-value pair stored in a lookup cache. Keys are strings; values are\neither strings or objects — the cache preserves whichever JSON shape was\nupserted. Top-level arrays are **rejected** at upsert with\n`400 invalid_value \"The value provided corresponding to the key: <k> is invalid\"`;\ncallers that need to store an array should wrap it in an object\n(e.g. `{ \"items\": [...] }`).","properties":{"key":{"type":"string","description":"Lookup key. Treated as an opaque string by the cache — case-sensitive, no\nnormalization. The same cache can hold multiple entries that differ only in\ncase (e.g. `CA` and `ca`)."},"value":{"description":"Value associated with the key. May be a string or an object; nested arrays\ninside an object are fine. Top-level arrays are rejected — wrap them.\nConsumers should check the runtime type before use.","oneOf":[{"title":"String value","type":"string"},{"title":"Object value","type":"object","additionalProperties":true}]}},"required":["key","value"]},"LookupCacheDataMissingEntry":{"type":"object","description":"Per-key read result returned when a requested `keys[]` entry was not present in\nthe cache. Surfaces in `data[]` alongside successful `LookupCacheDataEntry`\nitems — callers should check for an `error` sub-object to distinguish hits from\nmisses.","properties":{"key":{"type":"string","description":"The key that was not found."},"error":{"type":"object","description":"Miss diagnostic.","properties":{"message":{"type":"string","description":"Human-readable explanation of the miss."}},"required":["message"]}},"required":["key","error"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/lookupcaches/{_id}/getData":{"post":{"operationId":"getLookupCacheData","tags":["Lookup Caches"],"summary":"Read entries from a lookup cache","description":"Returns entries stored in a lookup cache. Called as `POST` (not `GET`) so the\nquery — explicit keys or a prefix — can travel in the request body.\n\nBody variants:\n  - omitted or `{}` → first page of all entries (up to ~1000, unordered).\n  - `{keys: [...]}` → one entry per requested key. Hits carry `value`; misses\n    carry `error: {message}` — missing keys are **reported**, not silently\n    omitted. Branch on `error` vs `value` when consuming the response.\n  - `{startsWith: \"prefix\"}` → every entry whose key begins with `prefix`\n    (case-sensitive).\n\n`keys` and `startsWith` are treated as mutually exclusive client-side; if both\nare supplied the server honors `keys` and ignores `startsWith`.\n\nAI guidance:\n- There is no pagination cursor for no-filter reads. For caches larger than\n  ~1000 entries, design your keys with a prefix scheme and iterate using\n  `startsWith`.\n- Case matters: `CA` and `ca` are different keys.\n- Related: upsert via `POST .../data`; remove via `DELETE .../data` or\n  `DELETE .../data/purge`.","parameters":[{"name":"_id","in":"path","required":true,"description":"Lookup cache id.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataReadRequest"}}}},"responses":{"200":{"description":"Matched entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupCacheDataReadResponse"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Purge all data from a lookup cache

> Removes every entry from a lookup cache. The cache itself is preserved — only\
> its contents are cleared. Use this instead of deleting-and-recreating when you\
> want to keep the cache's \`\_id\`, name, and any references from flows intact.\
> \
> AI guidance:\
> \- Irreversible. Purged entries cannot be recovered — re-upsert from the source\
> &#x20; of truth if needed.\
> \- To delete the cache entirely (not just its data), call\
> &#x20; \`DELETE /v1/lookupcaches/{\_id}\` instead.\
> \- To delete a subset of keys, use \`DELETE /v1/lookupcaches/{\_id}/data\` with a\
> &#x20; \`keys\` body.

```json
{"openapi":"3.1.0","info":{"title":"Lookup Caches","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/lookupcaches/{_id}/data/purge":{"delete":{"operationId":"purgeLookupCacheData","tags":["Lookup Caches"],"summary":"Purge all data from a lookup cache","description":"Removes every entry from a lookup cache. The cache itself is preserved — only\nits contents are cleared. Use this instead of deleting-and-recreating when you\nwant to keep the cache's `_id`, name, and any references from flows intact.\n\nAI guidance:\n- Irreversible. Purged entries cannot be recovered — re-upsert from the source\n  of truth if needed.\n- To delete the cache entirely (not just its data), call\n  `DELETE /v1/lookupcaches/{_id}` instead.\n- To delete a subset of keys, use `DELETE /v1/lookupcaches/{_id}/data` with a\n  `keys` body.","parameters":[{"name":"_id","in":"path","required":true,"description":"Lookup cache id.","schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Cache data was purged. No response body."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## List dependencies of a lookup cache

> 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":"Lookup Caches","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/lookupcaches/{_id}/dependencies":{"get":{"operationId":"listLookupCacheDependencies","tags":["Lookup Caches"],"summary":"List dependencies of a lookup cache","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/lookup-caches.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.