Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

APIs

APIs expose integration logic as HTTP endpoints that external systems can invoke.

Two modes:

  • Builder — visual configuration with request/response mapping, routing, and transformations

  • Script — custom JavaScript handler function for full control

Each API gets a public URL: https://api.integrator.io/apis/{version}/{relativeURI}

API schema

List APIs

get
/v1/apis

Returns all APIs configured in the account. No pagination -- every API is returned in a single response. Legacy script-mode APIs (created before the builder/script distinction) may omit type, version, and disabled. A 204 response means the account has zero APIs.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
limitinteger · min: 1Optional

Maximum number of records to return per page.

Example: 100
namestringOptional

Filter by name — a substring match, not an exact match. An empty value is ignored.

Example: Order
disabledbooleanOptional

Filter by the disabled flag.

afterstringOptional

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

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 APIs.

application/json
get/v1/apis
GET /v1/apis HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "68ae4264b5f755d2dd3796b4",
    "name": "Order Webhook",
    "type": "builder",
    "version": "v1",
    "disabled": false,
    "createdAt": "2025-08-26T23:25:24.107Z",
    "lastModified": "2026-04-07T03:48:20.795Z"
  },
  {
    "_id": "689212abe5118c1cabfb43b3",
    "name": "Custom Handler",
    "type": "script",
    "version": "v1",
    "disabled": false,
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest",
    "createdAt": "2025-08-05T14:18:19.583Z",
    "lastModified": "2025-08-05T14:18:42.626Z"
  }
]

Create an API

post
/v1/apis

Creates a new API. For script mode, include script._scriptId and script.function (the server also copies these to the top level in the response). For builder mode, builder.request is required (at minimum relativeURI and method).

Builder-mode APIs are created with logging: {"mode": "basic"} when the account license has logging enabled -- the request body cannot override this (logging is ignored on POST and PUT; change it afterwards with PATCH /v1/apis/{_id}).

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Request body for creating or updating an API.

For builder-mode APIs, populate the builder object (at minimum builder.request.relativeURI and builder.request.method); the script field is ignored. For script-mode APIs, populate script with _scriptId and function; the builder field is ignored. On PUT, send the complete object — omitted fields revert to defaults.

Set type explicitly to builder or script. The server infers script when type is omitted, but new APIs must declare it.

namestring · min: 1 · max: 100Required

Display name.

Example: Customer API
_integrationIdstring · objectIdOptional

Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).

Example: 5e9a8f7c6b3d2a0011c4e5f6
descriptionstringOptional

Optional description of the API's purpose.

Example: API for managing customer records in Salesforce
typestring · enumRequired

API mode. Cannot be changed after creation. Defaults to script when omitted on create; legacy script APIs created before builder mode may omit it on reads as well.

Default: scriptExample: builderPossible values:
versionstringOptional

Version segment of the public URL (/{version}/{relativeURI}).

Default: v1Example: v1Pattern: ^[a-zA-Z0-9\-_\.]+$
disabledbooleanOptional

When true, the API rejects all incoming requests.

Default: false
timeoutPeriodinteger · max: 120Optional

Request-timeout override in seconds (1–120). 0 is a sentinel meaning "use the 120-second default" — the server rewrites it on write, so a stored value is never 0.

Example: 120
traceKeyTemplatestring · max: 1024Optional

Handlebars template that computes each request's trace key from the request payload, used to correlate run-history entries with source records. Absent from responses until set.

Example: {{record.orderId}}
draftbooleanOptional

When true, this API is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

Responses
201

API created successfully

application/json

API resource. Shape varies by mode: builder-mode APIs carry type, version, disabled, and builder; script-mode APIs additionally carry script plus top-level _scriptId / function copies. Legacy script APIs (pre-builder era) omit type, version, disabled, and builder entirely.

namestring · min: 1 · max: 100Required

Display name.

Example: Customer API
_integrationIdstring · objectIdOptional

Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).

Example: 5e9a8f7c6b3d2a0011c4e5f6
descriptionstringOptional

Optional description of the API's purpose.

Example: API for managing customer records in Salesforce
typestring · enumOptional

API mode. Cannot be changed after creation. Defaults to script when omitted on create; legacy script APIs created before builder mode may omit it on reads as well.

Default: scriptExample: builderPossible values:
versionstringOptional

Version segment of the public URL (/{version}/{relativeURI}).

Default: v1Example: v1Pattern: ^[a-zA-Z0-9\-_\.]+$
disabledbooleanOptional

When true, the API rejects all incoming requests.

Default: false
timeoutPeriodinteger · max: 120Optional

Request-timeout override in seconds (1–120). 0 is a sentinel meaning "use the 120-second default" — the server rewrites it on write, so a stored value is never 0.

Example: 120
traceKeyTemplatestring · max: 1024Optional

Handlebars template that computes each request's trace key from the request payload, used to correlate run-history entries with source records. Absent from responses until set.

Example: {{record.orderId}}
draftbooleanOptional

When true, this API is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the API.

Example: 68ae4264b5f755d2dd3796b4
_apiGroupingIdstring · nullableRead-onlyOptional

API grouping this API belongs to. Set only via PUT /apis/grouping; the server ignores this field in POST/PUT bodies on this resource. May be null after ungrouping.

Example: 60a1b2c3d4e5f60012345678
_scriptIdstring · objectIdRead-onlyOptional

Top-level copy of script._scriptId. Present on script-mode and legacy script APIs for backward compatibility.

Example: 689212a2c42d988978e27a11
functionstringRead-onlyOptional

Top-level copy of script.function. Present on script-mode and legacy script APIs for backward compatibility.

Example: handleRequest
createdAtstring · date-timeRead-onlyRequired

Timestamp when the API was created.

Example: 2025-08-26T23:25:24.107Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the API was last modified.

Example: 2026-04-07T03:48:20.795Z
_templateIdstring · objectIdRead-onlyOptional

Template this API was created from. Present only on template-installed APIs.

Example: 60a2c4e6f321d800129a1a3c
draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft API auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z
post/v1/apis
POST /v1/apis HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "name": "Custom Handler",
  "type": "script",
  "script": {
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest"
  }
}
{
  "_id": "689212abe5118c1cabfb43b3",
  "name": "Custom Handler",
  "type": "script",
  "version": "v1",
  "disabled": false,
  "script": {
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest"
  },
  "_scriptId": "689212a2c42d988978e27a11",
  "function": "handleRequest",
  "createdAt": "2025-08-05T14:18:19.583Z",
  "lastModified": "2025-08-05T14:18:19.583Z"
}

List month-to-date API invocation counts

get
/v1/apis/usage

Returns one invocation-counter record per resource + method + relativeURI in the current month. Counts API-style invocations across every resource type that exposes an HTTP-callable endpoint: custom APIs (builder and script), individual exports/imports called via /invoke, virtual imports, and APIM-fronted invocations.

The endpoint aggregates -- it does not return one record per individual call. Each entry rolls up every invocation of that (resource, method, URI) triple in the current month. Counters reset on the 1st of each month; there is no pagination and no historical-months filter on this path.

ioInvocationCount bills against the Celigo subscription; apimInvocationCount is billed separately for external APIM passthrough. To find the resource behind a row, read metadata._resourceId (present for exports/imports) or parse the resource id out of relativeURI.

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

Usage breakdown for the current month. usages[] is empty when no endpoints have been invoked yet.

application/json

Month-to-date invocation counters for every API endpoint that has been called in the account. Returned by GET /v1/apis/usage. Each entry in usages[] represents one resource + method + relativeURI triple — the same export or import invoked via two different methods yields two entries. Counters are cumulative for the month named in month / year and reset on the 1st.

externalApimCountintegerOptional

Account-wide count of invocations that arrived through an external API Management layer (APIM) in front of integrator.io for the current month. Aggregate counterpart to the per-endpoint apimInvocationCount values in usages[]. Absent on some responses when the account has never been routed through an external APIM.

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

{
  "usages": [
    {
      "_id": "69d054b9be4ce14fb4112827",
      "method": "POST",
      "relativeURI": "/v1/exports/6878f4a43bc01652c09cdccc/invoke",
      "metadata": {
        "_resourceId": "6878f4a43bc01652c09cdccc",
        "name": "Get Contacts",
        "type": "export"
      },
      "month": 4,
      "year": 2026,
      "ioInvocationCount": 29,
      "apimInvocationCount": 0,
      "createdAt": "2026-04-04T00:00:57.285Z"
    }
  ]
}

Get an API

get
/v1/apis/{_id}

Returns the complete configuration of a specific API.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The unique identifier of the API

Example: 5f8d43a1b9e5a80011a35f2c
Responses
200

API retrieved successfully.

application/json

API resource. Shape varies by mode: builder-mode APIs carry type, version, disabled, and builder; script-mode APIs additionally carry script plus top-level _scriptId / function copies. Legacy script APIs (pre-builder era) omit type, version, disabled, and builder entirely.

namestring · min: 1 · max: 100Required

Display name.

Example: Customer API
_integrationIdstring · objectIdOptional

Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).

Example: 5e9a8f7c6b3d2a0011c4e5f6
descriptionstringOptional

Optional description of the API's purpose.

Example: API for managing customer records in Salesforce
typestring · enumOptional

API mode. Cannot be changed after creation. Defaults to script when omitted on create; legacy script APIs created before builder mode may omit it on reads as well.

Default: scriptExample: builderPossible values:
versionstringOptional

Version segment of the public URL (/{version}/{relativeURI}).

Default: v1Example: v1Pattern: ^[a-zA-Z0-9\-_\.]+$
disabledbooleanOptional

When true, the API rejects all incoming requests.

Default: false
timeoutPeriodinteger · max: 120Optional

Request-timeout override in seconds (1–120). 0 is a sentinel meaning "use the 120-second default" — the server rewrites it on write, so a stored value is never 0.

Example: 120
traceKeyTemplatestring · max: 1024Optional

Handlebars template that computes each request's trace key from the request payload, used to correlate run-history entries with source records. Absent from responses until set.

Example: {{record.orderId}}
draftbooleanOptional

When true, this API is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the API.

Example: 68ae4264b5f755d2dd3796b4
_apiGroupingIdstring · nullableRead-onlyOptional

API grouping this API belongs to. Set only via PUT /apis/grouping; the server ignores this field in POST/PUT bodies on this resource. May be null after ungrouping.

Example: 60a1b2c3d4e5f60012345678
_scriptIdstring · objectIdRead-onlyOptional

Top-level copy of script._scriptId. Present on script-mode and legacy script APIs for backward compatibility.

Example: 689212a2c42d988978e27a11
functionstringRead-onlyOptional

Top-level copy of script.function. Present on script-mode and legacy script APIs for backward compatibility.

Example: handleRequest
createdAtstring · date-timeRead-onlyRequired

Timestamp when the API was created.

Example: 2025-08-26T23:25:24.107Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the API was last modified.

Example: 2026-04-07T03:48:20.795Z
_templateIdstring · objectIdRead-onlyOptional

Template this API was created from. Present only on template-installed APIs.

Example: 60a2c4e6f321d800129a1a3c
draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft API auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z
get/v1/apis/{_id}
GET /v1/apis/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "689212abe5118c1cabfb43b3",
  "name": "Custom Handler",
  "type": "script",
  "version": "v1",
  "disabled": false,
  "script": {
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest"
  },
  "_scriptId": "689212a2c42d988978e27a11",
  "function": "handleRequest",
  "createdAt": "2025-08-05T14:18:19.583Z",
  "lastModified": "2025-08-05T14:18:42.626Z"
}

Update an API

put
/v1/apis/{_id}

Replaces the full API configuration. Send the complete object -- omitted fields revert to defaults, not their prior values. Read-only fields (_id, createdAt, lastModified) in the request body are ignored.

logging is also ignored -- silently: a PUT that includes logging succeeds with the stored value unchanged, and no error reveals that the change was dropped. Use PATCH /v1/apis/{_id} (paths /logging/mode, /logging/debugUntil) to change logging settings.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The unique identifier of the API

Example: 5f8d43a1b9e5a80011a35f2c
Body

Request body for creating or updating an API.

For builder-mode APIs, populate the builder object (at minimum builder.request.relativeURI and builder.request.method); the script field is ignored. For script-mode APIs, populate script with _scriptId and function; the builder field is ignored. On PUT, send the complete object — omitted fields revert to defaults.

Set type explicitly to builder or script. The server infers script when type is omitted, but new APIs must declare it.

namestring · min: 1 · max: 100Required

Display name.

Example: Customer API
_integrationIdstring · objectIdOptional

Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).

Example: 5e9a8f7c6b3d2a0011c4e5f6
descriptionstringOptional

Optional description of the API's purpose.

Example: API for managing customer records in Salesforce
typestring · enumRequired

API mode. Cannot be changed after creation. Defaults to script when omitted on create; legacy script APIs created before builder mode may omit it on reads as well.

Default: scriptExample: builderPossible values:
versionstringOptional

Version segment of the public URL (/{version}/{relativeURI}).

Default: v1Example: v1Pattern: ^[a-zA-Z0-9\-_\.]+$
disabledbooleanOptional

When true, the API rejects all incoming requests.

Default: false
timeoutPeriodinteger · max: 120Optional

Request-timeout override in seconds (1–120). 0 is a sentinel meaning "use the 120-second default" — the server rewrites it on write, so a stored value is never 0.

Example: 120
traceKeyTemplatestring · max: 1024Optional

Handlebars template that computes each request's trace key from the request payload, used to correlate run-history entries with source records. Absent from responses until set.

Example: {{record.orderId}}
draftbooleanOptional

When true, this API is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

Responses
200

API updated successfully

application/json

API resource. Shape varies by mode: builder-mode APIs carry type, version, disabled, and builder; script-mode APIs additionally carry script plus top-level _scriptId / function copies. Legacy script APIs (pre-builder era) omit type, version, disabled, and builder entirely.

namestring · min: 1 · max: 100Required

Display name.

Example: Customer API
_integrationIdstring · objectIdOptional

Integration this API belongs to. Omitted for standalone APIs (an API can be created without an integration).

Example: 5e9a8f7c6b3d2a0011c4e5f6
descriptionstringOptional

Optional description of the API's purpose.

Example: API for managing customer records in Salesforce
typestring · enumOptional

API mode. Cannot be changed after creation. Defaults to script when omitted on create; legacy script APIs created before builder mode may omit it on reads as well.

Default: scriptExample: builderPossible values:
versionstringOptional

Version segment of the public URL (/{version}/{relativeURI}).

Default: v1Example: v1Pattern: ^[a-zA-Z0-9\-_\.]+$
disabledbooleanOptional

When true, the API rejects all incoming requests.

Default: false
timeoutPeriodinteger · max: 120Optional

Request-timeout override in seconds (1–120). 0 is a sentinel meaning "use the 120-second default" — the server rewrites it on write, so a stored value is never 0.

Example: 120
traceKeyTemplatestring · max: 1024Optional

Handlebars template that computes each request's trace key from the request payload, used to correlate run-history entries with source records. Absent from responses until set.

Example: {{record.orderId}}
draftbooleanOptional

When true, this API is a draft that auto-deletes when its expiry passes (draftExpiresAt in the response). Set at creation; an update can clear the flag but never set it.

_idstring · objectIdRead-onlyRequired

Unique identifier for the API.

Example: 68ae4264b5f755d2dd3796b4
_apiGroupingIdstring · nullableRead-onlyOptional

API grouping this API belongs to. Set only via PUT /apis/grouping; the server ignores this field in POST/PUT bodies on this resource. May be null after ungrouping.

Example: 60a1b2c3d4e5f60012345678
_scriptIdstring · objectIdRead-onlyOptional

Top-level copy of script._scriptId. Present on script-mode and legacy script APIs for backward compatibility.

Example: 689212a2c42d988978e27a11
functionstringRead-onlyOptional

Top-level copy of script.function. Present on script-mode and legacy script APIs for backward compatibility.

Example: handleRequest
createdAtstring · date-timeRead-onlyRequired

Timestamp when the API was created.

Example: 2025-08-26T23:25:24.107Z
lastModifiedstring · date-timeRead-onlyRequired

Timestamp when the API was last modified.

Example: 2026-04-07T03:48:20.795Z
_templateIdstring · objectIdRead-onlyOptional

Template this API was created from. Present only on template-installed APIs.

Example: 60a2c4e6f321d800129a1a3c
draftExpiresAtstring · date-timeRead-onlyOptional

Timestamp when a draft API auto-deletes. Server-computed when draft is set at creation.

Example: 2026-01-15T09:30:00.000Z
put/v1/apis/{_id}
PUT /v1/apis/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "name": "Custom Handler v2",
  "type": "script",
  "script": {
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest"
  }
}
{
  "_id": "689212abe5118c1cabfb43b3",
  "name": "Custom Handler v2",
  "type": "script",
  "version": "v1",
  "disabled": false,
  "script": {
    "_scriptId": "689212a2c42d988978e27a11",
    "function": "handleRequest"
  },
  "_scriptId": "689212a2c42d988978e27a11",
  "function": "handleRequest",
  "createdAt": "2025-08-05T14:18:19.583Z",
  "lastModified": "2025-08-05T14:18:42.626Z"
}

Delete an API

delete
/v1/apis/{_id}

Deletes an API. Soft-deleted and retained in the recycle bin for 30 days. The public endpoint stops responding immediately. The delete succeeds even with dependents, but those resources will break -- check GET /v1/apis/{_id}/dependencies first.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The unique identifier of the API

Example: 5f8d43a1b9e5a80011a35f2c
Responses
204

API deleted successfully

No content
delete/v1/apis/{_id}
DELETE /v1/apis/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Patch an API

patch
/v1/apis/{_id}

Partially updates an API using a JSON Patch document (RFC 6902). The replace operation is supported on the following whitelisted paths (/logging/debugUntil also accepts remove, which clears an active debug window early):

Path
Description

/name

API display name

/description

API description

/disabled

Enable or disable the API (boolean)

/timeoutPeriod

Request-timeout override in seconds

/pagination/enabled

Enable or disable the cursor-pagination envelope (boolean)

/logging/mode

Logging level for requests handled by this API

/logging/debugUntil

End of a temporary full-debug capture window

/traceKeyTemplate

Handlebars template that computes each request's trace key

All other paths are rejected with 422. This is the only way to change logging -- PUT silently ignores that field.

Logging changes are validated against account entitlements: setting /logging/mode to a payload-capturing mode (standard, detailed) fails with 422 (code payload_storage_required) when the account does not have payload storage enabled, and /logging/debugUntil has the same payload-storage requirement. Accounts whose license does not include logging, or whose license caps the maximum logging mode below the requested one, are also rejected with 422.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The unique identifier of the API

Example: 5f8d43a1b9e5a80011a35f2c
Bodyobject · JsonPatchOperation[]

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

opstring · enumRequired

The operation to perform.

Possible values:
pathstringRequired

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

valueanyOptional

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

Responses
204

API patched successfully

No content
patch/v1/apis/{_id}
PATCH /v1/apis/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50

[
  {
    "op": "replace",
    "path": "/disabled",
    "value": true
  }
]
No content

Convert a JSON object to JSON Schema

put
/v1/apis/schema

Accepts a sample JSON object and returns its inferred JSON Schema definition. Useful for bootstrapping bodySchema in builder-mode APIs from real payload samples. Input must be a non-empty JSON object -- arrays and primitives are rejected. The generated schema is shallow (one level of properties); nested objects become type: "object" without further property inference.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body

Any sample JSON object to convert into JSON Schema.

Other propertiesanyOptional
Responses
200

JSON Schema generated successfully.

application/json
typestringOptionalExample: object
Other propertiesanyOptional
put/v1/apis/schema
PUT /v1/apis/schema HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "name": "Acme Corp",
  "active": true,
  "count": 42
}
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "count": {
      "type": "number"
    }
  }
}

Update the grouping for one or more APIs

put
/v1/apis/updateApiGrouping

Assigns or removes an API grouping for the specified API resources. Pass _apiGroupingId: null to ungroup. Nonexistent API IDs are silently accepted.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
_apiIdsstring · objectId[]Required

List of API resource IDs to update.

_apiGroupingIdstring · nullableOptional

The grouping ID to assign. Pass null or omit to remove the current grouping from the specified APIs.

Example: 60a1b2c3d4e5f60012345678
Responses
204

API grouping updated successfully (no body returned).

No content
put/v1/apis/updateApiGrouping
PUT /v1/apis/updateApiGrouping HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "_apiIds": [
    "5f8d43a1b9e5a80011a35f2c",
    "5f8d43a1b9e5a80011a35f2d"
  ],
  "_apiGroupingId": "60a1b2c3d4e5f60012345678"
}
No content

List recent request/response logs for an API

get
/v1/apis/{_id}/logs

Returns the recent invocation traces captured for the named API. Each entry is a decoded request/response pair — masked for credentials — that the runtime stored when the API was called via its public endpoint. Use this to audit what the API has handled and to triage errors without re-invoking the API.

Traces are file-backed with server-controlled retention and capture scope; an empty requests[] simply means nothing is currently stored for this API. Two invocation sources do not populate this log:

  • Test-runs via POST /v1/apis/{_id}/test/run never surface here.

  • Script-mode API invocations via POST /v1/apis/{_id}/request also do not surface here despite counting toward /v1/apis/usage. Only builder-mode invocations against the public endpoint (https://api.integrator.io/apis/{version}{relativeURI}) populate logs.

List entries are summaries (key, time, method, statusCode) — to see the decoded request/response payload, follow up with GET /v1/apis/{_id}/logs/{key}.

statusCode is returned as a string in list entries but as an integer on the detail endpoint. Credential values are masked as ******** before storage and are not recoverable.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
Responses
200

Trace envelope. requests[] is empty when no invocations are currently stored.

application/json

Request log envelope returned by GET /v1/apis/{_id}/logs. Contains the recent API invocation traces for the API identified by _id. The requests[] array is empty when no invocations have been logged — either the API has never been called, or debug capture is off, or the retention window has elapsed. Each entry is a full decoded request/response pair.

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

{
  "requests": []
}

Get one request/response log entry by key

get
/v1/apis/{_id}/logs/{key}

Returns the full decoded request/response envelope for one API invocation, looked up by the opaque key values surfaced in GET /v1/apis/{_id}/logs. Matches the exact entry whose key is provided — there is no partial-match or range query on this endpoint.

Unlike the parent list (which only carries {key, time, method, statusCode}), this endpoint returns the complete payload: request method/url/headers/body/queryParams/clientAddress, response status/headers/body/responseTime, and (for builder-mode APIs) the inputToResponseBubble snapshot of what the response-mapper saw. Sensitive header values (authorization, OAuth bearer tokens) are masked as ******** before storage.

For builder APIs where the response mapper didn't produce the expected output, inspect inputToResponseBubble.sourceRecord to see what the response stage actually received. response.statusCode is an integer here but the sibling list endpoint returns it as a string. A 404 file_not_found means the key has expired from retention or was never captured.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
keystringRequired

Opaque log key from the parent GET /v1/apis/{_id}/logs listing. Encodes status + method (e.g. …-200-POST) — use the key exactly as returned; do not construct one manually.

Example: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
Responses
200

The decoded request/response envelope.

application/json

Full decoded request/response envelope for one API invocation, returned by GET /v1/apis/{_id}/logs/{key}. Sensitive header values (authorization, OAuth bearer tokens, and similar) are masked with ******** before storage — the originals are not recoverable. The inputToResponseBubble block reveals the Celigo-internal state handed to the response-mapping stage; it's absent for script-mode APIs and pre-mapping failures.

timeinteger · int64Optional

Epoch milliseconds when the invocation was handled.

Example: 1776917346304
keystringOptional

Echoes the key path parameter. Same structure as in the list (<seq>-<id>-<status>-<method>).

Example: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
idstringOptional

Shorter internal id for this log record. Appears embedded in the key string as the second segment. Not independently useful to the caller, but handy for correlating with audit or monitoring logs that reference only the short id.

Example: a10af1ade8fe477a847771c1e3716e36
get/v1/apis/{_id}/logs/{key}
GET /v1/apis/{_id}/logs/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "time": 1776917346304,
  "request": {
    "method": "POST",
    "url": "/apis/v1/orders",
    "httpVersion": "1.1",
    "headers": {
      "content-type": "application/json",
      "authorization": "********",
      "accept": "application/json",
      "host": "api.integrator.io"
    },
    "queryParams": {},
    "body": "{\"orderId\":\"SO-1042\",\"total\":129.99}",
    "clientAddress": "::ffff:127.0.0.6",
    "size": 0
  },
  "response": {
    "statusCode": 200,
    "statusMessage": "OK",
    "headers": {
      "content-type": "application/json",
      "x-request-id": "abc123def456"
    },
    "body": "{\"orderId\":\"SO-1042\"}",
    "size": 21,
    "responseTime": 312
  },
  "inputToResponseBubble": {
    "sourceRecord": [
      {
        "orderId": "SO-1042",
        "total": 129.99
      }
    ],
    "executionErrors": [],
    "configurationErrors": []
  },
  "key": "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST",
  "id": "a10af1ade8fe477a847771c1e3716e36"
}

List API request run history (defaults to last 5 minutes)

get
/v1/apis/{_id}/requests

Returns the logged request executions for an API — one entry per inbound request captured while the API's logging.mode was anything other than noLogging. Distinct from GET /v1/apis/{_id}/logs, which returns the legacy file-backed request/response envelopes: use /requests for run history and trace drill-down, /logs for the raw decoded request and response of a single call.

Whether requests are captured into run history depends on server-side enablement of the capture pipeline, which is separate from this read API. On accounts where capture is not active, this endpoint responds normally (including filter validation) but requests is empty regardless of the API's logging.mode — even for requests that the legacy GET /v1/apis/{_id}/logs (an independent capture path) does record.

Results are cursor-paginated (next/prev). When time_gte / time_lte are omitted, only the last 5 minutes are returned — pass an explicit window for a broader history. Use the executionId from a list entry with GET /v1/apis/{_id}/requests/{executionId} to open the trace view for requests logged in detailed or debug mode.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
Query parameters
statusCodestringOptional

Filter by HTTP response status code — a single value or a comma-separated list. Every value must be an integer.

Example: 200,404Pattern: ^\d+(,\d+)*$
methodstring · enumOptional

Filter by HTTP method (case-insensitive; normalized to uppercase).

Example: GETPossible values:
traceKeystringOptional

Prefix filter on the request trace key.

Example: trace-abc
remoteIPstringOptional

Prefix filter on the client IP address.

Example: 192.168.1.
relativeURIstringOptional

Prefix filter on the request relative URI.

Example: /orders
searchKeystring · min: 3 · max: 500Optional

Free-text search, OR-matched across traceKey (prefix), remoteIP (prefix), and relativeURI (substring). When provided, the individual traceKey/remoteIP/relativeURI filters are ignored. Values shorter than 3 characters are rejected with 400.

Example: order-123
pageSizeinteger · min: 1 · max: 100Optional

Number of entries per page. Values above the documented maximum are not rejected — the server accepts them silently, so treat the maximum as the supported contract rather than an enforced limit.

Default: 50Example: 50
sortOrderstring · enumOptional

Sort direction by request time.

Default: descPossible values:
nextstring · date-timeOptional

ISO 8601 timestamp cursor for the next page (from nextPageUrl). Mutually exclusive with prev; requires cursorExecutionId.

prevstring · date-timeOptional

ISO 8601 timestamp cursor for the previous page (from prevPageUrl). Mutually exclusive with next; requires cursorExecutionId.

cursorExecutionIdstringOptional

Tie-breaker execution id, required when paging with next/prev.

time_gtestring · date-timeOptional

Include requests at or after this ISO timestamp.

time_ltestring · date-timeOptional

Include requests at or before this ISO timestamp.

Responses
200

Paginated run history. requests[] is empty when nothing matches.

application/json

Paginated API request run history.

nextPageUrlstring · nullableOptional

URL to fetch the next page (carries the next cursor and cursorExecutionId tie-breaker); null when there is no next page.

Example: https://api.integrator.io/v1/apis/685021eda02a61042cee80ab/requests?pageSize=50&next=2026-05-15T13:42:11.234Z&cursorExecutionId=a1b2c3d4e5f678901234
prevPageUrlstring · nullableOptional

URL to fetch the previous page; null when there is no previous page.

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

{
  "requests": [
    {
      "executionId": "a1b2c3d4e5f678901234",
      "time": "2026-05-15T13:42:11.234Z",
      "method": "POST",
      "relativeURI": "/orders",
      "statusCode": 200,
      "traceKey": "trace-abc-123",
      "remoteIP": "192.168.1.5",
      "timeTaken": 142.7,
      "logMode": "detailed"
    }
  ],
  "nextPageUrl": null,
  "prevPageUrl": null
}

Delete API request logs in a date range

delete
/v1/apis/{_id}/requests

Queues asynchronous deletion of stored request log payloads for the API within [startedAt, endAt]. Returns 202 Accepted; cleanup runs in the background. Requires manage access for log deletion — monitor-level users receive 403.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
Query parameters
startedAtstring · date-timeRequired

Start of the deletion range, inclusive (ISO 8601). Must be before endAt.

Example: 2026-01-01T00:00:00.000Z
endAtstring · date-timeRequired

End of the deletion range, inclusive (ISO 8601). Must not be in the future.

Example: 2026-01-31T23:59:59.999Z
Responses
202

Deletion request accepted for asynchronous processing.

No content
delete/v1/apis/{_id}/requests
DELETE /v1/apis/{_id}/requests?startedAt=2026-01-01T00%3A00%3A00.000Z&endAt=2026-01-31T23%3A59%3A59.999Z HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get trace metadata for an API request execution

get
/v1/apis/{_id}/requests/{executionId}

Returns the top-level execution steps for the trace view of one API request. Trace data is only available for requests that were logged in detailed or debug mode (see logMode on the run-history entry), and only when the run-history capture pipeline is active for the account (see GET /v1/apis/{_id}/requests) — otherwise steps is empty for every execution id.

A malformed executionId returns 422; an unknown API _id returns 404.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
executionIdstringRequired

The execution id (20-character lowercase hex).

Example: a1b2c3d4e5f678901234Pattern: ^[0-9a-f]{20}$
Responses
200

Top-level trace steps for the request execution.

application/json

Top-level execution steps for the trace view of an API request.

get/v1/apis/{_id}/requests/{executionId}
GET /v1/apis/{_id}/requests/{executionId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "steps": [
    {
      "_expOrImpId": "67ee026136f4d1eeb529ad63",
      "status": "success",
      "timeTaken": 142,
      "groupId": "6449f2",
      "recordId": "4a8e5c",
      "time": "2026-05-15T13:42:11.234Z"
    }
  ]
}

List child records under an API trace step

get
/v1/apis/{_id}/requests/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children

Returns the child records under a parent record within an API request trace (lookup / one-to-many expansions). Results are cursor-paginated (next/prev).

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
executionIdstringRequired

The execution id (20-character lowercase hex).

Example: a1b2c3d4e5f678901234Pattern: ^[0-9a-f]{20}$
_expOrImpIdstringRequired

Export, import, or builder resource-step identifier for the step.

Example: 67ee026136f4d1eeb529ad63
parentRecordIdstringRequired

The parent record id whose children are returned.

Example: a1b2c3
Query parameters
statusstringOptional

Filter children by processing outcome — a single value or a comma-separated list of success, error, ignore.

Example: success,errorPattern: ^(success|error|ignore)(,(success|error|ignore))*$
pageSizeinteger · min: 1 · max: 100Optional

Number of entries per page.

Default: 50Example: 50
sortOrderstring · enumOptional

Sort direction by step time.

Default: descPossible values:
nextstring · date-timeOptional

ISO 8601 timestamp cursor for the next page (from nextPageUrl). Mutually exclusive with prev; requires cursorRecordId.

prevstring · date-timeOptional

ISO 8601 timestamp cursor for the previous page (from prevPageUrl). Mutually exclusive with next; requires cursorRecordId.

cursorRecordIdstringOptional

Tie-breaker record id, required when paging with next/prev.

Responses
200

Paginated child step records.

application/json

Paginated child records under a parent record in an API request trace.

nextPageUrlstring · nullableOptional

URL to fetch the next page; null when there is no next page.

prevPageUrlstring · nullableOptional

URL to fetch the previous page; null when there is no previous page.

get/v1/apis/{_id}/requests/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children
GET /v1/apis/{_id}/requests/{executionId}/{_expOrImpId}/logs/{parentRecordId}/children HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "children": [
    {
      "_expOrImpId": "67ee026136f4d1eeb529ad63",
      "status": "success",
      "timeTaken": 12,
      "groupId": "6449f2",
      "recordId": "child-1",
      "parentRecordId": "a1b2c3",
      "time": "2026-05-15T13:42:11.234Z"
    }
  ],
  "nextPageUrl": null,
  "prevPageUrl": null
}

Query decoded log data for an API trace step

post
/v1/apis/{_id}/requests/{executionId}/logs/data/query

Returns the decoded request/response payload and error metadata for a record/stage within an API request execution, identified by _expOrImpId, stage, groupId, and recordId. If the log content exceeds inline limits or is stored externally, an externalReference with an S3 key (and optional byte range) is returned — download it via the signed-URL endpoint. The response may be gzip-compressed.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
executionIdstringRequired

The execution id (20-character lowercase hex).

Example: a1b2c3d4e5f678901234Pattern: ^[0-9a-f]{20}$
Body

Query payload for retrieving decoded log data for a step within an API request execution. Same shape as the flow log-data query; for API Builder steps, _expOrImpId may be a MongoDB ObjectId or a builder resource-step identifier (resStepId).

_expOrImpIdstringRequired

Export, import, or builder resource-step identifier for the step.

Example: 67ee026136f4d1eeb529ad63
stagestringRequired

Processing stage to fetch data for.

Example: mapping
groupIdstringRequired

Group identifier for the step's records.

Example: grp-001
recordIdstringRequired

Identifier of the record to fetch.

Example: rec-123
Responses
200

Log data (and/or external references) plus error metadata.

application/json
post/v1/apis/{_id}/requests/{executionId}/logs/data/query
POST /v1/apis/{_id}/requests/{executionId}/logs/data/query HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 101

{
  "_expOrImpId": "67ee026136f4d1eeb529ad63",
  "stage": "mapping",
  "groupId": "grp-001",
  "recordId": "rec-123"
}
{
  "logs": [],
  "errors": []
}

Get a signed URL for a stored API request log payload

get
/v1/apis/{_id}/requests/{executionId}/logs/signedURL

Returns a short-lived signed S3 URL (about 120 seconds expiry) for the provided s3Key suffix, taken from an externalReference returned by the log-data query endpoint. The full S3 key is resolved under the execution's own log prefix, so callers can only access logs for this API and execution.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 685021eda02a61042cee80ab
executionIdstringRequired

The execution id (20-character lowercase hex).

Example: a1b2c3d4e5f678901234Pattern: ^[0-9a-f]{20}$
Query parameters
s3KeystringRequired

S3 object key suffix relative to the execution's log prefix, typically returned in a prior log-data query externalReference.

Example: 67ee026136f4d1eeb529ad63/grp-001/part.log
Responses
200

Signed URL for the requested object.

application/json

A short-lived signed URL for downloading a stored API request log payload object.

signedURLstringRequired

Time-limited signed URL (about 120 seconds) to download the referenced log object.

Example: https://integrator-userdata-delete-30.s3.amazonaws.com/api-execution-logs/user/api/exec/group/file.log?Expires=1754046196&Signature=...
get/v1/apis/{_id}/requests/{executionId}/logs/signedURL
GET /v1/apis/{_id}/requests/{executionId}/logs/signedURL?s3Key=67ee026136f4d1eeb529ad63%2Fgrp-001%2Fpart.log HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-userdata-delete-30.s3.amazonaws.com/api-execution-logs/user/api/exec/group/file.log?Expires=1754046196&Signature=..."
}

List dependencies of an API

get
/v1/apis/{_id}/dependencies

Returns the set of resources that depend on the specified resource. The response is an object whose keys are dependent-resource types (e.g. flows, imports) and whose values are arrays of dependency entries. An empty object {} means no 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: 5f8d43a1b9e5a80011a35f2c
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.

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

{}

Test-run an API

post
/v1/apis/{_id}/test/run

Executes the API once in a sandboxed test harness without invoking its public endpoint, and returns the job tree produced by the run. Use this to validate a builder-mode API's request parsing, routing, and response mapping before exposing it externally.

The response carries a metadata map keyed by step id (each value is the ordered list of stage names that ran for that step), the parent flowJob, and the per-step childJobs[]. Inspect a specific step's stages with GET /v1/apis/{_id}/test/run/{runId}/{_stepId}, where runId is the parent flowJob._id.

Test-run invocations do not surface in GET /v1/apis/{_id}/logs.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
Body

Optional test request for the run. When the body is empty or omitted, the run replays the API's saved builder.request.mockRequest.

Other propertiesanyOptional
Responses
200

The job tree produced by the test run.

application/json
flowJobobjectOptional

The parent job for the test run. Its _id is the runId.

childJobsobject[]Optional

Per-step child jobs produced during the run.

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

{}
{
  "metadata": {
    "68ae4264b5f755d2dd3796b4": [
      "request",
      "parse"
    ],
    "main": [
      "router"
    ]
  },
  "flowJob": {
    "_id": "6a2e23bbcf5b64ca6b93b757",
    "type": "flow",
    "_integrationId": "68ed772471086fb1a76686de",
    "status": "completed",
    "numError": 1,
    "numSuccess": 1,
    "startedAt": "2026-06-14T03:44:59.577Z",
    "endedAt": "2026-06-14T03:44:59.947Z"
  },
  "childJobs": [
    {
      "_id": "6a2e23bbcf5b64ca6b93b774",
      "type": "export",
      "_parentJobId": "6a2e23bbcf5b64ca6b93b757",
      "status": "completed",
      "numSuccess": 1
    }
  ]
}

Get a step's stages from an API test run

get
/v1/apis/{_id}/test/run/{runId}/{_stepId}

Returns the per-stage execution detail for a single step of a completed API test run. runId is the parent flowJob._id returned by POST /v1/apis/{_id}/test/run, and _stepId is the step id surfaced in that run's metadata map.

Each entry in stages[] carries the stage name (e.g. request, parse, router) plus its input, output, and errors. Stages that did not produce data for a given direction return null for that field. Top-level errors aggregates step-level errors.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
runIdstringRequired

The parent job id (flowJob._id) returned by the test-run request.

Example: 6a2e23bbcf5b64ca6b93b757
_stepIdstringRequired

The step id, as surfaced in the test run's metadata map.

Example: 68ae4264b5f755d2dd3796b4
Responses
200

Per-stage execution detail for the requested step.

application/json
errorsobject[]Optional

Aggregated step-level errors.

get/v1/apis/{_id}/test/run/{runId}/{_stepId}
GET /v1/apis/{_id}/test/run/{runId}/{_stepId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "stages": [
    {
      "name": "request",
      "errors": null,
      "output": null,
      "input": [
        {
          "record": {
            "page": {
              "_userId": "624cb0346309dc3a543733a2",
              "data": [
                {}
              ]
            }
          },
          "errors": [],
          "traceKey": null
        }
      ]
    },
    {
      "name": "parse",
      "errors": null,
      "input": null,
      "output": [
        {
          "record": {},
          "errors": [],
          "traceKey": null
        }
      ]
    }
  ],
  "errors": []
}

Get request/response captures for an API test-run step

get
/v1/apis/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse

Returns the request/response captures recorded for a single export or import step of an API test run. runId is the parent flowJob._id from POST /v1/apis/{_id}/test/run, and _stepId is the step id from that run's metadata map.

Each entry in requests[] is a summary identified by an opaque key; fetch the full decoded request/response envelope with GET /v1/apis/{_id}/{_stepId}/requests/{key}. A step id that is not an export or import (such as a router) returns a 400 invalid_ref, and a step that captured no request/response data returns a 404 req_res_logs_not_found.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
runIdstringRequired

The parent job id (flowJob._id) returned by the test-run request.

Example: 6a2e23bbcf5b64ca6b93b757
_stepIdstringRequired

The step id, as surfaced in the test run's metadata map. Must be an export or import step.

Example: 68ae434d5fcd3b761b24253a
Responses
200

Request captures recorded for the step.

application/json
get/v1/apis/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse
GET /v1/apis/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "requests": [
    {
      "key": "5475338577473-6c43f93c1fa84b248d64e0d7be1f275f-200-undefined-import-testMode",
      "time": 1782779822527,
      "method": "undefined",
      "statusCode": "200",
      "stage": "import"
    }
  ]
}

List captured requests for an API step

get
/v1/apis/{_id}/{_stepId}/requests

Returns the set of requests captured for a single step of an API. _stepId identifies the step within the API's configuration. Each entry in requests[] is a captured request summary; follow up with GET /v1/apis/{_id}/{_stepId}/requests/{key} to retrieve one entry in full.

An empty requests[] simply means nothing is currently stored for this step.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
_stepIdstringRequired

The step id within the API's configuration.

Example: 68ae4264b5f755d2dd3796b4
Responses
200

Captured requests for the step. requests[] is empty when nothing is stored.

application/json
requestsobject[]Optional

Captured request entries for this step.

get/v1/apis/{_id}/{_stepId}/requests
GET /v1/apis/{_id}/{_stepId}/requests HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "requests": []
}

Get one captured request for an API step by key

get
/v1/apis/{_id}/{_stepId}/requests/{key}

Returns the full captured request/response envelope for one entry of an API step, looked up by the opaque key values surfaced in GET /v1/apis/{_id}/{_stepId}/requests. Matches the exact entry whose key is provided — there is no partial-match query on this endpoint.

Use the key exactly as returned by the parent listing; do not construct one manually. A 404 means the key has expired from retention or was never captured.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The API id.

Example: 68ae4264b5f755d2dd3796b4
_stepIdstringRequired

The step id within the API's configuration.

Example: 68ae4264b5f755d2dd3796b4
keystringRequired

Opaque request key from the parent GET /v1/apis/{_id}/{_stepId}/requests listing. Use the key exactly as returned; do not construct one manually.

Example: 5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST
Responses
200

The full captured request/response envelope for the entry.

application/json
objectOptional

Decoded request/response envelope for the captured entry.

get/v1/apis/{_id}/{_stepId}/requests/{key}
GET /v1/apis/{_id}/{_stepId}/requests/{key} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "time": 1776917346304,
  "request": {
    "method": "POST",
    "url": "/apis/v1/orders",
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"orderId\":\"SO-1042\"}"
  },
  "response": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json"
    },
    "body": "{\"orderId\":\"SO-1042\"}"
  },
  "key": "5481201053696-a10af1ade8fe477a847771c1e3716e36-200-POST"
}

Clone an API

post
/v1/apis/{_id}/clone

Clones a builder-mode API along with the resources it depends on (such as its backing import) and returns a manifest of every resource created.

The request body is required: version must be supplied, and the cloned API's combination of version, method, and relativeURI must be unique. Reusing all three returns a 422 clone_api_already_exists. Pass _integrationId to create the clone inside an integration — when omitted, the clone is created standalone rather than inheriting the source API's integration.

Only builder-type APIs can be cloned — cloning any other API type returns a 400 clone_not_supported.

To check for a version/method/relativeURI conflict without creating anything, call POST /v1/apis/{_id}/clone/validate first.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The id of the API to clone.

Example: 68ae4264b5f755d2dd3796b4
Body
versionstringRequired

Version identifier for the cloned API. The cloned API's combination of version, method, and relativeURI must be unique — reusing all three returns a 422 clone_api_already_exists.

Example: v2
namestringOptional

Name for the cloned API. Defaults to a copy of the source API's name when omitted.

Example: IDP (v2)
_integrationIdstring · objectIdOptional

Integration the cloned API is created in. When omitted, the clone is created standalone — it does not inherit the source API's integration.

Example: 6a429af50547257e3301246c
Responses
201

The clone was created. Returns a manifest of every resource the clone created — the new API plus any dependencies it copied (imports, scripts).

application/json

Manifest of resources created by the clone.

modelstringOptional

Model name of the created resource (e.g. Api, Import).

Example: Api
_idstring · objectIdOptional

Unique id of the created resource.

Example: 6a2e23bbcf5b64ca6b93b757
post/v1/apis/{_id}/clone
POST /v1/apis/{_id}/clone HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "version": "v2",
  "name": "IDP (v2)"
}
[
  {
    "model": "Import",
    "_id": "6a2e23bbcf5b64ca6b93b73d"
  },
  {
    "model": "Api",
    "_id": "6a2e23bbcf5b64ca6b93b757"
  }
]

Validate an API clone

post
/v1/apis/{_id}/clone/validate

Dry-run check for POST /v1/apis/{_id}/clone. Verifies that cloning the API to the target version would not collide with an existing API route — the clone keeps the source API's method and relativeURI, so the target version + method + relativeURI combination must not conflict with an API that is already registered in the account. Nothing is created or modified.

Returns canClone: true when the route is free, false when it conflicts — pick a different version before calling POST /v1/apis/{_id}/clone. Only builder-type APIs can be validated; a script-type API returns 404, the same as an unknown id.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The id of the API to validate cloning for.

Example: 68ae4264b5f755d2dd3796b4
Body
versionstringRequired

Version identifier the clone would be created under. Omitting it returns a 400 required_field_missing.

Example: v2
Responses
200

Validation result. Returned for both outcomes — check canClone.

application/json
canClonebooleanOptional

When true, the target version + method + relativeURI route is free and the clone can be created. When false, the route conflicts with an existing API — choose a different version.

post/v1/apis/{_id}/clone/validate
POST /v1/apis/{_id}/clone/validate HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "version": "v2"
}
{
  "canClone": true
}

Get a downloadable template for an API

get
/v1/apis/{_id}/template

Packages a builder-mode API as an installable template and returns a signed S3 URL where the template .zip can be downloaded. The URL is pre-signed and short-lived (approximately 15 minutes), so fetch the file promptly; call the endpoint again for a fresh URL.

The .zip contains the API definition plus every resource it references — imports, exports, connections, and scripts — grouped into one folder per resource type, with an integration.json manifest at the root.

Only builder-type APIs can be exported — requesting a script-type API returns 404, the same as an unknown id. Requires the create:api:template permission.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
_idstring · objectIdRequired

The id of the API to export.

Example: 68ae4264b5f755d2dd3796b4
Responses
200

Signed download URL for the API template zip.

application/json
signedURLstring · uriOptional

Pre-signed, short-lived S3 URL to download the template .zip.

Example: https://integrator-templates.s3.us-east-1.amazonaws.com/68ae4264b5f755d2dd3796b4.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a
keystringOptional

S3 object key for the generated template .zip, named <apiId>.zip.

Example: 68ae4264b5f755d2dd3796b4.zip
get/v1/apis/{_id}/template
GET /v1/apis/{_id}/template HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-templates.s3.us-east-1.amazonaws.com/68ae4264b5f755d2dd3796b4.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=b117bf598b5535ed024cdbdfec756172f386fd39ad4e4536e40e5efbbf4ff52a",
  "key": "68ae4264b5f755d2dd3796b4.zip"
}
PreviousAPIM
NextAsync Helpers

Last updated

Was this helpful?