Telemetry Settings Api Update Telemetry Settings

Telemetry Settings Api Update Telemetry Settings
Update the telemetry settings

Save telemetry settings. ADMIN only. Changing shareAdditionalData is not retroactive.

Request
URI
PUT
https://{api_host}/api/v1/settings/telemetry
COPY
Request Body

The telemetry settings to change. A field that is left out keeps its stored value, and an empty proxyUrl or caBundlePem clears the stored one.

TelemetrySettingsUpdateRequest of type(s) application/json
Required  
{
    "shareAdditionalData": true,
    "proxyUrl": "http://proxy.example.com:3128",
    "retentionDays": 180
}
boolean
shareAdditionalData
Optional

Whether additional usage data is included in uploaded reports; omit to keep the stored value

string
proxyUrl
Optional

Proxy URL (http or https), no userinfo, empty string clears it

string
caBundlePem
Optional

PEM X.509 CA bundle, at most 64 KiB and 10 certificates, empty string clears it

integer As int32 As int32
retentionDays
Optional
Constraints: minimum: 90 maximum: 365

Retention period of stored reports in days, from 90 to 365; omit to keep the stored value

Authentication
This operation uses the following authentication methods.
Responses
200

200 OK successful response envelope. The telemetry settings after the save

Returns TelemetrySettingsDto of type(s) application/json
{
    "shareAdditionalData": true,
    "endpoint": "production",
    "proxyUrl": "http://proxy.example.com:3128",
    "retentionDays": 180,
    "installationId": "00000000-0000-4000-8000-000000000031",
    "secretConfigured": true,
    "operatorDisabled": false
}
boolean
shareAdditionalData
Required  

Whether the additional tier is included in reports generated from now on

string
endpoint
Required  

Upload endpoint selection

  • production: The Broadcom production endpoint; the default of a release build
  • staging: The Broadcom staging endpoint; the default of a build that is not a release build
  • custom: An https URL from configuration (vtp.telemetry.custom-url) without user info, query or fragment; refused in a release build
Enumeration: production, staging, custom
string
proxyUrl
Optional

Optional proxy URL without userinfo

string
caBundleFingerprint
Optional

SHA-256 fingerprint of the custom CA bundle, when one is set

integer As int32 As int32
retentionDays
Required  
Constraints: minimum: 90 maximum: 365

Days reports are kept, 90 to 365

string
installationId
Required  

Stable installation id (UUID)

boolean
secretConfigured
Required  

Whether the product credential was delivered to the appliance

boolean
operatorDisabled
Required  

Whether the support-only operator kill switch is set. Read-only.

string As date-time As date-time
disclosureAcknowledgedAt
Optional

When an administrator acknowledged the disclosure notice, if ever


400

400 Bad Request: INVALID_PROXY_URL when proxyUrl is not an acceptable proxy URL; INVALID_CA_BUNDLE when caBundlePem is not an acceptable PEM certificate bundle; INVALID_RETENTION_DAYS when retentionDays is outside 90 to 365; INVALID_REQUEST when the request body is empty; MALFORMED_REQUEST when the body cannot be read

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


401

401 Unauthorized: UNAUTHENTICATED when the VTP_SESSION cookie is missing, unknown, expired or revoked

Returns Unauthenticated of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


403

403 Forbidden error response (including LICENSE_EXPIRED while the license is restricted). CSRF_ERROR when the X-XSRF-TOKEN header is missing or wrong on a POST, PUT, PATCH or DELETE (only POST /api/v1/auth/login is exempt, and a request without a valid session gets 401 UNAUTHENTICATED instead); PASSWORD_CHANGE_REQUIRED when the account must change its password first (only GET /api/v1/auth/session, POST /api/v1/auth/logout and POST /api/v1/auth/change-password are exempt); LICENSE_REQUIRED or LICENSE_EXPIRED while the license pool is restricted (no license, or expired past grace) (exempt: every route under /api/v1/auth, GET /api/v1/user/preferences, GET /api/v1/licensing/summary and POST /api/v1/licensing/licenses)

Returns ApiErrorResponse of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


500

500 Internal Server Error: INTERNAL_ERROR when the server fails unexpectedly; the message carries no detail

Returns InternalError of type(s) application/json
{
    "errorCode": "string",
    "message": "string",
    "path": "string",
    "timestamp": "string",
    "reason": "string"
}
errorCode
Required  

Stable machine-readable error code. The known values are listed in ApiErrorCode; the set is not closed, so a client must tolerate an unlisted value.

string
message
Required  

Human-readable error description

string
path
Required  

Request URI path that produced the error

string As date-time As date-time
timestamp
Required  

Timestamp when the error occurred as an ISO 8601 date-time with offset

string
reason
Optional

A finer code, present only where an endpoint documents it. The Rule Pack endpoints' PACK_ENTRY_INVALID carries the import core's code here.


Code Samples
COPY
                    curl -X PUT -H 'Authorization: <value>' -H 'Content-Type: application/json' -d '{}' https://{api_host}/api/v1/settings/telemetry