Lookup Caches

Lookup caches are in-memory key-value stores used during flow execution for fast lookups, deduplication, and cross-reference resolution.

Lookup caches are account-level resources — they are not scoped to a specific integration.

• Maximum size: 50 MB per cache
• Aggregate limit: 1 GB per environment
• Data is managed through separate endpoints (getData, upsert, delete, purge) that proxy to the Lookup Cache service

Lookup cache schema

List lookup caches

get

/v1/lookupcaches

Returns lookup caches in the account.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

limitinteger · min: 1Optional

Maximum number of caches to return per page. Omit to return all caches.

Example: 100

externalIdstringOptional

Filter to caches matching this exact external identifier.

Example: ext-cache-12345

Responses

200

One or more lookup caches found.

application/json

204

No lookup caches exist in the account.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/lookupcaches

GET /v1/lookupcaches HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "69c2eb25365fb658aa39c642",
    "_userId": "624cb0346309dc3a543733a2",
    "name": "US State Name to State Code",
    "description": "Maps full state names, abbreviations, and common variations to 2-letter state codes",
    "includeDataInTemplatesAndCloning": false,
    "size": 1887,
    "sizeInMB": "<5 MB",
    "createdAt": "2026-03-24T19:51:01.266Z",
    "lastModified": "2026-04-18T05:40:33.812Z"
  },
  {
    "_id": "69f4b2d97009ea11ab730306",
    "_userId": "624cb0346309dc3a543733a2",
    "name": "",
    "includeDataInTemplatesAndCloning": false,
    "size": 0,
    "sizeInMB": "0 MB",
    "createdAt": "2026-05-01T14:04:09.321Z",
    "lastModified": "2026-05-01T14:04:09.339Z"
  }
]

Create a lookup cache

post

/v1/lookupcaches

Creates a new empty lookup cache. Only name is required. Populate it afterwards via POST /v1/lookupcaches/{_id}/data.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Writable fields shared by the request and response schemas.

namestring · max: 200Optional

Display name.

Example: Customer ID Cache

descriptionstring · max: 5120Optional

Purpose or contents of the cache.

Example: Maps external customer IDs to internal Salesforce IDs for deduplication

includeDataInTemplatesAndCloningbooleanOptional

Whether to include the cached key-value data when this cache is used in templates or cloned. When false (default), only metadata transfers. Set to true for static reference tables.

Default: false

externalIdstringOptional

Caller-supplied identifier for cross-system correlation.

Example: ext-cache-12345

Responses

201

Lookup cache created.

application/json

Lookup cache object as returned by the API.

namestring · max: 200Optional

Display name.

Example: Customer ID Cache

descriptionstring · max: 5120Optional

Purpose or contents of the cache.

Example: Maps external customer IDs to internal Salesforce IDs for deduplication

includeDataInTemplatesAndCloningbooleanOptional

Whether to include the cached key-value data when this cache is used in templates or cloned. When false (default), only metadata transfers. Set to true for static reference tables.

Default: false

externalIdstringOptional

Caller-supplied identifier for cross-system correlation.

Example: ext-cache-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyRequired

User who owns this lookup cache.

Example: 624cb0346309dc3a543733a2

_templateIdstring · objectIdRead-onlyOptional

Template this lookup cache was installed from, when it originated from a template.

Example: 6a27a36f9cea1a85192e72cd

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this cache was created by cloning or installing a template.

Example: 5f8d43a1b9e5a80011a35f2c

sizeintegerRead-onlyOptional

Current size of the cached data in bytes. Maximum 50 MB per cache; 1 GB aggregate per environment.

sizeInMBstringRead-onlyOptional

Human-readable size rounded up to the nearest 5 MB increment. "0 MB" for empty caches, "<5 MB" through "<50 MB" for non-empty caches, "50 MB" at the per-cache cap.

Example: 0 MB

draftbooleanRead-onlyOptional

When true, this cache was created as a draft by the AI-assisted builder and has not yet been confirmed.

Example: true

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft cache expires and will be automatically deleted. Only present when draft is true.

Example: 2026-05-08T17:29:30.726Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

post/v1/lookupcaches

POST /v1/lookupcaches HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28

{
  "name": "Customer ID Cache"
}

{
  "_id": "6a07cb9a2334574c8c54bcb6",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "Customer ID Cache",
  "includeDataInTemplatesAndCloning": false,
  "size": 0,
  "sizeInMB": "0 MB",
  "createdAt": "2026-05-15T21:42:35.701Z",
  "lastModified": "2026-05-15T21:42:35.701Z"
}

Get a lookup cache

get

/v1/lookupcaches/{_id}

Returns configuration, metadata, and current size of a lookup cache. This returns metadata only — to read the cached key-value data, use POST /v1/lookupcaches/{_id}/getData.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache ID.

Example: 69c2eb25365fb658aa39c642

Responses

200

Lookup cache found.

application/json

Lookup cache object as returned by the API.

namestring · max: 200Optional

Display name.

Example: Customer ID Cache

descriptionstring · max: 5120Optional

Purpose or contents of the cache.

Example: Maps external customer IDs to internal Salesforce IDs for deduplication

includeDataInTemplatesAndCloningbooleanOptional

Whether to include the cached key-value data when this cache is used in templates or cloned. When false (default), only metadata transfers. Set to true for static reference tables.

Default: false

externalIdstringOptional

Caller-supplied identifier for cross-system correlation.

Example: ext-cache-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyRequired

User who owns this lookup cache.

Example: 624cb0346309dc3a543733a2

_templateIdstring · objectIdRead-onlyOptional

Template this lookup cache was installed from, when it originated from a template.

Example: 6a27a36f9cea1a85192e72cd

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this cache was created by cloning or installing a template.

Example: 5f8d43a1b9e5a80011a35f2c

sizeintegerRead-onlyOptional

Current size of the cached data in bytes. Maximum 50 MB per cache; 1 GB aggregate per environment.

sizeInMBstringRead-onlyOptional

Human-readable size rounded up to the nearest 5 MB increment. "0 MB" for empty caches, "<5 MB" through "<50 MB" for non-empty caches, "50 MB" at the per-cache cap.

Example: 0 MB

draftbooleanRead-onlyOptional

When true, this cache was created as a draft by the AI-assisted builder and has not yet been confirmed.

Example: true

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft cache expires and will be automatically deleted. Only present when draft is true.

Example: 2026-05-08T17:29:30.726Z

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/lookupcaches/{_id}

GET /v1/lookupcaches/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "69c2eb25365fb658aa39c642",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "US State Name to State Code",
  "description": "Maps full state names, abbreviations, and common variations to 2-letter state codes",
  "includeDataInTemplatesAndCloning": false,
  "size": 1887,
  "sizeInMB": "<5 MB",
  "createdAt": "2026-03-24T19:51:01.266Z",
  "lastModified": "2026-04-18T05:40:33.812Z"
}

Update a lookup cache

put

/v1/lookupcaches/{_id}

Replaces the cache's writable fields. Read-only fields (_id, _userId, size, sizeInMB, timestamps) are silently ignored. To write cached data, use POST /v1/lookupcaches/{_id}/data.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache ID.

Example: 69c2eb25365fb658aa39c642

Body

Writable fields shared by the request and response schemas.

namestring · max: 200Optional

Display name.

Example: Customer ID Cache

descriptionstring · max: 5120Optional

Purpose or contents of the cache.

Example: Maps external customer IDs to internal Salesforce IDs for deduplication

includeDataInTemplatesAndCloningbooleanOptional

Whether to include the cached key-value data when this cache is used in templates or cloned. When false (default), only metadata transfers. Set to true for static reference tables.

Default: false

externalIdstringOptional

Caller-supplied identifier for cross-system correlation.

Example: ext-cache-12345

Responses

200

Lookup cache updated.

application/json

Lookup cache object as returned by the API.

namestring · max: 200Optional

Display name.

Example: Customer ID Cache

descriptionstring · max: 5120Optional

Purpose or contents of the cache.

Example: Maps external customer IDs to internal Salesforce IDs for deduplication

includeDataInTemplatesAndCloningbooleanOptional

Whether to include the cached key-value data when this cache is used in templates or cloned. When false (default), only metadata transfers. Set to true for static reference tables.

Default: false

externalIdstringOptional

Caller-supplied identifier for cross-system correlation.

Example: ext-cache-12345

_idstring · objectIdRead-onlyRequired

Unique identifier for the resource. Format is a 24-character hexadecimal string.

Example: 5f8d43a1b9e5a80011a35f2c

createdAtstring · date-timeRead-onlyRequired

Timestamp when the resource was created. Set automatically and cannot be modified.

Example: 2023-04-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the resource was last updated. Changes whenever any property is modified.

Example: 2023-04-15T14:30:15Z

deletedAtstring · nullableRead-onlyOptional

Timestamp when the resource was soft-deleted. When null or absent, the resource is active.

Example: 2023-05-20T11:45:32Z

_userIdstring · objectIdRead-onlyRequired

User who owns this lookup cache.

Example: 624cb0346309dc3a543733a2

_templateIdstring · objectIdRead-onlyOptional

Template this lookup cache was installed from, when it originated from a template.

Example: 6a27a36f9cea1a85192e72cd

_sourceIdstring · objectIdRead-onlyOptional

Origin resource ID when this cache was created by cloning or installing a template.

Example: 5f8d43a1b9e5a80011a35f2c

sizeintegerRead-onlyOptional

Current size of the cached data in bytes. Maximum 50 MB per cache; 1 GB aggregate per environment.

sizeInMBstringRead-onlyOptional

Human-readable size rounded up to the nearest 5 MB increment. "0 MB" for empty caches, "<5 MB" through "<50 MB" for non-empty caches, "50 MB" at the per-cache cap.

Example: 0 MB

draftbooleanRead-onlyOptional

When true, this cache was created as a draft by the AI-assisted builder and has not yet been confirmed.

Example: true

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft cache expires and will be automatically deleted. Only present when draft is true.

Example: 2026-05-08T17:29:30.726Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

put/v1/lookupcaches/{_id}

PUT /v1/lookupcaches/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 143

{
  "name": "US State Code Lookup (v2)",
  "description": "Updated mapping table — now includes territories",
  "includeDataInTemplatesAndCloning": true
}

{
  "_id": "69c2eb25365fb658aa39c642",
  "_userId": "624cb0346309dc3a543733a2",
  "name": "US State Code Lookup (v2)",
  "description": "Updated mapping table — now includes territories",
  "includeDataInTemplatesAndCloning": true,
  "size": 1887,
  "sizeInMB": "<5 MB",
  "createdAt": "2026-03-24T19:51:01.266Z",
  "lastModified": "2026-04-21T09:30:12.405Z"
}

Delete a lookup cache

delete

/v1/lookupcaches/{_id}

Soft-deletes a lookup cache and all its data. Retained for 30 days before permanent removal. To clear data without deleting the cache itself, use DELETE /v1/lookupcaches/{_id}/data/purge instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache ID.

Example: 69c2eb25365fb658aa39c642

Responses

204

Lookup cache deleted.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/lookupcaches/{_id}

DELETE /v1/lookupcaches/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch a lookup cache

patch

/v1/lookupcaches/{_id}

Partially updates a lookup cache using a JSON Patch document (RFC 6902). Only replace is supported, on these paths:

Path	Description
/name	Cache display name
/description	Cache description

All other paths or operations are rejected.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache ID.

Example: 69c2eb25365fb658aa39c642

Bodyobject · JsonPatchOperation[]

A JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.

opstring · enumRequired

The operation to perform.

Possible values:

pathstringRequired

JSON Pointer (RFC 6901) to the field to patch. Only whitelisted paths are accepted — unlisted paths return 422 with "<path> is not a whitelisted property".

valueanyOptional

The new value to set. Required for replace and add, omit for remove.

Responses

204

Lookup cache patched successfully

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

patch/v1/lookupcaches/{_id}

PATCH /v1/lookupcaches/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 66

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Customer ID Cache (v2)"
  }
]

No content

Preview cloning a lookup cache

get

/v1/lookupcaches/{_id}/clone/preview

Returns resources that would be created by cloning this cache. Lookup caches have no transitive dependencies, so the response contains only the cache itself. No resources are created. Whether the clone includes cached data depends on the source cache's includeDataInTemplatesAndCloning setting.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache ID.

Example: 69c2eb25365fb658aa39c642

Responses

200

Clone preview retrieved successfully

application/json

Preview of the resources that would be created by a clone operation. Each object in the objects array represents a resource that will be cloned, including the target resource and all transitive dependencies (connections, scripts, exports, imports, etc.).

stackRequiredbooleanOptional

Whether the clone requires a stack (connector-level) environment to proceed.

_stackIdstring · nullableOptional

The stack id associated with the resource, or null if no stack is involved.

Example: 5f8d43a1b9e5a80011a35f2c

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/lookupcaches/{_id}/clone/preview

GET /v1/lookupcaches/{_id}/clone/preview HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "objects": [
    {
      "model": "LookupCache",
      "doc": {
        "name": "US State Name to State Code",
        "description": "Maps full state names, abbreviations, and common variations to 2-letter state codes",
        "includeDataInTemplatesAndCloning": false
      }
    }
  ],
  "stackRequired": false,
  "_stackId": null
}

Upsert entries into a lookup cache

post

/v1/lookupcaches/{_id}/data

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. Each cache is capped at 50 MB and the per-environment aggregate is 1 GB.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache id.

Example: 69c2eb25365fb658aa39c642

Body

Request body for upserting key-value entries into a lookup cache. data must be a non-empty array. Keys already present are overwritten; new keys are created.

The service rejects batches larger than ~1000 entries or ~5 MB — callers inserting more than that should split into multiple requests (the Celigo CLI auto-batches at 1000 entries / 5 MB).

Responses

200

Entries upserted. Per-key success flags in response.

application/json

Response from a successful lookup-cache upsert. Contains a per-key success flag for every entry in the request — in the same order as submitted.

successbooleanOptional

When true, the server accepted the upsert request. Individual key results are in data.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

post/v1/lookupcaches/{_id}/data

POST /v1/lookupcaches/{_id}/data HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 105

{
  "data": [
    {
      "key": "CA",
      "value": "California"
    },
    {
      "key": "NY",
      "value": "New York"
    },
    {
      "key": "TX",
      "value": "Texas"
    }
  ]
}

{
  "success": true,
  "data": [
    {
      "key": "CA",
      "success": true
    },
    {
      "key": "NY",
      "success": true
    },
    {
      "key": "TX",
      "success": true
    }
  ]
}

Delete specific keys from a lookup cache

delete

/v1/lookupcaches/{_id}/data

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. The response reports success: true for every submitted key, including keys that did not exist in the cache.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache id.

Example: 69c2eb25365fb658aa39c642

Body

Request body for deleting specific keys from a lookup cache. The keys array may be empty (the endpoint returns {success: true, data: []}), but the field itself must be present — a request body missing keys is rejected with missing_parameter.

To remove every entry from a cache instead, call DELETE /v1/lookupcaches/{_id}/data/purge.

keysstring[]Required

Keys to remove from the cache.

Example: ["CA","NY"]

Responses

200

Delete accepted. Per-key results in response.

application/json

Response from a successful delete-keys call. Mirrors the upsert response shape: one per-key result entry per submitted key, in submission order.

Note: success: true is returned for every submitted key regardless of whether it actually existed in the cache — the endpoint does not distinguish between "deleted" and "absent." Callers that need that distinction should read the cache first.

successbooleanOptional

When true, the server accepted the delete request. Individual key results are in data.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/lookupcaches/{_id}/data

DELETE /v1/lookupcaches/{_id}/data HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "keys": [
    "CA",
    "NY"
  ]
}

{
  "success": true,
  "data": [
    {
      "key": "CA",
      "success": true
    },
    {
      "key": "NY",
      "success": true
    }
  ]
}

Read entries from a lookup cache

post

/v1/lookupcaches/{_id}/getData

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:

• omitted or {} → first page of all entries (up to ~1000, unordered).
• {keys: [...]} → one entry per requested key. Hits carry value; misses carry error: {message} — missing keys are reported, not silently omitted. Branch on error vs value when consuming the response.
• {startsWith: "prefix"} → every entry whose key begins with prefix (case-sensitive).

keys and startsWith are treated as mutually exclusive client-side; if both are supplied the server honors keys and ignores startsWith. Keys are case-sensitive. There is no pagination cursor for unfiltered reads; for caches larger than ~1000 entries, use a prefix scheme with startsWith.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache id.

Example: 69c2eb25365fb658aa39c642

Body

Request body for reading entries from a lookup cache.

All fields are optional. If omitted, the endpoint returns the first page of the cache (up to ~1000 entries, unordered). keys and startsWith should be treated as mutually exclusive — if both are supplied the server honors keys and ignores startsWith. An empty JSON body ({}) is equivalent to calling the endpoint with no body.

keysstring[]Optional

Explicit keys to fetch. The response returns one data[] entry per requested key: hits carry value, misses carry error: {message} — both surface in the same array. Branch on the presence of error vs value when consuming the response.

Example: ["CA","NY","TX"]

startsWithstringOptional

Key prefix filter. Returns every entry whose key begins with the supplied string (case-sensitive). Useful for namespaced keys like tenant-42/customer-….

Example: tenant-42/

Responses

200

Matched entries.

application/json

Response from a successful lookup-cache read. Contains the matching entries.

When no filter is supplied, the response contains the first page of the cache (up to ~1000 entries). The API does not currently expose a pagination cursor for large caches — callers that need to iterate a cache larger than the page limit should use startsWith to narrow the result set, or key their data with a known prefix scheme.

successbooleanOptional

When true, the read request completed successfully.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

post/v1/lookupcaches/{_id}/getData

POST /v1/lookupcaches/{_id}/getData HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "success": true,
  "data": [
    {
      "key": "CA",
      "value": "California"
    },
    {
      "key": "NY",
      "value": "New York"
    },
    {
      "key": "ZZ",
      "error": {
        "message": "Key not found"
      }
    }
  ]
}

Purge all data from a lookup cache

delete

/v1/lookupcaches/{_id}/data/purge

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. This operation is irreversible. To delete a subset of keys, use DELETE /v1/lookupcaches/{_id}/data with a keys body.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Lookup cache id.

Example: 69c2eb25365fb658aa39c642

Responses

204

Cache data was purged. No response body.

No content

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/lookupcaches/{_id}/data/purge

DELETE /v1/lookupcaches/{_id}/data/purge HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

List dependencies of a lookup cache

get

/v1/lookupcaches/{_id}/dependencies

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. An empty object {} means no dependents exist (also returned for a well-formatted but nonexistent id).

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Resource ID.

Example: 69c2eb25365fb658aa39c642

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/lookupcaches/{_id}/dependencies

GET /v1/lookupcaches/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{}