Guardrails

Guardrails are safety and compliance checks that evaluate data flowing through integrations — detecting PII, moderating content, or applying custom AI-powered rules.

Guardrails are import resources with adaptorType: GuardrailImport. All CRUD operations use the /v1/imports endpoints. The guardrail object holds the type-specific configuration.

Guardrail schema

List guardrails

get

/v1/imports

Returns all imports in the account, not just guardrails. Filter client-side by adaptorType: "GuardrailImport" to isolate guardrails.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

includestringOptional

Comma-separated list of fields to project into each returned record. Triggers summary projection: the response contains a minimal identity set (_id, name, plus resource-specific fields) with the requested fields added on top. Supports dot notation for nested fields. Mutually exclusive with exclude.

Example: _integrationId,disabled,lastModified

excludestringOptional

Comma-separated list of fields to strip from the default response. Unlike include, does not trigger summary projection — returns the full record with the named fields removed. Protected identity fields (e.g. name) cannot be stripped. Mutually exclusive with include.

Example: createdAt,lastModified

Responses

200

Successfully retrieved list of imports

application/json

204

No imports 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/imports

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

[
  {
    "_id": "69eb9f5078dbae2f1bb05f89",
    "createdAt": "2026-04-24T16:50:24.073Z",
    "lastModified": "2026-05-02T15:46:24.249Z",
    "name": "PII Scanner",
    "apiIdentifier": "i39ee734f7",
    "sandbox": false,
    "lookups": [],
    "adaptorType": "GuardrailImport",
    "guardrail": {
      "type": "pii",
      "confidenceThreshold": 0.7,
      "pii": {
        "entities": [
          "email_address",
          "phone_number",
          "us_social_security_number"
        ],
        "mask": true
      }
    }
  },
  {
    "_id": "69eb9f666fbf339ed3bc66c3",
    "createdAt": "2026-04-24T16:50:46.439Z",
    "lastModified": "2026-04-24T16:50:53.525Z",
    "name": "Content Moderator",
    "_connectionId": "68ae48d6b5f755d2dd38c294",
    "apiIdentifier": "i6a7acf995",
    "sandbox": false,
    "lookups": [],
    "adaptorType": "GuardrailImport",
    "guardrail": {
      "type": "moderation",
      "confidenceThreshold": 0.7,
      "moderation": {
        "categories": [
          "hate",
          "violence",
          "harassment"
        ]
      }
    }
  }
]

Create a guardrail

post

/v1/imports

Creates a new guardrail import. _connectionId is only needed for BYOK ai_agent guardrails.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Configuration for a guardrail import. _connectionId is only required for BYOK ai_agent guardrails.

namestring · max: 100Required

Display name for the guardrail.

Example: PII Scanner

descriptionstring · max: 5120Optional

Optional description of the guardrail's purpose.

Example: Scans records for PII and masks detected values before import.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key). Only needed for ai_agent type guardrails. Optional — platform-managed credentials are used when omitted.

Example: 68ae48d6b5f755d2dd38c294

adaptorTypestring · enumRequired

Must be GuardrailImport.

Example: GuardrailImportPossible values:

inputContextstring · enumOptional

Controls the shape of the input passed to the guardrail's processing pipeline, exactly as on other imports. The UI writes record explicitly on new guardrails; when the field is absent the platform behaves as record.

Example: recordPossible values:

Responses

201

Guardrail created successfully

application/json

Guardrail import object as returned by the API.

_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

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

namestring · max: 100Required

Display name for the guardrail. May be empty if created without one.

Example: PII Scanner

descriptionstring · max: 5120Optional

Free-text note describing the guardrail's purpose.

Example: Scans records for PII and masks detected values before import.

adaptorTypestring · enumRequired

Always GuardrailImport for guardrails.

Example: GuardrailImportPossible values:

_connectionIdstring · objectIdOptional

BYOK connection backing an ai_agent guardrail. Absent when platform-managed credentials are used.

Example: 68ae48d6b5f755d2dd38c294

_sourceIdstring · objectIdRead-onlyOptional

Source guardrail this one was cloned from. Present only on clones.

Example: 69a886183b213b3ac90860fe

inputContextstring · enumOptional

Input shape for the guardrail's processing pipeline. Present when set; absence means record.

Example: recordPossible values:

apiIdentifierstringRead-onlyRequired

Ten-character hex identifier used to invoke the guardrail over HTTP.

Example: i894602e87

lookupsobject[]Required

Static lookup configurations. Guardrail (AI agent) imports support static lookups only; defaults to an empty array.

Example: []

mappingsobject[]Optional

Import field mappings. Each entry requires a status field. Typically empty for guardrails.

Example: []

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

422

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

application/json

post/v1/imports

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

{
  "name": "PII Scanner",
  "adaptorType": "GuardrailImport",
  "guardrail": {
    "type": "pii",
    "confidenceThreshold": 0.7,
    "pii": {
      "entities": [
        "email_address",
        "phone_number",
        "us_social_security_number"
      ],
      "mask": true
    }
  }
}

{
  "_id": "6a1cfd72c7867992e6d5b021",
  "createdAt": "2026-06-01T03:33:06.758Z",
  "lastModified": "2026-06-01T03:33:06.851Z",
  "name": "PII Scanner",
  "apiIdentifier": "i894602e87",
  "lookups": [],
  "adaptorType": "GuardrailImport",
  "guardrail": {
    "type": "pii",
    "confidenceThreshold": 0.7,
    "pii": {
      "entities": [
        "email_address",
        "phone_number"
      ],
      "mask": true
    }
  }
}

Get a guardrail

get

/v1/imports/{_id}

Returns the complete configuration of a specific guardrail import. The _id is from the imports collection — the same ID used for any import type.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the guardrail import

Example: 5f8d43a1b9e5a80011a35f2c

Responses

200

Guardrail retrieved successfully

application/json

Guardrail import object as returned by the API.

_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

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

namestring · max: 100Required

Display name for the guardrail. May be empty if created without one.

Example: PII Scanner

descriptionstring · max: 5120Optional

Free-text note describing the guardrail's purpose.

Example: Scans records for PII and masks detected values before import.

adaptorTypestring · enumRequired

Always GuardrailImport for guardrails.

Example: GuardrailImportPossible values:

_connectionIdstring · objectIdOptional

BYOK connection backing an ai_agent guardrail. Absent when platform-managed credentials are used.

Example: 68ae48d6b5f755d2dd38c294

_sourceIdstring · objectIdRead-onlyOptional

Source guardrail this one was cloned from. Present only on clones.

Example: 69a886183b213b3ac90860fe

inputContextstring · enumOptional

Input shape for the guardrail's processing pipeline. Present when set; absence means record.

Example: recordPossible values:

apiIdentifierstringRead-onlyRequired

Ten-character hex identifier used to invoke the guardrail over HTTP.

Example: i894602e87

lookupsobject[]Required

Static lookup configurations. Guardrail (AI agent) imports support static lookups only; defaults to an empty array.

Example: []

mappingsobject[]Optional

Import field mappings. Each entry requires a status field. Typically empty for guardrails.

Example: []

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/imports/{_id}

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

{
  "_id": "69eb9f666fbf339ed3bc66c3",
  "createdAt": "2026-04-24T16:50:46.439Z",
  "lastModified": "2026-04-24T16:50:53.525Z",
  "name": "Custom Validator",
  "_connectionId": "68ae48d6b5f755d2dd38c294",
  "apiIdentifier": "i6a7acf995",
  "sandbox": false,
  "lookups": [],
  "adaptorType": "GuardrailImport",
  "guardrail": {
    "type": "ai_agent",
    "confidenceThreshold": 0.7,
    "aiAgent": {
      "provider": "openai",
      "openai": {
        "instructions": "Validate that each record has a non-empty email field.",
        "model": "gpt-4.1-mini-2025-04-14",
        "tools": []
      }
    }
  }
}

Update a guardrail

put

/v1/imports/{_id}

Replaces the guardrail import with the provided configuration. This is a full replace -- include all fields you want to keep. adaptorType must remain GuardrailImport.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the guardrail import

Example: 5f8d43a1b9e5a80011a35f2c

Body

Configuration for a guardrail import. _connectionId is only required for BYOK ai_agent guardrails.

namestring · max: 100Required

Display name for the guardrail.

Example: PII Scanner

descriptionstring · max: 5120Optional

Optional description of the guardrail's purpose.

Example: Scans records for PII and masks detected values before import.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key). Only needed for ai_agent type guardrails. Optional — platform-managed credentials are used when omitted.

Example: 68ae48d6b5f755d2dd38c294

adaptorTypestring · enumRequired

Must be GuardrailImport.

Example: GuardrailImportPossible values:

inputContextstring · enumOptional

Controls the shape of the input passed to the guardrail's processing pipeline, exactly as on other imports. The UI writes record explicitly on new guardrails; when the field is absent the platform behaves as record.

Example: recordPossible values:

Responses

200

Guardrail updated successfully

application/json

Guardrail import object as returned by the API.

_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

_integrationIdstring · objectIdRead-onlyOptional

Reference to the specific integration instance that contains this resource.

This field is only populated for resources that are part of an integration app installation. It contains the unique identifier (_id) of the integration resource that was installed in the account.

The integration instance represents a specific installed instance of an integration app, with its own configuration, settings, and runtime environment.

This reference enables:

• Tracing the resource back to its parent integration instance
• Permission and access control based on integration ownership
• Lifecycle management (enabling/disabling, updating, or uninstalling)

Example: 5f9a7b2c3d4e5f6a7b8c9d0e

_connectorIdstring · objectIdRead-onlyOptional

Reference to the integration app that defines this resource.

This field is only populated for resources that are part of an integration app. It contains the unique identifier (_id) of the integration app (connector) that defines the structure, behavior, and templates for this resource.

The integration app is the published template that can be installed multiple times across different accounts, with each installation creating a separate integration instance (referenced by _integrationId).

This reference enables:

• Identifying the source integration app for this resource
• Determining which template version is being used
• Linking to documentation, support, and marketplace information

Example: 5e8d43a1b9e5a80011a35f1b

namestring · max: 100Required

Display name for the guardrail. May be empty if created without one.

Example: PII Scanner

descriptionstring · max: 5120Optional

Free-text note describing the guardrail's purpose.

Example: Scans records for PII and masks detected values before import.

adaptorTypestring · enumRequired

Always GuardrailImport for guardrails.

Example: GuardrailImportPossible values:

_connectionIdstring · objectIdOptional

BYOK connection backing an ai_agent guardrail. Absent when platform-managed credentials are used.

Example: 68ae48d6b5f755d2dd38c294

_sourceIdstring · objectIdRead-onlyOptional

Source guardrail this one was cloned from. Present only on clones.

Example: 69a886183b213b3ac90860fe

inputContextstring · enumOptional

Input shape for the guardrail's processing pipeline. Present when set; absence means record.

Example: recordPossible values:

apiIdentifierstringRead-onlyRequired

Ten-character hex identifier used to invoke the guardrail over HTTP.

Example: i894602e87

lookupsobject[]Required

Static lookup configurations. Guardrail (AI agent) imports support static lookups only; defaults to an empty array.

Example: []

mappingsobject[]Optional

Import field mappings. Each entry requires a status field. Typically empty for guardrails.

Example: []

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

422

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

application/json

put/v1/imports/{_id}

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

{
  "name": "PII Scanner",
  "adaptorType": "GuardrailImport",
  "guardrail": {
    "type": "pii",
    "confidenceThreshold": 0.8,
    "pii": {
      "entities": [
        "email_address",
        "phone_number",
        "credit_card_number"
      ],
      "mask": true
    }
  }
}

{
  "_id": "69eb9f5078dbae2f1bb05f89",
  "createdAt": "2026-04-24T16:50:24.073Z",
  "lastModified": "2026-05-02T16:12:08.114Z",
  "name": "PII Scanner",
  "apiIdentifier": "i39ee734f7",
  "sandbox": false,
  "lookups": [],
  "adaptorType": "GuardrailImport",
  "guardrail": {
    "type": "pii",
    "confidenceThreshold": 0.8,
    "pii": {
      "entities": [
        "email_address",
        "phone_number",
        "credit_card_number"
      ],
      "mask": true
    }
  }
}

Delete a guardrail

delete

/v1/imports/{_id}

Deletes a guardrail import. Soft-deleted and retained in the recycle bin for 30 days before permanent removal.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

The unique identifier of the guardrail import

Example: 5f8d43a1b9e5a80011a35f2c

Responses

204

Guardrail deleted 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

The resource has dependents that must be deleted first. Each entry in the errors array names one blocking resource.

application/json

delete/v1/imports/{_id}

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

No content

List dependencies of a guardrail

get

/v1/imports/{_id}/dependencies

Returns the set of resources that depend on the specified guardrail import. 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 other resources depend on the target. This is 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: 66a1f2c3b4d5e6f7a8b9c0d1

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/imports/{_id}/dependencies

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

{}