On Premise Agents

On-premise agents are software programs installed on a local server that establish a secure tunnel back to integrator.io. Connections configured with an _agentId route traffic through the agent, enabling integrations with databases and applications behind a firewall without opening inbound ports.

Agent schema

List on-premise agents

get

/v1/agents

Returns all on-premise agents configured in the account. Check offline to determine agent health — true means the platform has not received a heartbeat recently.

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

limitinteger · min: 1 · max: 1000Optional

Maximum number of agents to return per page.

Default: 1000Example: 100

sort_bystringOptional

Field to sort the agent list by (for example name).

Example: name

afterstringOptional

Opaque pagination cursor from a previous page's Link header; returns results after that position. Invalid cursor values return 400 invalid_query_param.

beforestringOptional

Opaque pagination cursor from a previous page's Link header; returns results before that position. Invalid cursor values return 400 invalid_query_param.

permissionsbooleanOptional

When true, each returned agent additionally carries _accessLevel — the calling user's effective access to that agent.

Example: true

Responses

200

Array of agent objects.

application/json

204

No agents exist in the account.

400

Invalid pagination cursor in after or before.

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

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

[
  {
    "_id": "62e1387939dc306a3806eab5",
    "name": "Production DB Server",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastModified": "2026-04-23T01:52:12.086Z",
    "offline": false,
    "version": "5.3.0",
    "_agentExtensionId": "68fb235610b42b2eaa6525c2",
    "port": "7020",
    "lastHeartbeatAt": "2026-05-15T12:00:00.000Z"
  },
  {
    "_id": "5ecd2c3ce1ec9c4fcaf60b10",
    "name": "Staging Server",
    "createdAt": "2023-06-01T08:00:00.000Z",
    "lastModified": "2026-03-10T14:22:33.000Z",
    "offline": true
  }
]

Create an on-premise agent

post

/v1/agents

Creates a new on-premise agent. Only name is required. The response includes the agent record but not the access token — call GET /v1/agents/{_id}/display-token to retrieve the token needed for the agent installer.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Fields for creating or updating an on-premise agent.

namestring · min: 1 · max: 100Required

Display name identifying where the agent is installed and what it accesses.

Example: Acme DC1 host — SQL Server + SFTP

descriptionstring · max: 5120Optional

Optional note about the agent's purpose or host environment.

Example: Runs on prod-db-01, accesses PostgreSQL and Redis.

Responses

201

Created agent.

application/json

On-premise agent object as returned by the API.

namestring · min: 1 · max: 100Required

Display name identifying where the agent is installed and what it accesses.

Example: Acme DC1 host — SQL Server + SFTP

descriptionstring · max: 5120Optional

Optional note about the agent's purpose or host environment.

Example: Runs on prod-db-01, accesses PostgreSQL and Redis.

_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

versionstringRead-onlyOptional

Agent software version running on the host.

Example: 5.3.0

_agentExtensionIdstring · objectIdRead-onlyOptional

Reference to the agent extension installation metadata.

Example: 68fb235610b42b2eaa6525c2

portstringRead-onlyOptional

Local port the agent uses for its tunnel listener.

Example: 7020

lastHeartbeatAtstring · date-timeRead-onlyOptional

Timestamp of the most recent heartbeat from the agent.

Example: 2026-05-15T12:00:00.000Z

offlinebooleanRead-onlyOptional

When true, the platform considers this agent offline based on heartbeat state.

_accessLevelstringRead-onlyOptional

The calling user's effective access level for this agent. Present only when the list request sets permissions=true.

Example: manage

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

Validation failed. A missing, empty, or non-string name returns required_field_missing (the server maps a non-string name to "missing"). A name longer than 100 characters, or a description longer than 5120, returns size_limit_exceeded.

application/json

post/v1/agents

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

{
  "name": "Production DB Server"
}

{
  "_id": "62e1387939dc306a3806eab5",
  "name": "Production DB Server",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModified": "2024-01-15T10:30:00.000Z",
  "offline": true
}

Get an on-premise agent

get

/v1/agents/{_id}

Returns a single on-premise agent.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Agent resource ID.

Responses

200

Agent object.

application/json

On-premise agent object as returned by the API.

namestring · min: 1 · max: 100Required

Display name identifying where the agent is installed and what it accesses.

Example: Acme DC1 host — SQL Server + SFTP

descriptionstring · max: 5120Optional

Optional note about the agent's purpose or host environment.

Example: Runs on prod-db-01, accesses PostgreSQL and Redis.

_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

versionstringRead-onlyOptional

Agent software version running on the host.

Example: 5.3.0

_agentExtensionIdstring · objectIdRead-onlyOptional

Reference to the agent extension installation metadata.

Example: 68fb235610b42b2eaa6525c2

portstringRead-onlyOptional

Local port the agent uses for its tunnel listener.

Example: 7020

lastHeartbeatAtstring · date-timeRead-onlyOptional

Timestamp of the most recent heartbeat from the agent.

Example: 2026-05-15T12:00:00.000Z

offlinebooleanRead-onlyOptional

When true, the platform considers this agent offline based on heartbeat state.

_accessLevelstringRead-onlyOptional

The calling user's effective access level for this agent. Present only when the list request sets permissions=true.

Example: manage

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

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

{
  "_id": "62e1387939dc306a3806eab5",
  "name": "Production DB Server",
  "description": "Runs on prod-db-01, accesses PostgreSQL.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModified": "2026-04-23T01:52:12.086Z",
  "offline": false,
  "version": "5.3.0",
  "_agentExtensionId": "68fb235610b42b2eaa6525c2",
  "port": "7020",
  "lastHeartbeatAt": "2026-05-15T12:00:00.000Z"
}

Update an on-premise agent

put

/v1/agents/{_id}

Replaces an on-premise agent's mutable fields. Only name and description are mutable — system-managed fields (version, offline, port, etc.) are ignored on PUT.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Agent resource ID.

Body

Fields for creating or updating an on-premise agent.

namestring · min: 1 · max: 100Required

Display name identifying where the agent is installed and what it accesses.

Example: Acme DC1 host — SQL Server + SFTP

descriptionstring · max: 5120Optional

Optional note about the agent's purpose or host environment.

Example: Runs on prod-db-01, accesses PostgreSQL and Redis.

Responses

200

Updated agent.

application/json

On-premise agent object as returned by the API.

namestring · min: 1 · max: 100Required

Display name identifying where the agent is installed and what it accesses.

Example: Acme DC1 host — SQL Server + SFTP

descriptionstring · max: 5120Optional

Optional note about the agent's purpose or host environment.

Example: Runs on prod-db-01, accesses PostgreSQL and Redis.

_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

versionstringRead-onlyOptional

Agent software version running on the host.

Example: 5.3.0

_agentExtensionIdstring · objectIdRead-onlyOptional

Reference to the agent extension installation metadata.

Example: 68fb235610b42b2eaa6525c2

portstringRead-onlyOptional

Local port the agent uses for its tunnel listener.

Example: 7020

lastHeartbeatAtstring · date-timeRead-onlyOptional

Timestamp of the most recent heartbeat from the agent.

Example: 2026-05-15T12:00:00.000Z

offlinebooleanRead-onlyOptional

When true, the platform considers this agent offline based on heartbeat state.

_accessLevelstringRead-onlyOptional

The calling user's effective access level for this agent. Present only when the list request sets permissions=true.

Example: manage

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

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

{
  "name": "Production DB Server",
  "description": "Runs on prod-db-01, accesses PostgreSQL and Redis."
}

{
  "_id": "62e1387939dc306a3806eab5",
  "name": "Production DB Server",
  "description": "Runs on prod-db-01, accesses PostgreSQL and Redis.",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastModified": "2026-04-23T01:52:12.086Z",
  "offline": false,
  "version": "5.3.0",
  "_agentExtensionId": "68fb235610b42b2eaa6525c2",
  "port": "7020",
  "lastHeartbeatAt": "2026-05-15T12:00:00.000Z"
}

Delete an on-premise agent

delete

/v1/agents/{_id}

Deletes an on-premise agent. Soft-deleted and retained in the recycle bin for 30 days. Does not uninstall the agent software on the host. Connections using this agent's _agentId will block deletion with 422 — check dependencies first.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Agent resource ID.

Responses

204

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

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

No content

Display on-premise agent access token

get

/v1/agents/{_id}/display-token

Returns the current unmasked access token for an agent. The agent process needs this token to authenticate its tunnel back to integrator.io. The access token is not included in normal GET/PUT responses — this is the only way to retrieve it.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Agent resource ID.

Responses

200

Access token.

application/json

Response containing the access token used by an on-premise agent to authenticate its secure tunnel back to integrator.io.

accessTokenstringOptional

The agent's current access token value.

Example: 894a7c82655d47b4940444f540e8f7b7

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/agents/{_id}/display-token

GET /v1/agents/{_id}/display-token HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "accessToken": "894a7c82655d47b4940444f540e8f7b7"
}

Rotate on-premise agent access token

put

/v1/agents/{_id}/change-token

Regenerates the access token and returns the new value. The previous token is immediately invalidated — the running agent process will disconnect, so update the agent's configuration with the new token before it attempts to reconnect. This is irreversible.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Agent resource ID.

Responses

200

New access token.

application/json

Response containing the access token used by an on-premise agent to authenticate its secure tunnel back to integrator.io.

accessTokenstringOptional

The agent's current access token value.

Example: 894a7c82655d47b4940444f540e8f7b7

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/agents/{_id}/change-token

PUT /v1/agents/{_id}/change-token HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "accessToken": "e21ccad765da4378bf296007c17b96a8"
}

Get on-premise agent installer download URL

get

/v1/agents/{_id}/installer/signedURL

Returns a short-lived presigned S3 URL for downloading the on-premise agent installer binary. The URL is pre-signed for roughly 15 minutes.

The os query parameter selects which installer to return:

• linux → agent-linux.run
• windows → agent-windows.exe

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

On-premise agent id.

Query parameters

osstring · enumRequired

Operating system to download the installer for.

Possible values:

Responses

200

Presigned installer download URL.

application/json

Presigned S3 download URL for the on-premise agent installer binary (Linux .run or Windows .exe). The URL is short-lived (~15 minutes).

signedURLstring · uriOptional

Presigned S3 URL the client should follow to download the installer.

Example: https://integrator-agents.s3.us-east-1.amazonaws.com/agent-linux.run?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

422

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

application/json

get/v1/agents/{_id}/installer/signedURL

GET /v1/agents/{_id}/installer/signedURL?os=linux HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "signedURL": "https://integrator-agents.s3.us-east-1.amazonaws.com/agent-linux.run?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&..."
}

List dependencies of an agent

get

/v1/agents/{_id}/dependencies

Returns resources that depend on this agent. Keys are resource types (e.g. connections); 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

Agent resource ID.

Responses

200

Dependency map. Keys are resource-type strings; values are arrays of dependency entries. Returns {} when no dependents exist.

application/json

Map of dependent-resource types to arrays of dependency entries. Keys are plural resource type strings (e.g. flows, imports, connections). An empty object {} means no dependents.

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

get/v1/agents/{_id}/dependencies

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

{}