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 providers are supported — OpenAI (via the Responses API), Google Gemini (via LiteLLM), and Anthropic Claude (via LiteLLM). A _connectionId is optional: omit it to use platform-managed credentials, or supply one for BYOK (bring your own key).

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"
          },
          "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. Omit _connectionId to use platform-managed credentials; include it for BYOK. Configure the provider-specific block (aiAgent.openai or aiAgent.litellm) — the other block is ignored.

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 block: aiAgent.openai for OpenAI, or aiAgent.litellm for Gemini and Anthropic Claude. Omit _connectionId to use platform-managed credentials.

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). Optional — platform-managed credentials are used when omitted.

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

Controls whether the resource treats child records within parent records as the primary data units.

Important: this is not for specifying where records are in an api response

If you need to tell an export where to find the array of records in the HTTP response body (e.g. "the records are at data.items"), use http.response.resourcePath instead. oneToMany serves a completely different purpose — it operates on records that have already been extracted from the response.

What oneToMany actually does

When set to true, this field fundamentally changes how record data is processed:

• The system will "unwrap" nested child records from their parent containers
• Each child record becomes a separate output record for downstream processing
• The pathToMany field must be set to indicate where these child records are located
• Parent record fields can still be accessed via a special "parent" context

This is typically used on lookup exports (isLookup: true) or imports where the incoming records contain nested arrays that need to be fanned out.

Common scenarios for enabling this option:

• Processing order line items individually from an order export
• Handling invoice line items from an invoice export
• Processing individual transaction lines from journal entries
• Extracting address records from customer exports

This setting applies for the duration of the current flow step only and does not affect how data is stored or structured in other flow steps.

If false (default), the resource processes each top-level record as a single unit.

Default: falseExample: true

pathToManystringOptional

Specifies the JSON path to child records when oneToMany mode is enabled.

This field is only used when oneToMany is set to true. It defines the exact location of child records within the parent record structure using dot notation:

• Simple path: "items" for a direct child array field
• Nested path: "lines.lineItems" for a more deeply nested array
• Multi-level: "details.items.subitems" for deeply nested structures

The system uses this path to:

• Locate the array of child records within each parent record
• Extract each array element as a separate record for processing
• Make both the child record data and parent context available to downstream steps

Important considerations:

• The path must point to an array field
• For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
• If the path is invalid or doesn't exist, the resource will report success but process zero records
• Maximum path depth: 10 levels

This field must contain a valid JSON path expression using dot notation.

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.

blobbooleanOptional

When true, the agent processes raw file content (blobs) rather than structured records.

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). Optional — platform-managed credentials are used when omitted.

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

Controls whether the resource treats child records within parent records as the primary data units.

Important: this is not for specifying where records are in an api response

If you need to tell an export where to find the array of records in the HTTP response body (e.g. "the records are at data.items"), use http.response.resourcePath instead. oneToMany serves a completely different purpose — it operates on records that have already been extracted from the response.

What oneToMany actually does

When set to true, this field fundamentally changes how record data is processed:

• The system will "unwrap" nested child records from their parent containers
• Each child record becomes a separate output record for downstream processing
• The pathToMany field must be set to indicate where these child records are located
• Parent record fields can still be accessed via a special "parent" context

This is typically used on lookup exports (isLookup: true) or imports where the incoming records contain nested arrays that need to be fanned out.

Common scenarios for enabling this option:

• Processing order line items individually from an order export
• Handling invoice line items from an invoice export
• Processing individual transaction lines from journal entries
• Extracting address records from customer exports

This setting applies for the duration of the current flow step only and does not affect how data is stored or structured in other flow steps.

If false (default), the resource processes each top-level record as a single unit.

Default: falseExample: true

pathToManystringOptional

Specifies the JSON path to child records when oneToMany mode is enabled.

This field is only used when oneToMany is set to true. It defines the exact location of child records within the parent record structure using dot notation:

• Simple path: "items" for a direct child array field
• Nested path: "lines.lineItems" for a more deeply nested array
• Multi-level: "details.items.subitems" for deeply nested structures

The system uses this path to:

• Locate the array of child records within each parent record
• Extract each array element as a separate record for processing
• Make both the child record data and parent context available to downstream steps

Important considerations:

• The path must point to an array field
• For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
• If the path is invalid or doesn't exist, the resource will report success but process zero records
• Maximum path depth: 10 levels

This field must contain a valid JSON path expression using dot notation.

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.

blobbooleanOptional

When true, the agent processes raw file content (blobs) rather than structured records.

_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). Optional — platform-managed credentials are used when omitted.

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

Controls whether the resource treats child records within parent records as the primary data units.

Important: this is not for specifying where records are in an api response

If you need to tell an export where to find the array of records in the HTTP response body (e.g. "the records are at data.items"), use http.response.resourcePath instead. oneToMany serves a completely different purpose — it operates on records that have already been extracted from the response.

What oneToMany actually does

When set to true, this field fundamentally changes how record data is processed:

• The system will "unwrap" nested child records from their parent containers
• Each child record becomes a separate output record for downstream processing
• The pathToMany field must be set to indicate where these child records are located
• Parent record fields can still be accessed via a special "parent" context

This is typically used on lookup exports (isLookup: true) or imports where the incoming records contain nested arrays that need to be fanned out.

Common scenarios for enabling this option:

• Processing order line items individually from an order export
• Handling invoice line items from an invoice export
• Processing individual transaction lines from journal entries
• Extracting address records from customer exports

This setting applies for the duration of the current flow step only and does not affect how data is stored or structured in other flow steps.

If false (default), the resource processes each top-level record as a single unit.

Default: falseExample: true

pathToManystringOptional

Specifies the JSON path to child records when oneToMany mode is enabled.

This field is only used when oneToMany is set to true. It defines the exact location of child records within the parent record structure using dot notation:

• Simple path: "items" for a direct child array field
• Nested path: "lines.lineItems" for a more deeply nested array
• Multi-level: "details.items.subitems" for deeply nested structures

The system uses this path to:

• Locate the array of child records within each parent record
• Extract each array element as a separate record for processing
• Make both the child record data and parent context available to downstream steps

Important considerations:

• The path must point to an array field
• For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
• If the path is invalid or doesn't exist, the resource will report success but process zero records
• Maximum path depth: 10 levels

This field must contain a valid JSON path expression using dot notation.

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.

blobbooleanOptional

When true, the agent processes raw file content (blobs) rather than structured records.

_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"
        },
        "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 block: aiAgent.openai for OpenAI, or aiAgent.litellm for Gemini and Anthropic Claude. Omit _connectionId to use platform-managed credentials.

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). Optional — platform-managed credentials are used when omitted.

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

Controls whether the resource treats child records within parent records as the primary data units.

Important: this is not for specifying where records are in an api response

If you need to tell an export where to find the array of records in the HTTP response body (e.g. "the records are at data.items"), use http.response.resourcePath instead. oneToMany serves a completely different purpose — it operates on records that have already been extracted from the response.

What oneToMany actually does

When set to true, this field fundamentally changes how record data is processed:

• The system will "unwrap" nested child records from their parent containers
• Each child record becomes a separate output record for downstream processing
• The pathToMany field must be set to indicate where these child records are located
• Parent record fields can still be accessed via a special "parent" context

This is typically used on lookup exports (isLookup: true) or imports where the incoming records contain nested arrays that need to be fanned out.

Common scenarios for enabling this option:

• Processing order line items individually from an order export
• Handling invoice line items from an invoice export
• Processing individual transaction lines from journal entries
• Extracting address records from customer exports

This setting applies for the duration of the current flow step only and does not affect how data is stored or structured in other flow steps.

If false (default), the resource processes each top-level record as a single unit.

Default: falseExample: true

pathToManystringOptional

Specifies the JSON path to child records when oneToMany mode is enabled.

This field is only used when oneToMany is set to true. It defines the exact location of child records within the parent record structure using dot notation:

• Simple path: "items" for a direct child array field
• Nested path: "lines.lineItems" for a more deeply nested array
• Multi-level: "details.items.subitems" for deeply nested structures

The system uses this path to:

• Locate the array of child records within each parent record
• Extract each array element as a separate record for processing
• Make both the child record data and parent context available to downstream steps

Important considerations:

• The path must point to an array field
• For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
• If the path is invalid or doesn't exist, the resource will report success but process zero records
• Maximum path depth: 10 levels

This field must contain a valid JSON path expression using dot notation.

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.

blobbooleanOptional

When true, the agent processes raw file content (blobs) rather than structured records.

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). Optional — platform-managed credentials are used when omitted.

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

Controls whether the resource treats child records within parent records as the primary data units.

Important: this is not for specifying where records are in an api response

If you need to tell an export where to find the array of records in the HTTP response body (e.g. "the records are at data.items"), use http.response.resourcePath instead. oneToMany serves a completely different purpose — it operates on records that have already been extracted from the response.

What oneToMany actually does

When set to true, this field fundamentally changes how record data is processed:

• The system will "unwrap" nested child records from their parent containers
• Each child record becomes a separate output record for downstream processing
• The pathToMany field must be set to indicate where these child records are located
• Parent record fields can still be accessed via a special "parent" context

This is typically used on lookup exports (isLookup: true) or imports where the incoming records contain nested arrays that need to be fanned out.

Common scenarios for enabling this option:

• Processing order line items individually from an order export
• Handling invoice line items from an invoice export
• Processing individual transaction lines from journal entries
• Extracting address records from customer exports

This setting applies for the duration of the current flow step only and does not affect how data is stored or structured in other flow steps.

If false (default), the resource processes each top-level record as a single unit.

Default: falseExample: true

pathToManystringOptional

Specifies the JSON path to child records when oneToMany mode is enabled.

This field is only used when oneToMany is set to true. It defines the exact location of child records within the parent record structure using dot notation:

• Simple path: "items" for a direct child array field
• Nested path: "lines.lineItems" for a more deeply nested array
• Multi-level: "details.items.subitems" for deeply nested structures

The system uses this path to:

• Locate the array of child records within each parent record
• Extract each array element as a separate record for processing
• Make both the child record data and parent context available to downstream steps

Important considerations:

• The path must point to an array field
• For row-based data (i.e. where Celigo models this via an array or arrays of objects), this field is not required
• If the path is invalid or doesn't exist, the resource will report success but process zero records
• Maximum path depth: 10 levels

This field must contain a valid JSON path expression using dot notation.

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.

blobbooleanOptional

When true, the agent processes raw file content (blobs) rather than structured records.

_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 uses platform-managed credentials. 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: */*

{}