State

Key-value state store for persisting JSON objects or arrays across flow runs. Common use cases include tracking sequence numbers, storing cursors for delta syncs, caching lookup values, and passing state between runs.

Lookup Caches are now the preferred mechanism for storing and retrieving data during flow execution. Prefer Lookup Caches for new integrations; State remains supported for existing flows.

State supports two scopes:

• Global — account-wide keys visible to all flows and scripts.
• Resource-scoped — keys namespaced under a specific export, import, or integration. Resource-scoped keys are isolated from the global key listing.

Values must be non-empty JSON objects or arrays. Bare primitives, null, and empty containers ({}, []) are rejected.

Prefer resource-scoped state over global state when the data belongs to a specific export, import, or integration. State keys are upserted — PUT creates if absent, replaces if present. There is no PATCH; send the full value each time.

State schema

List global state keys

get

/v1/state

Returns all global state key names. Does not return resource-scoped keys — use GET /v1/{resourceType}/{_id}/state for those.

Lists key names only, not values. Call GET /v1/state/{key} to retrieve a specific value.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Object containing an array of key names.

application/json

keysstring[]Required

204

No global state keys exist.

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/state

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

{
  "keys": [
    "sequence_number",
    "last_sync_time"
  ]
}

Delete all global state keys

delete

/v1/state

Deletes all global state keys and their values. This is a destructive operation and cannot be undone.

Prefer DELETE /v1/state/{key} to remove individual keys.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

204

All global state 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

delete/v1/state

DELETE /v1/state HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get a global state value

get

/v1/state/{key}

Returns the JSON value stored under the given global key.

Returns the raw JSON value (object or array), not wrapped in an envelope.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

keystringRequired

The state key name.

Example: sequence_number

Responses

200

The stored value (a JSON object or array).

application/json

A stored state value. Values must be non-empty JSON objects or arrays — bare primitives, null, and empty containers ({}, []) are rejected. Keys are upserted: PUT creates the key if absent and replaces the value if present.

object · objectOptional

or

array · min: 1Optional

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

The key does not exist.

application/json

get/v1/state/{key}

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

{
  "lastSyncTime": "2025-08-10T14:22:33.000Z",
  "sequenceNumber": 4207
}

Create or update a global state value

put

/v1/state/{key}

Sets the value for a global state key. Creates the key if it does not exist; replaces the value if it does.

The request body must be a non-empty JSON object or array. Bare JSON primitives (strings, numbers, booleans, null) and empty containers ({}, []) are rejected.

This is an upsert — check the status code to distinguish create (201) from update (200). The response body is plain text, not JSON. If the state belongs to a specific export, import, or integration, use the resource-scoped endpoint instead.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

keystringRequired

The state key name.

Example: sequence_number

Body

A non-empty JSON object or array to store. Bare primitives and empty containers are not accepted.

object · objectOptional

or

array · min: 1Optional

Responses

200

Existing key updated.

text/plain

string · enumOptionalPossible values:

201

New key created.

text/plain

400

Invalid request body. The body is not valid JSON, or is a bare primitive (string, number, boolean, or null).

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

415

The Content-Type header is missing or is not application/json.

application/json

422

The request body is empty, or is an empty container ({} or []).

application/json

put/v1/state/{key}

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

{
  "lastSyncTime": "2025-08-10T14:22:33.000Z",
  "sequenceNumber": 4207
}

OK

Delete a global state key

delete

/v1/state/{key}

Deletes a specific global state key and its value. Returns 404 if the key does not exist.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

keystringRequired

The state key name.

Example: sequence_number

Responses

204

Key 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

The key does not exist.

application/json

delete/v1/state/{key}

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

No content

List state keys for a resource

get

/v1/{resourceType}/{_resourceId}/state

Returns the list of state key names stored under the specified resource. These keys are separate from global state.

Returns 204 No Content when no keys exist for the resource.

Only exports, imports, and integrations support resource-scoped state. Other resource types return 403.

This only lists key names, not values. Call GET /v1/{resourceType}/{_resourceId}/state/{key} to retrieve a specific value.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

resourceTypestring · enumRequired

The resource type. Only exports, imports, and integrations are supported.

Possible values:

_resourceIdstring · objectIdRequired

The resource ID.

Example: 66a1f2c3b4d5e6f7a8b9c0d1

Responses

200

Object containing an array of key names.

application/json

keysstring[]Required

204

No state keys exist for this resource.

400

The resource ID is not a valid identifier.

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

403

The resource type does not support state. Only exports, imports, and integrations are allowed.

application/json

404

The resource was not found.

application/json

get/v1/{resourceType}/{_resourceId}/state

GET /v1/{resourceType}/{_resourceId}/state HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "keys": [
    "sequence_number",
    "last_sync_time"
  ]
}

Delete all state keys for a resource

delete

/v1/{resourceType}/{_resourceId}/state

Deletes all state keys and values stored under the specified resource. This is destructive and cannot be undone.

Prefer DELETE /v1/{resourceType}/{_resourceId}/state/{key} to remove individual keys.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

resourceTypestring · enumRequired

The resource type. Only exports, imports, and integrations are supported.

Possible values:

_resourceIdstring · objectIdRequired

The resource ID.

Example: 66a1f2c3b4d5e6f7a8b9c0d1

Responses

204

All resource state deleted.

No content

400

The resource ID is not a valid identifier.

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

403

The resource type does not support state.

application/json

404

The resource was not found.

application/json

delete/v1/{resourceType}/{_resourceId}/state

DELETE /v1/{resourceType}/{_resourceId}/state HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get a resource-scoped state value

get

/v1/{resourceType}/{_resourceId}/state/{key}

Returns the JSON value stored under the given key for a specific resource.

Only exports, imports, and integrations support resource-scoped state.

Returns the raw JSON value (object or array), not wrapped in an envelope. A 403 means the resource type doesn't support state, not a permissions issue.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

resourceTypestring · enumRequired

The resource type. Only exports, imports, and integrations are supported.

Possible values:

_resourceIdstring · objectIdRequired

The resource ID.

Example: 66a1f2c3b4d5e6f7a8b9c0d1

keystringRequired

The state key name.

Example: sequence_number

Responses

200

The stored value (a JSON object or array).

application/json

A stored state value. Values must be non-empty JSON objects or arrays — bare primitives, null, and empty containers ({}, []) are rejected. Keys are upserted: PUT creates the key if absent and replaces the value if present.

object · objectOptional

or

array · min: 1Optional

400

The resource ID is not a valid identifier.

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

403

The resource type does not support state.

application/json

404

The resource or key was not found.

application/json

get/v1/{resourceType}/{_resourceId}/state/{key}

GET /v1/{resourceType}/{_resourceId}/state/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "cursor": "2025-08-10T14:22:33.000Z",
  "pageToken": "abc123"
}

Create or update a resource-scoped state value

put

/v1/{resourceType}/{_resourceId}/state/{key}

Sets the value for a state key under a specific resource. Creates the key if it does not exist; replaces the value if it does.

The request body must be a non-empty JSON object or array. Bare JSON primitives (strings, numbers, booleans, null) and empty containers ({}, []) are rejected.

Only exports, imports, and integrations support resource-scoped state.

This is an upsert — check the status code to distinguish create (201) from update (200). The response body is plain text, not JSON.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

resourceTypestring · enumRequired

The resource type. Only exports, imports, and integrations are supported.

Possible values:

_resourceIdstring · objectIdRequired

The resource ID.

Example: 66a1f2c3b4d5e6f7a8b9c0d1

keystringRequired

The state key name.

Example: sequence_number

Body

A non-empty JSON object or array to store. Bare primitives and empty containers are not accepted.

object · objectOptional

or

array · min: 1Optional

Responses

200

Existing key updated.

text/plain

string · enumOptionalPossible values:

201

New key created.

text/plain

400

Invalid request. The body is not valid JSON, is a bare primitive, or the resource ID is invalid.

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

403

The resource type does not support state.

application/json

404

The resource was not found.

application/json

415

The Content-Type header is missing or is not application/json.

application/json

422

The request body is empty, or is an empty container ({} or []).

application/json

put/v1/{resourceType}/{_resourceId}/state/{key}

PUT /v1/{resourceType}/{_resourceId}/state/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 58

{
  "cursor": "2025-08-10T14:22:33.000Z",
  "pageToken": "abc123"
}

OK

Delete a resource-scoped state key

delete

/v1/{resourceType}/{_resourceId}/state/{key}

Deletes a specific state key and its value from the resource. Returns 404 if the key does not exist.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

resourceTypestring · enumRequired

The resource type. Only exports, imports, and integrations are supported.

Possible values:

_resourceIdstring · objectIdRequired

The resource ID.

Example: 66a1f2c3b4d5e6f7a8b9c0d1

keystringRequired

The state key name.

Example: sequence_number

Responses

204

Key deleted.

No content

400

The resource ID is not a valid identifier.

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

403

The resource type does not support state.

application/json

404

The resource or key was not found.

application/json

delete/v1/{resourceType}/{_resourceId}/state/{key}

DELETE /v1/{resourceType}/{_resourceId}/state/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content