> 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/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."},"_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."},"_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."},"_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."},"_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."},"_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\`
```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."},"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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.celigo.com/api/api-reference/on-premise-agents.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.