TRtraversal
integrations-v3

Update

Changed on

Update metadata or rotate credentials for an integration instance.

All body fields are optional. Omitting a field leaves that aspect unchanged. Supplying integration rotates the stored credentials.

environment_labels replaces the stored set outright rather than merging, so send the full list; [] clears every label and omitting the field keeps the current ones. Labels are normalized (lowercased, trimmed, deduped) before storage, and the response echoes the stored form — send ["PROD"] and read back ["prod"].

Permissions: users with integration-setup permission on the owning org, or platform admin. organization_id defaults to the caller's own org; platform admins may supply a different org to update its integrations.

If credentials, config, or network access changes, a health check workflow starts in the background and updates last_health_check asynchronously.

Returns HTTP 404 if the instance or the target organization does not exist. Returns HTTP 409 if the update would exceed the org MCP tool limit.

put/v3/integrations/{id}

Request

  • Base URL
    https://api.traversal.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.traversal.com/v3/integrations/{id}
  • Auth
    none declared

Path parameters

idstring required

Query parameters

organization_idstring nullable

Request body

namestring nullable

New display name for the integration instance. Leave null to keep the existing name.

descriptionstring nullable

Description of this integration instance. Surfaced directly to Traversal's AI during incident investigations — include context about which environment, services, or teams this integration covers, and any scope or access limitations the AI should be aware of. Leave null to keep the existing description.

integrationobject nullable

Partial integration fields to update. Keys map to top-level attributes of the integration model and are applied as follows: (1) Pydantic sub-model field (e.g. auth, connection) — the supplied dict is shallow-merged onto the existing sub-model, so omitted attributes are preserved from the stored value. (2) Plain dict field (e.g. incident_api_health_check_params) — the supplied dict replaces the stored value entirely; omitted keys are not preserved. (3) Scalar or list field — replaced outright. Supplying this field rotates credentials in the secrets backend and refreshes the cached configuration snapshot in the database. Leave null to update only metadata fields (name, description).

network_accessstring nullable

Name of the network this integration should connect through (e.g. an internal VPN). Leave null to keep the current network setting unchanged. Set to "Public internet" to clear the network and connect over the public internet.

mcp_tool_descriptionsobject nullable

Optional agent-facing MCP tool descriptions keyed by raw MCP tool name. Unblocked tools remain searchable without a saved description. This is metadata only and does not rotate integration credentials.

environment_labelsstring[] nullable

The customer's own names for the environments this integration's data covers, e.g. ["prod", "staging"]. Replaces the stored set outright: send the full list, send [] to clear every label, and leave null to keep the current labels unchanged. Lowercased, trimmed and deduped on the way in, so PROD and prod are one environment. At most 10 labels of 20 characters each. Use the reserved "unscoped" alone when the data is not split by environment at all — it cannot be combined with any other label. This is metadata only and does not rotate integration credentials; datasets pick the new labels up at their next population run.

Response

Successful Response

idstring required

Stable UUID for this integration instance. Use this in PUT /v3/integrations/{id} and DELETE /v3/integrations/{id}.

organization_idstring required

UUID of the organization that owns this integration instance.

namestring required

Human-readable display name set at creation time.

descriptionstring nullable

Optional free-text description of this integration instance. Surfaced to Traversal's AI during investigations to help it understand when and how to use this integration.

type'anthropic' | 'openai' | 'gradient_ai' | 'datadog' | 'elasticsearch' | 'prometheus' | 'mimir' | 'victoria_metrics' | 'grafana' | 'appdynamics' | 'servicenow' | 'github' | 'github_webhook' | 'gitlab' | 'thousandeyes' | 'linear' | 'notion' | 'loki' | 'opensearch' | 'splunk' | 'gcp' | 'motherduck' | 'confluence' | 'coralogix' | 'firehydrant' | 'pagerduty' | 'slack' | 'teams' | 'jira' | 'kubernetes' | 'traversal' | 'traversal_webhook' | 'traversal_api_key' | 'incident_io' | 'sentry' | 'tempo' | 'alexandria' | 'honeycomb' | 'alertmanager' | 'emim' | 'trailblazer' | 'dynatrace' | 'cribl' | 'mcp' | 'aws_cli' | 'artifactory' | 'spinnaker' | 'amex_webex_captions' | 'deptracker' | 'do_service_catalog' | 'cloudwatch' | 'azure_devops' | 'azure' required

Canonical integration platform types.

Represents the platform or system where data originates from. Used to determine appropriate connectors, authentication, and API clients.

third_party_idstring nullable

Optional opaque identifier from the third-party system (e.g. a Log Store instance ID). Populated automatically from the integration payload when present.

enabled_data_typesstring[] required

List of data-type capabilities enabled for this integration (e.g. ["logs", "metrics"]). Controlled by the integration payload.

metadataobject

Non-secret integration-specific metadata stored with this instance.

created_atstring date-time nullable

ISO-8601 timestamp of when this integration instance was created.

updated_atstring date-time nullable

ISO-8601 timestamp of the most recent update to this instance.

created_bystring nullable

UUID of the user who created this integration instance, if known.

connector_idstring nullable

UUID of the org connector this instance routes through. Null when the instance connects over the public internet.

network_accessstring nullable

Name of the network this integration connects through (e.g. an internal VPN). Null when the integration connects over the public internet.

environment_labelsstring[]

The customer's own names for the environments this integration's data covers, e.g. ["prod", "staging"], normalized to lowercase. Empty when the instance has none. The single reserved value "unscoped" means the data is deliberately not split by environment, which is distinct from the empty list meaning nobody has labelled it yet.

Changes