AI Agents

AI agents are LLM-powered import steps that classify, extract, validate, or generate data within integration flows. They are stored as import resources with adaptorType: AiAgentImport and managed via the /v1/imports endpoints.

Three built-in providers — OpenAI (via the Responses API), Google Gemini (via LiteLLM), and Anthropic Claude (via LiteLLM) — run on platform-managed credentials or, with a _connectionId, on your own key (BYOK). Catalog providers — Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq — use one generic flat configuration format and always run on a BYOK connection.

AI agent schema

List AI agents

get

/v1/imports

Returns all imports in the account. The response includes every import type, not just AI agents — filter client-side by adaptorType: "AiAgentImport".

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

afterstringOptional

Opaque cursor for forward pagination. Pass the value from the Link response header (rel="next") to fetch the next page.

limitinteger · min: 1 · max: 1000Optional

Maximum number of imports to return per page.

Default: 1000

Responses

200

Array of import objects.

application/json

204

No imports exist in the account.

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

get/v1/imports

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

[
  {
    "_id": "69af00be3b213b3ac9dff10d",
    "name": "AI AR agent specialist",
    "description": "Reads incoming emails and determines actions to execute.",
    "adaptorType": "AiAgentImport",
    "_connectionId": "662aaa6576bf4040548dbbe4",
    "apiIdentifier": "i0e9c706d0",
    "lookups": [],
    "aiAgent": {
      "provider": "openai",
      "openai": {
        "model": "gpt-4.1",
        "instructions": "You process inbound AR emails and create a Gmail draft reply.",
        "maxOutputTokens": 1000,
        "serviceTier": "default",
        "reasoning": {
          "effort": "medium"
        },
        "output": {
          "format": {
            "type": "json_schema",
            "name": "agent-response",
            "strict": false,
            "jsonSchema": {
              "type": "object",
              "properties": {
                "action": {
                  "type": "string"
                },
                "draftBody": {
                  "type": "string"
                }
              },
              "required": [
                "action"
              ]
            }
          },
          "verbose": "medium"
        },
        "tools": [
          {
            "type": "mcp",
            "mcp": {
              "_mcpConnectionId": "66a1b2c3d4e5f60011a35f2c"
            }
          }
        ]
      }
    },
    "createdAt": "2026-03-09T17:17:50.501Z",
    "lastModified": "2026-04-20T18:01:04.731Z"
  }
]

Create an AI agent

post

/v1/imports

Creates a new AI agent import. The provider decides the configuration format: aiAgent.openai for OpenAI, aiAgent.litellm for Gemini and Anthropic Claude, or the generic flat format (aiAgent.model, aiAgent.modelOptions, …) for the catalog providers Mistral, xAI, Hugging Face, DeepSeek, Cohere, and Groq — a block that does not match the provider is rejected. For a built-in provider, omit _connectionId to use platform-managed credentials or include it for BYOK; a catalog provider needs a BYOK connection to save — without one the request fails with 422 connection_required on _connectionId.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Configuration for an AI agent import. Set aiAgent.provider to choose the LLM backend, then configure the matching format: aiAgent.openai for OpenAI, aiAgent.litellm for Gemini and Anthropic Claude, or the generic flat format (aiAgent.model, aiAgent.modelOptions, …) for the catalog providers. Omit _connectionId to use platform-managed credentials on a built-in provider; catalog providers need a BYOK connection to run.

namestring · min: 1 · max: 100Required

Display name for the AI agent.

Example: Customer Classifier

descriptionstringOptional

Optional description of the AI agent's purpose.

Example: Classifies incoming support tickets by category and priority.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API. Optional for the built-in providers (openai, gemini, anthropic), which run on platform-managed credentials when it is omitted. Catalog providers (mistral, xai, huggingface, deepseek, cohere, groq) have no platform-managed credentials: the save requires it — without one the agent fails to save with 422 connection_required on _connectionId.

Example: 662aaa6576bf4040548dbbe4

_integrationIdstring · objectIdOptional

Integration this AI agent belongs to. Omitted for a standalone agent.

Example: 5d4f9b8e2c1a4b3f6e7d8c90

adaptorTypestring · enumRequired

Must be AiAgentImport.

Possible values:

_connectorIdstring · objectIdOptional

Connector this AI agent was created from, set when it is part of an installed integration app.

Example: 69e72db5f4b94414c88ebfa1

inputContextstring · enumOptional

Selects the data context that mappings[].extract evaluates against. With no mappings the agent receives the entire record and inputContext is moot. record (the default) extracts against the flat record; envelope extracts against the runtime envelope, which exposes the record alongside job, settings, and other run-time metadata ($.record.field, $.settings.field, etc.). Same contract as the import resource's inputContext.

Possible values:

oneToManybooleanOptional

When true, the step runs once per child record instead of once per incoming record. pathToMany names the array field that holds the children inside an object record; when the incoming record is itself an array (grouped or row-based data), leave pathToMany blank and each element becomes a record. The fan-out is scoped to this step: afterwards the children are re-joined into the record's original shape — the object with its array, or the array of rows — carrying any response-mapping enrichment, and that re-joined record is what the next step receives. Not for locating records in an export's HTTP response; use http.response.resourcePath for that. Applies to steps that receive a record — imports and lookups (an export referenced as a page processor of a flow, API, or Tool). A standalone export (a flow's page generator) has no incoming record, so the fields are saved but have no effect on the records it produces; to emit one record per array element from a standalone export, use a hooks.preSavePage script, or for a file-definition export make the repeating segment the record boundary in the definition's rules.

Default: falseExample: true

pathToManystringOptional

Path to the array of child records inside an object record when oneToMany is true, in dot notation (items, lines.lineItems). Leave blank when the incoming record is itself an array (grouped or row-based data) — each element is then a child record. A path that does not resolve to an array processes zero records and reports success. Read only on steps that receive a record (imports, lookup exports); on a standalone export it is saved and ignored — see oneToMany.

Example: items

distributedbooleanOptional

Always false for AI agent imports — the agent executes on Celigo's servers, not inside a target application.

maxAttemptsnumberOptional

Maximum number of attempts made to deliver a record before it is marked as failed.

ignoreExistingbooleanOptional

When true, records that already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

ignoreMissingbooleanOptional

When true, records that do not already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

Responses

201

Created AI agent.

application/json

AI agent import object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the AI agent.

Example: Customer Classifier

descriptionstringOptional

Optional description of the AI agent's purpose.

Example: Classifies incoming support tickets by category and priority.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API. Optional for the built-in providers (openai, gemini, anthropic), which run on platform-managed credentials when it is omitted. Catalog providers (mistral, xai, huggingface, deepseek, cohere, groq) have no platform-managed credentials: the save requires it — without one the agent fails to save with 422 connection_required on _connectionId.

Example: 662aaa6576bf4040548dbbe4

_integrationIdstring · objectIdOptional

Integration this AI agent belongs to. Omitted for a standalone agent.

Example: 5d4f9b8e2c1a4b3f6e7d8c90

adaptorTypestring · enumRequired

Must be AiAgentImport.

Possible values:

_connectorIdstring · objectIdOptional

Connector this AI agent was created from, set when it is part of an installed integration app.

Example: 69e72db5f4b94414c88ebfa1

inputContextstring · enumOptional

Selects the data context that mappings[].extract evaluates against. With no mappings the agent receives the entire record and inputContext is moot. record (the default) extracts against the flat record; envelope extracts against the runtime envelope, which exposes the record alongside job, settings, and other run-time metadata ($.record.field, $.settings.field, etc.). Same contract as the import resource's inputContext.

Possible values:

oneToManybooleanOptional

When true, the step runs once per child record instead of once per incoming record. pathToMany names the array field that holds the children inside an object record; when the incoming record is itself an array (grouped or row-based data), leave pathToMany blank and each element becomes a record. The fan-out is scoped to this step: afterwards the children are re-joined into the record's original shape — the object with its array, or the array of rows — carrying any response-mapping enrichment, and that re-joined record is what the next step receives. Not for locating records in an export's HTTP response; use http.response.resourcePath for that. Applies to steps that receive a record — imports and lookups (an export referenced as a page processor of a flow, API, or Tool). A standalone export (a flow's page generator) has no incoming record, so the fields are saved but have no effect on the records it produces; to emit one record per array element from a standalone export, use a hooks.preSavePage script, or for a file-definition export make the repeating segment the record boundary in the definition's rules.

Default: falseExample: true

pathToManystringOptional

Path to the array of child records inside an object record when oneToMany is true, in dot notation (items, lines.lineItems). Leave blank when the incoming record is itself an array (grouped or row-based data) — each element is then a child record. A path that does not resolve to an array processes zero records and reports success. Read only on steps that receive a record (imports, lookup exports); on a standalone export it is saved and ignored — see oneToMany.

Example: items

distributedbooleanOptional

Always false for AI agent imports — the agent executes on Celigo's servers, not inside a target application.

maxAttemptsnumberOptional

Maximum number of attempts made to deliver a record before it is marked as failed.

ignoreExistingbooleanOptional

When true, records that already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

ignoreMissingbooleanOptional

When true, records that do not already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

_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

_sourceIdstring · objectIdRead-onlyOptional

Export that feeds data into this import within a flow.

Example: 5d4f9b8e2c1a4b3f6e7d8c91

apiIdentifierstringRead-onlyOptional

Ten-character hex identifier for the resource.

Example: i0e9c706d0

lookupsobject[]Read-onlyOptional

Lookup configurations associated with this import.

_templateIdstring · objectIdRead-onlyOptional

Template this AI agent was created from.

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft version of this AI agent expires. Drafts are staged by Celigo Ora (the platform's AI assistant) when it proposes changes for review; this field is present only while an unapproved Ora draft is pending.

debugUntilstring · date-timeRead-onlyOptional

Timestamp until which verbose debug logging runs for this AI agent. Read-only on create/update; enable it through the debug PATCH endpoint, not a full update.

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: 186

{
  "name": "Customer Classifier",
  "adaptorType": "AiAgentImport",
  "aiAgent": {
    "provider": "openai",
    "openai": {
      "model": "gpt-4.1-nano",
      "instructions": "Classify each incoming record by category."
    }
  }
}

{
  "_id": "69af00be3b213b3ac9dff10d",
  "name": "Customer Classifier",
  "adaptorType": "AiAgentImport",
  "apiIdentifier": "i0e9c706d0",
  "lookups": [],
  "aiAgent": {
    "provider": "openai",
    "openai": {
      "model": "gpt-4.1-nano",
      "instructions": "Classify each incoming record by category.",
      "maxOutputTokens": 5000,
      "serviceTier": "default",
      "output": {
        "format": {
          "type": "text",
          "strict": false
        },
        "verbose": "medium"
      },
      "tools": []
    }
  },
  "createdAt": "2026-03-09T17:17:50.501Z",
  "lastModified": "2026-03-09T17:17:50.501Z"
}

Get an AI agent

get

/v1/imports/{_id}

Returns the full configuration of a single AI agent import.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Import resource ID.

Example: 69af00be3b213b3ac9dff10d

Responses

200

AI agent import object.

application/json

AI agent import object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the AI agent.

Example: Customer Classifier

descriptionstringOptional

Optional description of the AI agent's purpose.

Example: Classifies incoming support tickets by category and priority.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API. Optional for the built-in providers (openai, gemini, anthropic), which run on platform-managed credentials when it is omitted. Catalog providers (mistral, xai, huggingface, deepseek, cohere, groq) have no platform-managed credentials: the save requires it — without one the agent fails to save with 422 connection_required on _connectionId.

Example: 662aaa6576bf4040548dbbe4

_integrationIdstring · objectIdOptional

Integration this AI agent belongs to. Omitted for a standalone agent.

Example: 5d4f9b8e2c1a4b3f6e7d8c90

adaptorTypestring · enumRequired

Must be AiAgentImport.

Possible values:

_connectorIdstring · objectIdOptional

Connector this AI agent was created from, set when it is part of an installed integration app.

Example: 69e72db5f4b94414c88ebfa1

inputContextstring · enumOptional

Selects the data context that mappings[].extract evaluates against. With no mappings the agent receives the entire record and inputContext is moot. record (the default) extracts against the flat record; envelope extracts against the runtime envelope, which exposes the record alongside job, settings, and other run-time metadata ($.record.field, $.settings.field, etc.). Same contract as the import resource's inputContext.

Possible values:

oneToManybooleanOptional

When true, the step runs once per child record instead of once per incoming record. pathToMany names the array field that holds the children inside an object record; when the incoming record is itself an array (grouped or row-based data), leave pathToMany blank and each element becomes a record. The fan-out is scoped to this step: afterwards the children are re-joined into the record's original shape — the object with its array, or the array of rows — carrying any response-mapping enrichment, and that re-joined record is what the next step receives. Not for locating records in an export's HTTP response; use http.response.resourcePath for that. Applies to steps that receive a record — imports and lookups (an export referenced as a page processor of a flow, API, or Tool). A standalone export (a flow's page generator) has no incoming record, so the fields are saved but have no effect on the records it produces; to emit one record per array element from a standalone export, use a hooks.preSavePage script, or for a file-definition export make the repeating segment the record boundary in the definition's rules.

Default: falseExample: true

pathToManystringOptional

Path to the array of child records inside an object record when oneToMany is true, in dot notation (items, lines.lineItems). Leave blank when the incoming record is itself an array (grouped or row-based data) — each element is then a child record. A path that does not resolve to an array processes zero records and reports success. Read only on steps that receive a record (imports, lookup exports); on a standalone export it is saved and ignored — see oneToMany.

Example: items

distributedbooleanOptional

Always false for AI agent imports — the agent executes on Celigo's servers, not inside a target application.

maxAttemptsnumberOptional

Maximum number of attempts made to deliver a record before it is marked as failed.

ignoreExistingbooleanOptional

When true, records that already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

ignoreMissingbooleanOptional

When true, records that do not already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

_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

_sourceIdstring · objectIdRead-onlyOptional

Export that feeds data into this import within a flow.

Example: 5d4f9b8e2c1a4b3f6e7d8c91

apiIdentifierstringRead-onlyOptional

Ten-character hex identifier for the resource.

Example: i0e9c706d0

lookupsobject[]Read-onlyOptional

Lookup configurations associated with this import.

_templateIdstring · objectIdRead-onlyOptional

Template this AI agent was created from.

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft version of this AI agent expires. Drafts are staged by Celigo Ora (the platform's AI assistant) when it proposes changes for review; this field is present only while an unapproved Ora draft is pending.

debugUntilstring · date-timeRead-onlyOptional

Timestamp until which verbose debug logging runs for this AI agent. Read-only on create/update; enable it through the debug PATCH endpoint, not a full update.

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": "69af00be3b213b3ac9dff10d",
  "name": "AI AR agent specialist",
  "description": "Reads incoming emails and determines actions to execute.",
  "adaptorType": "AiAgentImport",
  "_connectionId": "662aaa6576bf4040548dbbe4",
  "apiIdentifier": "i0e9c706d0",
  "lookups": [],
  "aiAgent": {
    "provider": "openai",
    "openai": {
      "model": "gpt-4.1",
      "instructions": "You process inbound AR emails and create a Gmail draft reply.",
      "maxOutputTokens": 1000,
      "serviceTier": "default",
      "reasoning": {
        "effort": "medium"
      },
      "output": {
        "format": {
          "type": "json_schema",
          "name": "agent-response",
          "strict": false,
          "jsonSchema": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string"
              },
              "draftBody": {
                "type": "string"
              }
            },
            "required": [
              "action"
            ]
          }
        },
        "verbose": "medium"
      },
      "tools": [
        {
          "type": "mcp",
          "mcp": {
            "_mcpConnectionId": "66a1b2c3d4e5f60011a35f2c"
          }
        }
      ]
    }
  },
  "createdAt": "2026-03-09T17:17:50.501Z",
  "lastModified": "2026-04-20T18:01:04.731Z"
}

Update an AI agent

put

/v1/imports/{_id}

Replaces the full configuration of an AI agent import.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Import resource ID.

Example: 69af00be3b213b3ac9dff10d

Body

Configuration for an AI agent import. Set aiAgent.provider to choose the LLM backend, then configure the matching format: aiAgent.openai for OpenAI, aiAgent.litellm for Gemini and Anthropic Claude, or the generic flat format (aiAgent.model, aiAgent.modelOptions, …) for the catalog providers. Omit _connectionId to use platform-managed credentials on a built-in provider; catalog providers need a BYOK connection to run.

namestring · min: 1 · max: 100Required

Display name for the AI agent.

Example: Customer Classifier

descriptionstringOptional

Optional description of the AI agent's purpose.

Example: Classifies incoming support tickets by category and priority.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API. Optional for the built-in providers (openai, gemini, anthropic), which run on platform-managed credentials when it is omitted. Catalog providers (mistral, xai, huggingface, deepseek, cohere, groq) have no platform-managed credentials: the save requires it — without one the agent fails to save with 422 connection_required on _connectionId.

Example: 662aaa6576bf4040548dbbe4

_integrationIdstring · objectIdOptional

Integration this AI agent belongs to. Omitted for a standalone agent.

Example: 5d4f9b8e2c1a4b3f6e7d8c90

adaptorTypestring · enumRequired

Must be AiAgentImport.

Possible values:

_connectorIdstring · objectIdOptional

Connector this AI agent was created from, set when it is part of an installed integration app.

Example: 69e72db5f4b94414c88ebfa1

inputContextstring · enumOptional

Selects the data context that mappings[].extract evaluates against. With no mappings the agent receives the entire record and inputContext is moot. record (the default) extracts against the flat record; envelope extracts against the runtime envelope, which exposes the record alongside job, settings, and other run-time metadata ($.record.field, $.settings.field, etc.). Same contract as the import resource's inputContext.

Possible values:

oneToManybooleanOptional

When true, the step runs once per child record instead of once per incoming record. pathToMany names the array field that holds the children inside an object record; when the incoming record is itself an array (grouped or row-based data), leave pathToMany blank and each element becomes a record. The fan-out is scoped to this step: afterwards the children are re-joined into the record's original shape — the object with its array, or the array of rows — carrying any response-mapping enrichment, and that re-joined record is what the next step receives. Not for locating records in an export's HTTP response; use http.response.resourcePath for that. Applies to steps that receive a record — imports and lookups (an export referenced as a page processor of a flow, API, or Tool). A standalone export (a flow's page generator) has no incoming record, so the fields are saved but have no effect on the records it produces; to emit one record per array element from a standalone export, use a hooks.preSavePage script, or for a file-definition export make the repeating segment the record boundary in the definition's rules.

Default: falseExample: true

pathToManystringOptional

Path to the array of child records inside an object record when oneToMany is true, in dot notation (items, lines.lineItems). Leave blank when the incoming record is itself an array (grouped or row-based data) — each element is then a child record. A path that does not resolve to an array processes zero records and reports success. Read only on steps that receive a record (imports, lookup exports); on a standalone export it is saved and ignored — see oneToMany.

Example: items

distributedbooleanOptional

Always false for AI agent imports — the agent executes on Celigo's servers, not inside a target application.

maxAttemptsnumberOptional

Maximum number of attempts made to deliver a record before it is marked as failed.

ignoreExistingbooleanOptional

When true, records that already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

ignoreMissingbooleanOptional

When true, records that do not already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

Responses

200

Updated AI agent.

application/json

AI agent import object as returned by the API.

namestring · min: 1 · max: 100Required

Display name for the AI agent.

Example: Customer Classifier

descriptionstringOptional

Optional description of the AI agent's purpose.

Example: Classifies incoming support tickets by category and priority.

_connectionIdstring · objectIdOptional

Connection for BYOK (bring your own key) — an HTTP connection to the vendor's API. Optional for the built-in providers (openai, gemini, anthropic), which run on platform-managed credentials when it is omitted. Catalog providers (mistral, xai, huggingface, deepseek, cohere, groq) have no platform-managed credentials: the save requires it — without one the agent fails to save with 422 connection_required on _connectionId.

Example: 662aaa6576bf4040548dbbe4

_integrationIdstring · objectIdOptional

Integration this AI agent belongs to. Omitted for a standalone agent.

Example: 5d4f9b8e2c1a4b3f6e7d8c90

adaptorTypestring · enumRequired

Must be AiAgentImport.

Possible values:

_connectorIdstring · objectIdOptional

Connector this AI agent was created from, set when it is part of an installed integration app.

Example: 69e72db5f4b94414c88ebfa1

inputContextstring · enumOptional

Selects the data context that mappings[].extract evaluates against. With no mappings the agent receives the entire record and inputContext is moot. record (the default) extracts against the flat record; envelope extracts against the runtime envelope, which exposes the record alongside job, settings, and other run-time metadata ($.record.field, $.settings.field, etc.). Same contract as the import resource's inputContext.

Possible values:

oneToManybooleanOptional

When true, the step runs once per child record instead of once per incoming record. pathToMany names the array field that holds the children inside an object record; when the incoming record is itself an array (grouped or row-based data), leave pathToMany blank and each element becomes a record. The fan-out is scoped to this step: afterwards the children are re-joined into the record's original shape — the object with its array, or the array of rows — carrying any response-mapping enrichment, and that re-joined record is what the next step receives. Not for locating records in an export's HTTP response; use http.response.resourcePath for that. Applies to steps that receive a record — imports and lookups (an export referenced as a page processor of a flow, API, or Tool). A standalone export (a flow's page generator) has no incoming record, so the fields are saved but have no effect on the records it produces; to emit one record per array element from a standalone export, use a hooks.preSavePage script, or for a file-definition export make the repeating segment the record boundary in the definition's rules.

Default: falseExample: true

pathToManystringOptional

Path to the array of child records inside an object record when oneToMany is true, in dot notation (items, lines.lineItems). Leave blank when the incoming record is itself an array (grouped or row-based data) — each element is then a child record. A path that does not resolve to an array processes zero records and reports success. Read only on steps that receive a record (imports, lookup exports); on a standalone export it is saved and ignored — see oneToMany.

Example: items

distributedbooleanOptional

Always false for AI agent imports — the agent executes on Celigo's servers, not inside a target application.

maxAttemptsnumberOptional

Maximum number of attempts made to deliver a record before it is marked as failed.

ignoreExistingbooleanOptional

When true, records that already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

ignoreMissingbooleanOptional

When true, records that do not already exist in the destination are silently skipped. Rarely meaningful for AI agents; accepted for import-surface parity.

_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

_sourceIdstring · objectIdRead-onlyOptional

Export that feeds data into this import within a flow.

Example: 5d4f9b8e2c1a4b3f6e7d8c91

apiIdentifierstringRead-onlyOptional

Ten-character hex identifier for the resource.

Example: i0e9c706d0

lookupsobject[]Read-onlyOptional

Lookup configurations associated with this import.

_templateIdstring · objectIdRead-onlyOptional

Template this AI agent was created from.

draftExpiresAtstring · date-timeRead-onlyOptional

When the draft version of this AI agent expires. Drafts are staged by Celigo Ora (the platform's AI assistant) when it proposes changes for review; this field is present only while an unapproved Ora draft is pending.

debugUntilstring · date-timeRead-onlyOptional

Timestamp until which verbose debug logging runs for this AI agent. Read-only on create/update; enable it through the debug PATCH endpoint, not a full update.

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/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: 199

{
  "name": "Customer Classifier",
  "adaptorType": "AiAgentImport",
  "aiAgent": {
    "provider": "openai",
    "openai": {
      "model": "gpt-4.1-nano",
      "instructions": "Classify each incoming record by category and priority."
    }
  }
}

{
  "_id": "69af00be3b213b3ac9dff10d",
  "name": "Customer Classifier",
  "adaptorType": "AiAgentImport",
  "apiIdentifier": "i0e9c706d0",
  "lookups": [],
  "aiAgent": {
    "provider": "openai",
    "openai": {
      "model": "gpt-4.1-nano",
      "instructions": "Classify each incoming record by category and priority.",
      "maxOutputTokens": 5000,
      "serviceTier": "default",
      "output": {
        "format": {
          "type": "text",
          "strict": false
        },
        "verbose": "medium"
      },
      "tools": []
    }
  },
  "createdAt": "2026-03-09T17:17:50.501Z",
  "lastModified": "2026-03-10T09:14:21.330Z"
}

Delete an AI agent

delete

/v1/imports/{_id}

Deletes an AI agent 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

Import resource ID.

Example: 69af00be3b213b3ac9dff10d

Responses

204

AI agent 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

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

Preview and compare AI agent configurations

post

/v1/imports/preview/compare

Runs one or more AI agent import configurations against the same input data and returns the LLM response, token usage, and timing for each. No job is created and no state is updated — this is a stateless preview.

The UI uses this to compare model or prompt variations side-by-side before saving. Each entry in imports is a full import object (the same shape returned by GET /v1/imports/{_id}) with the aiAgent block configured for the variant being tested.

Each entry in imports must include adaptorType: "AiAgentImport" and a valid aiAgent configuration. A _connectionId is required unless the agent is on a built-in provider (openai, gemini, anthropic) using platform-managed credentials — catalog providers always need one, since the preview runs the model. The response array is positional — response[i] corresponds to imports[i]. A per-entry statusCode: 422 with errors means that specific configuration failed, not that the overall request failed.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Request body for comparing AI agent configurations side-by-side. Each entry in imports is a full import object with adaptorType: "AiAgentImport". The same _id can appear in multiple entries with different aiAgent settings to compare model or prompt variants.

Responses

200

Array of results, one per import entry. Each result contains the LLM response text, structured output, token usage, and timing.

application/json

Result of running a single AI agent configuration against the input data.

statusCodeintegerOptional

HTTP-style status code for this entry. 200 on success, 422 on configuration or provider error.

Example: 200

_textstring · nullableOptional

Free-form text response from the LLM. Present when output.format.type is text.

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

One or more import entries failed validation — e.g. a required aiAgent field is missing. The body is the same positional results array as a 200 response; each failing entry carries statusCode: 422 and an errors array instead of LLM output.

application/json

post/v1/imports/preview/compare

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

{
  "imports": [
    {
      "name": "testtest",
      "adaptorType": "AiAgentImport",
      "_connectionId": "68ae48d6b5f755d2dd38c294",
      "aiAgent": {
        "provider": "openai",
        "openai": {
          "model": "gpt-4.1-mini",
          "instructions": "Classify this support ticket by category.",
          "temperature": 1,
          "maxOutputTokens": 5000,
          "serviceTier": "default",
          "output": {
            "format": {
              "type": "text"
            },
            "verbose": "medium"
          }
        }
      }
    },
    {
      "name": "testtest",
      "adaptorType": "AiAgentImport",
      "_connectionId": "68ae48d6b5f755d2dd38c294",
      "aiAgent": {
        "provider": "openai",
        "openai": {
          "model": "gpt-4.1",
          "instructions": "Classify this support ticket by category.",
          "temperature": 1,
          "maxOutputTokens": 5000,
          "serviceTier": "auto",
          "output": {
            "format": {
              "type": "text"
            },
            "verbose": "medium"
          }
        }
      }
    }
  ],
  "data": {
    "subject": "Cannot log in",
    "body": "I keep getting a 403 error when trying to access my dashboard."
  }
}

[
  {
    "statusCode": 200,
    "_json": {},
    "_text": "Category: Technical Support\nPriority: High",
    "usage": {
      "input_tokens": 307,
      "output_tokens": 20,
      "total_tokens": 327,
      "service_tier": "default",
      "model": "gpt-4.1-mini-2025-04-14",
      "total_cost": 0
    },
    "timing": {
      "total_request_time": 1.997
    }
  },
  {
    "statusCode": 200,
    "_json": {},
    "_text": "Category: Technical Support — Authentication\nPriority: High\nSuggested action: Check SSO configuration and session token validity.",
    "usage": {
      "input_tokens": 307,
      "output_tokens": 38,
      "total_tokens": 345,
      "service_tier": "auto",
      "model": "gpt-4.1",
      "total_cost": 0
    },
    "timing": {
      "total_request_time": 2.451
    }
  }
]

List dependencies of an AI agent

get

/v1/imports/{_id}/dependencies

Returns resources that depend on this AI agent import. Keys are resource types (e.g. flows); values are arrays of dependency entries.

Check dependencies before deleting — the DELETE endpoint is blocked if dependents exist. Returns {} for both zero-dependency and nonexistent IDs.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Import resource ID.

Responses

200

Dependency map. 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: */*

{}