ICAP Settings
Manage the appliance-wide ICAP server settings.
/api/v1/icap/settings
Get the ICAP settings
Returns the settings in effect on the running ICAP server, the deployment values it is bound to, and non-secret certificate metadata. A read succeeds whether or not the licence includes the ICAP entitlement.
/api/v1/icap/settings › Responses
The current ICAP settings
serviceHeaderThe ICAP service header returned on every response.
optionsTtlThe OPTIONS TTL in seconds.
cacheMaxSizeInMbThe maximum size of the response cache in megabytes.
cachingEnabledWhether responses are cached. Follows the cache size rather than being set separately: caching is on whenever the maximum size is greater than zero.
processingTimeoutThe processing timeout, as a duration.
logLevelThe console log level.
mutualTlsEnabledWhether the mutual-TLS listener is enabled. While it is off the server does not bind the TLS port at all. Changing it takes effect on the next ICAP server restart.
listeningPortThe port the server listens on. Set during appliance setup; cannot be changed here.
secureListeningPortThe port the mutual-TLS listener binds. Set during appliance setup; cannot be changed here.
listeningIpThe address the server binds to. Set at deployment; cannot be changed here.
What can be said about the server certificate without disclosing it. The certificate and its private key are provisioned outside the web tier and are never returned.
configuredWhether an administrator has saved these settings through the portal or this API. True after a save that pinned nothing, because the appliance records the save itself, so this does not mean any value is overridden. Read from the settings store on every read.
pendingSettingsThe stored settings the ICAP server has not picked up yet, named as this schema names them. Empty where everything stored is in force. A setting applied live reaches the server when its mounted configuration resyncs, inside a minute, so a read taken in that window reports the value still in effect; this says which values are waiting, so a caller can tell a save that has not landed yet from one that failed. Mutual TLS never appears: it binds a listener at startup, so it applies on the next restart rather than by propagation.
/api/v1/icap/settings
Save the ICAP settings
Changes the ICAP settings. A property left out keeps its current value, so one setting can be changed without restating the rest. A body naming a setting fixed at deployment — a port, the listening address, replica count or the container security context — is refused and names the field, rather than having it silently dropped. Requires the "Glasswall Halo: ICAP" licence entitlement; without it the write is refused and the response names the entitlement. The response carries the values that were written; a setting applied live reaches the running server within the propagation window, and the mTLS listener on the next restart.
/api/v1/icap/settings › Request Body
serviceHeader^[ -~]+$The ICAP service header, 1 to 255 printable ASCII characters and not only whitespace. The value is written verbatim into response headers, which are ASCII, so anything outside that range either injects a header or changes how one renders.
optionsTtlThe OPTIONS TTL in seconds, up to an hour. A peer honouring the TTL does not renegotiate until it expires, so a longer one pins the behaviour a client believes this server has.
cacheMaxSizeInMbThe maximum size of the response cache in megabytes. Zero turns caching off. Cannot exceed 10000000, nor the space available on the volume backing the cache.
processingTimeoutThe processing timeout, between one second and ten minutes, as hh:mm:ss. Must carry a colon: a bare number is refused, because it is a valid duration meaning that many days, so 10 from a caller who meant ten seconds would otherwise be stored as ten days. Note that a two-part value is read as hours and minutes, so 01:40 is one hour forty and outside the range — write 00:01:40.
logLevelThe console log level.
mutualTlsEnabledWhether the mutual-TLS listener is enabled. Applies on the next ICAP server restart, not immediately.
/api/v1/icap/settings › Responses
The saved ICAP settings
serviceHeaderThe ICAP service header returned on every response.
optionsTtlThe OPTIONS TTL in seconds.
cacheMaxSizeInMbThe maximum size of the response cache in megabytes.
cachingEnabledWhether responses are cached. Follows the cache size rather than being set separately: caching is on whenever the maximum size is greater than zero.
processingTimeoutThe processing timeout, as a duration.
logLevelThe console log level.
mutualTlsEnabledWhether the mutual-TLS listener is enabled. While it is off the server does not bind the TLS port at all. Changing it takes effect on the next ICAP server restart.
listeningPortThe port the server listens on. Set during appliance setup; cannot be changed here.
secureListeningPortThe port the mutual-TLS listener binds. Set during appliance setup; cannot be changed here.
listeningIpThe address the server binds to. Set at deployment; cannot be changed here.
What can be said about the server certificate without disclosing it. The certificate and its private key are provisioned outside the web tier and are never returned.
configuredWhether an administrator has saved these settings through the portal or this API. True after a save that pinned nothing, because the appliance records the save itself, so this does not mean any value is overridden. Read from the settings store on every read.
pendingSettingsThe stored settings the ICAP server has not picked up yet, named as this schema names them. Empty where everything stored is in force. A setting applied live reaches the server when its mounted configuration resyncs, inside a minute, so a read taken in that window reports the value still in effect; this says which values are waiting, so a caller can tell a save that has not landed yet from one that failed. Mutual TLS never appears: it binds a listener at startup, so it applies on the next restart rather than by propagation.
/api/v1/icap/connection
Get the ICAP connection details
Returns the endpoint details needed to point an ICAP client at this appliance, taken from the running server rather than from hardcoded values. Readable by the User role as well as Admin: the details carry no secret material, and a proxy administrator should not need the Admin role to read the host and port they are configuring against.
/api/v1/icap/connection › Responses
The ICAP connection details
listeningPortThe port the server listens on.
secureListeningPortThe port the mutual-TLS listener binds.
listeningIpThe address the server binds to.
mutualTlsEnabledWhether the mutual-TLS listener is enabled.
serviceHeaderThe ICAP service header the server returns.
optionsTtlThe OPTIONS TTL in seconds.
/api/v1/icap/test-connection
Test the ICAP service
Issues an ICAP OPTIONS request against the appliance's own listener, so the service can be verified without an external ICAP client and without a file. The probe takes no request body: what it tests is the server that is running. It is bounded and always answers 200 with the outcome, because a probe that ran and found a failure is not the same as a request that failed - read passed, not the status code. Admin only.
/api/v1/icap/test-connection › Responses
The probe ran; passed reports what it found
passedWhether the listener answered both requests.
outcomeThe classification of what the probe found. A caller that does not recognise a value should fall back to reason.
reasonA short summary of the outcome.
hostThe address the probe connected to.
portThe port the probe connected to.
timeoutSecondsThe number of seconds the probe was bounded by.
optionsStatusCodeThe ICAP status the OPTIONS request was answered with, where it was answered.
/api/v1/icap/deployment
Read whether the ICAP server is running
Reports whether the appliance is answering ICAP requests, and how many replicas are asked for against how many are ready. The appliance ships with the ICAP server installed but not running, so this answers enabled: false until an administrator starts it.
It reads the deployment rather than the ICAP server, because at zero replicas the server's own API is silent - which is exactly when this has to work. transitioning is true while the desired and ready counts disagree, so a server that has been asked to start is not reported as running before it can answer. Admin only.
/api/v1/icap/deployment › Responses
The state of the ICAP deployment
enabledWhether the appliance is answering ICAP requests. True only once a replica is ready, so a server that is still starting reads false.
desiredReplicasHow many replicas the deployment has been asked for. The portal sets this to 0 or 1.
readyReplicasHow many replicas are ready to serve.
transitioningWhether the desired and ready counts disagree - a server that is starting or stopping. Poll until this is false before treating the state as settled.
managedByAutoscalerWhether an autoscaler owns the replica count on this installation. It does not settle whether the server can be started and stopped - read changeable for that.
changeableWhether this installation can start and stop the server. False where it was deployed without permission to change it, and where an autoscaler owns the count that the appliance may not pause; a change is refused in both cases. Where an autoscaler is present and can be paused this is true, and starting and stopping go through the autoscaler rather than around it, so nothing is reverted underneath.
/api/v1/icap/deployment
Start or stop the ICAP server
Starts the ICAP server, so the appliance answers ICAP requests on its configured ports, or stops it, so it does not. Saved ICAP settings are kept either way and apply again when the server is started.
The response carries the state as the cluster reports it at that moment, so readyReplicas is usually still zero on a successful start - the pod becomes ready shortly afterwards. Poll the GET until transitioning is false rather than treating the reply as the finished state.
How many replicas serve ICAP is a deployment-time setting and cannot be changed here; this decides only whether one runs at all. Admin only, and audited whichever way it went.
/api/v1/icap/deployment › Request Body
enabledWhether the ICAP server should be running. Required - a body that omits it is refused rather than read as false, so a malformed request cannot stop ICAP by accident.
/api/v1/icap/deployment › Responses
The state of the ICAP deployment after the change
enabledWhether the appliance is answering ICAP requests. True only once a replica is ready, so a server that is still starting reads false.
desiredReplicasHow many replicas the deployment has been asked for. The portal sets this to 0 or 1.
readyReplicasHow many replicas are ready to serve.
transitioningWhether the desired and ready counts disagree - a server that is starting or stopping. Poll until this is false before treating the state as settled.
managedByAutoscalerWhether an autoscaler owns the replica count on this installation. It does not settle whether the server can be started and stopped - read changeable for that.
changeableWhether this installation can start and stop the server. False where it was deployed without permission to change it, and where an autoscaler owns the count that the appliance may not pause; a change is refused in both cases. Where an autoscaler is present and can be paused this is true, and starting and stopping go through the autoscaler rather than around it, so nothing is reverted underneath.