> For the complete documentation index, see [llms.txt](https://developer.celigo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.celigo.com/api/api-reference/connections-and-http-connectors/on-premise-agents.md).

# 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

## The Agent object

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"components":{"schemas":{"Agent":{"type":"object","required":["_id","name","createdAt","lastModified"],"description":"On-premise agent object as returned by the API.","allOf":[{"$ref":"#/components/schemas/AgentBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"version":{"type":"string","readOnly":true,"description":"Agent software version running on the host. Agents from 4.6.0 onward pick\nup new releases on their own while they run as a service (with\nadministrator privileges on Windows), so an agent that stays behind the\ncurrent release is usually not meeting one of those conditions or predates\n4.6.0 — except hosts on Windows Server 2012 R2, which stay on 4.3.0 by\ndesign — and may fall below the minimum Celigo requires for connectivity.\nBring an agent that should be updating (not a 2012 R2 host) current in\nplace with its own installer and token rather than a new agent, which\nwould leave this agent's connections bound to the old one."},"_agentExtensionId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the agent extension installation metadata."},"port":{"type":"string","readOnly":true,"description":"Local port the agent uses for its tunnel listener."},"lastHeartbeatAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the most recent heartbeat from the agent."},"offline":{"type":"boolean","readOnly":true,"description":"When true, the platform considers this agent offline based on heartbeat state."},"_accessLevel":{"type":"string","readOnly":true,"description":"The calling user's effective access level for this agent.\nPresent only when the list request sets `permissions=true`."}}}]},"AgentBase":{"type":"object","description":"Fields for creating or updating an on-premise agent.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name identifying where the agent is installed and what it accesses."},"description":{"type":"string","maxLength":5120,"description":"Optional note about the agent's purpose or host environment."}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]}}}}
```

## List on-premise 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.

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"parameters":{"Include":{"name":"include","in":"query","required":false,"description":"Comma-separated list of fields to project into each returned record.\nTriggers summary projection: the response contains a minimal identity\nset (`_id`, `name`, plus resource-specific fields) with the requested\nfields added on top. Supports dot notation for nested fields.\nMutually exclusive with `exclude`.","schema":{"type":"string"}},"Exclude":{"name":"exclude","in":"query","required":false,"description":"Comma-separated list of fields to strip from the default response.\nUnlike `include`, does not trigger summary projection — returns the\nfull record with the named fields removed. Protected identity fields\n(e.g. `name`) cannot be stripped. Mutually exclusive with `include`.","schema":{"type":"string"}}},"schemas":{"Agent":{"type":"object","required":["_id","name","createdAt","lastModified"],"description":"On-premise agent object as returned by the API.","allOf":[{"$ref":"#/components/schemas/AgentBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"version":{"type":"string","readOnly":true,"description":"Agent software version running on the host. Agents from 4.6.0 onward pick\nup new releases on their own while they run as a service (with\nadministrator privileges on Windows), so an agent that stays behind the\ncurrent release is usually not meeting one of those conditions or predates\n4.6.0 — except hosts on Windows Server 2012 R2, which stay on 4.3.0 by\ndesign — and may fall below the minimum Celigo requires for connectivity.\nBring an agent that should be updating (not a 2012 R2 host) current in\nplace with its own installer and token rather than a new agent, which\nwould leave this agent's connections bound to the old one."},"_agentExtensionId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the agent extension installation metadata."},"port":{"type":"string","readOnly":true,"description":"Local port the agent uses for its tunnel listener."},"lastHeartbeatAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the most recent heartbeat from the agent."},"offline":{"type":"boolean","readOnly":true,"description":"When true, the platform considers this agent offline based on heartbeat state."},"_accessLevel":{"type":"string","readOnly":true,"description":"The calling user's effective access level for this agent.\nPresent only when the list request sets `permissions=true`."}}}]},"AgentBase":{"type":"object","description":"Fields for creating or updating an on-premise agent.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name identifying where the agent is installed and what it accesses."},"description":{"type":"string","maxLength":5120,"description":"Optional note about the agent's purpose or host environment."}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/agents":{"get":{"summary":"List on-premise agents","description":"Returns all on-premise agents configured in the account. Check `offline`\nto determine agent health — `true` means the platform has not received a\nheartbeat recently.","operationId":"listAgents","tags":["On-premise Agents"],"parameters":[{"$ref":"#/components/parameters/Include"},{"$ref":"#/components/parameters/Exclude"},{"name":"limit","in":"query","required":false,"description":"Maximum number of agents to return per page.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":1000}},{"name":"sort_by","in":"query","required":false,"description":"Field to sort the agent list by (for example `name`).","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Opaque pagination cursor from a previous page's `Link` header;\nreturns results after that position. Invalid cursor values return\n400 `invalid_query_param`.","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Opaque pagination cursor from a previous page's `Link` header;\nreturns results before that position. Invalid cursor values return\n400 `invalid_query_param`.","schema":{"type":"string"}},{"name":"permissions","in":"query","required":false,"description":"When true, each returned agent additionally carries `_accessLevel` —\nthe calling user's effective access to that agent.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Array of agent objects.","headers":{"Link":{"description":"RFC 5988 pagination links. Includes `<...>; rel=\"next\"` when more\npages remain; absent on the final page.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}},"204":{"description":"No agents exist in the account."},"400":{"description":"Invalid pagination cursor in `after` or `before`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```

## Create an on-premise agent

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

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Fields for creating or updating an on-premise agent.","required":["name"],"allOf":[{"$ref":"#/components/schemas/AgentBase"}]},"AgentBase":{"type":"object","description":"Fields for creating or updating an on-premise agent.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name identifying where the agent is installed and what it accesses."},"description":{"type":"string","maxLength":5120,"description":"Optional note about the agent's purpose or host environment."}}},"Agent":{"type":"object","required":["_id","name","createdAt","lastModified"],"description":"On-premise agent object as returned by the API.","allOf":[{"$ref":"#/components/schemas/AgentBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"version":{"type":"string","readOnly":true,"description":"Agent software version running on the host. Agents from 4.6.0 onward pick\nup new releases on their own while they run as a service (with\nadministrator privileges on Windows), so an agent that stays behind the\ncurrent release is usually not meeting one of those conditions or predates\n4.6.0 — except hosts on Windows Server 2012 R2, which stay on 4.3.0 by\ndesign — and may fall below the minimum Celigo requires for connectivity.\nBring an agent that should be updating (not a 2012 R2 host) current in\nplace with its own installer and token rather than a new agent, which\nwould leave this agent's connections bound to the old one."},"_agentExtensionId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the agent extension installation metadata."},"port":{"type":"string","readOnly":true,"description":"Local port the agent uses for its tunnel listener."},"lastHeartbeatAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the most recent heartbeat from the agent."},"offline":{"type":"boolean","readOnly":true,"description":"When true, the platform considers this agent offline based on heartbeat state."},"_accessLevel":{"type":"string","readOnly":true,"description":"The calling user's effective access level for this agent.\nPresent only when the list request sets `permissions=true`."}}}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/agents":{"post":{"summary":"Create an on-premise agent","description":"Creates a new on-premise agent. Only `name` is required. The response\nincludes the agent record but not the access token — call\n`GET /v1/agents/{_id}/display-token` to retrieve the token needed for\nthe agent installer.","operationId":"createAgent","tags":["On-premise Agents"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"201":{"description":"Created agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"422":{"description":"Validation failed. A missing, empty, or non-string `name` returns\n`required_field_missing` (the server maps a non-string `name` to\n\"missing\"). A `name` longer than 100 characters, or a `description`\nlonger than 5120, returns `size_limit_exceeded`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get an on-premise agent

> Returns a single on-premise agent.

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Agent":{"type":"object","required":["_id","name","createdAt","lastModified"],"description":"On-premise agent object as returned by the API.","allOf":[{"$ref":"#/components/schemas/AgentBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"version":{"type":"string","readOnly":true,"description":"Agent software version running on the host. Agents from 4.6.0 onward pick\nup new releases on their own while they run as a service (with\nadministrator privileges on Windows), so an agent that stays behind the\ncurrent release is usually not meeting one of those conditions or predates\n4.6.0 — except hosts on Windows Server 2012 R2, which stay on 4.3.0 by\ndesign — and may fall below the minimum Celigo requires for connectivity.\nBring an agent that should be updating (not a 2012 R2 host) current in\nplace with its own installer and token rather than a new agent, which\nwould leave this agent's connections bound to the old one."},"_agentExtensionId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the agent extension installation metadata."},"port":{"type":"string","readOnly":true,"description":"Local port the agent uses for its tunnel listener."},"lastHeartbeatAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the most recent heartbeat from the agent."},"offline":{"type":"boolean","readOnly":true,"description":"When true, the platform considers this agent offline based on heartbeat state."},"_accessLevel":{"type":"string","readOnly":true,"description":"The calling user's effective access level for this agent.\nPresent only when the list request sets `permissions=true`."}}}]},"AgentBase":{"type":"object","description":"Fields for creating or updating an on-premise agent.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name identifying where the agent is installed and what it accesses."},"description":{"type":"string","maxLength":5120,"description":"Optional note about the agent's purpose or host environment."}}},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/agents/{_id}":{"get":{"summary":"Get an on-premise agent","operationId":"getAgent","tags":["On-premise Agents"],"description":"Returns a single on-premise agent.","parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Agent object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Update an on-premise agent

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

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Request":{"type":"object","description":"Fields for creating or updating an on-premise agent.","required":["name"],"allOf":[{"$ref":"#/components/schemas/AgentBase"}]},"AgentBase":{"type":"object","description":"Fields for creating or updating an on-premise agent.","properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Display name identifying where the agent is installed and what it accesses."},"description":{"type":"string","maxLength":5120,"description":"Optional note about the agent's purpose or host environment."}}},"Agent":{"type":"object","required":["_id","name","createdAt","lastModified"],"description":"On-premise agent object as returned by the API.","allOf":[{"$ref":"#/components/schemas/AgentBase"},{"$ref":"#/components/schemas/ResourceResponse"},{"type":"object","properties":{"version":{"type":"string","readOnly":true,"description":"Agent software version running on the host. Agents from 4.6.0 onward pick\nup new releases on their own while they run as a service (with\nadministrator privileges on Windows), so an agent that stays behind the\ncurrent release is usually not meeting one of those conditions or predates\n4.6.0 — except hosts on Windows Server 2012 R2, which stay on 4.3.0 by\ndesign — and may fall below the minimum Celigo requires for connectivity.\nBring an agent that should be updating (not a 2012 R2 host) current in\nplace with its own installer and token rather than a new agent, which\nwould leave this agent's connections bound to the old one."},"_agentExtensionId":{"type":"string","format":"objectId","readOnly":true,"description":"Reference to the agent extension installation metadata."},"port":{"type":"string","readOnly":true,"description":"Local port the agent uses for its tunnel listener."},"lastHeartbeatAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp of the most recent heartbeat from the agent."},"offline":{"type":"boolean","readOnly":true,"description":"When true, the platform considers this agent offline based on heartbeat state."},"_accessLevel":{"type":"string","readOnly":true,"description":"The calling user's effective access level for this agent.\nPresent only when the list request sets `permissions=true`."}}}]},"ResourceResponse":{"type":"object","description":"Response","properties":{"_id":{"type":"string","format":"objectId","readOnly":true,"description":"Unique identifier for the resource. Format is a 24-character hexadecimal string."},"createdAt":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was created. Set automatically and cannot be modified."},"lastModified":{"type":"string","format":"date-time","readOnly":true,"description":"Timestamp when the resource was last updated. Changes whenever any property is modified."},"deletedAt":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Timestamp when the resource was soft-deleted. When null or absent, the resource is active."}},"required":["_id"]},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"400-bad-request":{"description":"Bad request. The server could not understand the request because of malformed syntax or invalid parameters.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/agents/{_id}":{"put":{"summary":"Update an on-premise agent","operationId":"updateAgent","tags":["On-premise Agents"],"description":"Replaces an on-premise agent's mutable fields. Only `name` and\n`description` are mutable — system-managed fields (`version`, `offline`,\n`port`, etc.) are ignored on PUT.","parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"responses":{"200":{"description":"Updated agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Agent"}}}},"400":{"$ref":"#/components/responses/400-bad-request"},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Delete an on-premise agent

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

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-dependency-conflict":{"description":"The resource has dependents that must be deleted first. Each entry\nin the `errors` array names one blocking resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}}},"paths":{"/v1/agents/{_id}":{"delete":{"summary":"Delete an on-premise agent","operationId":"deleteAgent","tags":["On-premise Agents"],"description":"Deletes an on-premise agent. Soft-deleted and retained in the recycle bin\nfor 30 days. Does not uninstall the agent software on the host.\nConnections using this agent's `_agentId` will block deletion with 422\n— check dependencies first.","parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"204":{"description":"Agent deleted."},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-dependency-conflict"}}}}}}
```

## Display on-premise agent access 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.

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AccessTokenResponse":{"type":"object","description":"Response containing the access token used by an on-premise agent to\nauthenticate its secure tunnel back to integrator.io.\n","properties":{"accessToken":{"type":"string","description":"The agent's current access token value."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/agents/{_id}/display-token":{"get":{"summary":"Display on-premise agent access token","description":"Returns the current unmasked access token for an agent. The agent process\nneeds this token to authenticate its tunnel back to integrator.io. The\naccess token is not included in normal GET/PUT responses — this is the\nonly way to retrieve it.","operationId":"displayAgentToken","tags":["On-premise Agents"],"parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessTokenResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Rotate on-premise agent access 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.

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"AccessTokenResponse":{"type":"object","description":"Response containing the access token used by an on-premise agent to\nauthenticate its secure tunnel back to integrator.io.\n","properties":{"accessToken":{"type":"string","description":"The agent's current access token value."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/agents/{_id}/change-token":{"put":{"summary":"Rotate on-premise agent access token","description":"Regenerates the access token and returns the new value. The previous\ntoken is immediately invalidated — the running agent process will\ndisconnect, so update the agent's configuration with the new token\nbefore it attempts to reconnect. This is irreversible.","operationId":"changeAgentToken","tags":["On-premise Agents"],"parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"New access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessTokenResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"}}}}}}
```

## Get on-premise agent installer download URL

> 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\`<br>

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"InstallerSignedUrlResponse":{"type":"object","description":"Presigned S3 download URL for the on-premise agent installer binary\n(Linux `.run` or Windows `.exe`). The URL is short-lived (~15 minutes).\n","properties":{"signedURL":{"type":"string","format":"uri","description":"Presigned S3 URL the client should follow to download the installer."}}},"Error":{"type":"object","description":"Standard error response envelope returned by integrator.io APIs.","properties":{"errors":{"type":"array","description":"List of errors that occurred while processing the request.","items":{"type":"object","properties":{"code":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Machine-readable error code. Usually a string like\n`invalid_ref`, `missing_required_field`, or `unauthorized`;\nmay be an **integer** when the error mirrors an upstream HTTP\nstatus (e.g. `500`) — most commonly returned by connection-ping\nand adaptor-proxy responses."},"message":{"type":"string","description":"Human-readable description of the error."},"field":{"type":"string","description":"Optional pointer to the document field that caused the error.\nUsed by structural validation errors (`missing_required_field`,\n`invalid_ref`) to indicate which field is at fault\n(e.g. `_id`, `type`, `http.baseURI`)."},"source":{"type":"string","description":"Optional origin layer for the error — e.g. `application` when\nthe error came from the remote system the adaptor called,\n`connector` when the adaptor itself rejected the request."}},"required":["message"]}}},"required":["errors"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}},"404-not-found":{"description":"Not found. The requested resource does not exist or is not visible to the caller.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422-unprocessable-entity":{"description":"Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/agents/{_id}/installer/signedURL":{"get":{"summary":"Get on-premise agent installer download URL","description":"Returns a short-lived presigned S3 URL for downloading the on-premise\nagent installer binary. The URL is pre-signed for roughly 15 minutes.\n\nThe `os` query parameter selects which installer to return:\n- `linux` → `agent-linux.run`\n- `windows` → `agent-windows.exe`\n","operationId":"getAgentInstallerUrl","tags":["On-premise Agents"],"parameters":[{"name":"_id","in":"path","required":true,"schema":{"type":"string","format":"objectId"},"description":"On-premise agent id."},{"name":"os","in":"query","required":true,"schema":{"type":"string","enum":["linux","windows"]},"description":"Operating system to download the installer for."}],"responses":{"200":{"description":"Presigned installer download URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallerSignedUrlResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"},"404":{"$ref":"#/components/responses/404-not-found"},"422":{"$ref":"#/components/responses/422-unprocessable-entity"}}}}}}
```

## List dependencies of an agent

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

```json
{"openapi":"3.2.0","info":{"title":"On-premise Agents","version":"1.0.0"},"tags":[{"name":"On-premise Agents","description":"On-premise agents are software programs installed on a local server that\nestablish a secure tunnel back to integrator.io. Connections configured\nwith an `_agentId` route traffic through the agent, enabling integrations\nwith databases and applications behind a firewall without opening\ninbound ports.\n\n## Agent schema\n\n{% openapi-schemas spec=\"agent\" schemas=\"Agent\" grouped=\"true\" %}"}],"servers":[{"url":"https://api.integrator.io","description":"Production (US / default region)"},{"url":"https://api.eu.integrator.io","description":"Production (EU region)"},{"url":"https://api.au.integrator.io","description":"Production (AU region)"},{"url":"https://api.ca.integrator.io","description":"Production (CA region)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"DependencyResponse":{"type":"object","description":"Map of dependent-resource types to arrays of dependency entries.\nKeys are plural resource type strings (e.g. `flows`, `imports`,\n`connections`). An empty object `{}` means no dependents.\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/DependencyEntry"}}},"DependencyEntry":{"type":"object","description":"A single resource that depends on the queried resource.","properties":{"id":{"type":"string","description":"Unique identifier of the dependent resource."},"name":{"type":"string","description":"Display name of the dependent resource."},"type":{"type":"string","description":"Sub-type of the dependent resource when its collection distinguishes one, such as\n`stream` for a listener export. Only present for resource types that carry a `type`."},"paths":{"type":"array","description":"Dot-notation paths within the dependent resource that reference\nthe target resource. `[*]` denotes array elements.","items":{"type":"string"}},"accessLevel":{"type":"string","description":"The caller's access level on the dependent resource."},"dependencyIds":{"type":"object","description":"Map of resource types to arrays of IDs that this dependent\nresource references on the target. Keys are singular or plural\nresource type strings; values are arrays of ID strings.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["id","name","paths","accessLevel","dependencyIds"]}},"responses":{"401-unauthorized":{"description":"Unauthorized. The request lacks a valid bearer token, or the provided token\nfailed to authenticate.\n\nNote: the 401 response is produced by the auth middleware **before** the\nrequest reaches the endpoint handler, so it does **not** follow the\nstandard `{errors: [...]}` envelope. Instead the body is a bare\n`{message: string}` object with no `code`, no `errors` array. Callers\nhandling 401s should key off the HTTP status and the `message` string,\nnot try to destructure an `errors[]`.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable description of the auth failure. Known values:\n- `\"Unauthorized\"` — no `Authorization` header on the request.\n- `\"Bearer Authentication Failed\"` — header present but token\n  is invalid, revoked, or expired."}},"required":["message"]}}}}}},"paths":{"/v1/agents/{_id}/dependencies":{"get":{"operationId":"listAgentDependencies","tags":["On-premise Agents"],"summary":"List dependencies of an agent","description":"Returns resources that depend on this agent. Keys are resource types\n(e.g. `connections`); values are arrays of dependency entries.\n\nCheck dependencies before deleting — the DELETE endpoint is blocked if\ndependents exist. Returns `{}` for both zero-dependency and nonexistent IDs.","parameters":[{"name":"_id","in":"path","required":true,"description":"Agent resource ID.","schema":{"type":"string","format":"objectId"}}],"responses":{"200":{"description":"Dependency map. Keys are resource-type strings; values are arrays\nof dependency entries. Returns `{}` when no dependents exist.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DependencyResponse"}}}},"401":{"$ref":"#/components/responses/401-unauthorized"}}}}}}
```