---
title: "Update"
method: PUT
path: "/v3/integrations/{id}"
tags: ["integrations-v3"]
---

# Update

`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

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.

## Path parameters

- `id` string, required

## Query parameters

- `organization_id` string, nullable

## Request body

- UpdateIntegrationV3Request: Request body for updating an integration instance. All fields are optional. Omitting a field leaves that aspect of the integration unchanged. Supplying ``integration`` rotates the stored credentials and refreshes the cached configuration snapshot. To rename without touching credentials, send only ``name``. To rotate credentials without renaming, send only ``integration``.
  - `name` string, nullable: New display name for the integration instance. Leave ``null`` to keep the existing name.
  - `description` string, 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.
  - `integration` object, 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_access` string, 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_descriptions` object, 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_labels` string[], 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 `200`

Successful Response

- IntegrationInstanceResponse: Metadata about a single integration instance. Credential fields are never included in this response. Use the integration-type-specific credential rotation endpoints to update secrets.
  - `id` string, required: Stable UUID for this integration instance. Use this in PUT /v3/integrations/{id} and DELETE /v3/integrations/{id}.
  - `organization_id` string, required: UUID of the organization that owns this integration instance.
  - `name` string, required: Human-readable display name set at creation time.
  - `description` string, 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_id` string, 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_types` string[], required: List of data-type capabilities enabled for this integration (e.g. ``["logs", "metrics"]``). Controlled by the integration payload.
  - `metadata` object: Non-secret integration-specific metadata stored with this instance.
  - `created_at` string, date-time, nullable: ISO-8601 timestamp of when this integration instance was created.
  - `updated_at` string, date-time, nullable: ISO-8601 timestamp of the most recent update to this instance.
  - `created_by` string, nullable: UUID of the user who created this integration instance, if known.
  - `last_health_check` HealthCheckResponse: Aggregate result of an integration's connection health check.
    - `status` 'pending' | 'connected' | 'partial' | 'failed', required: Overall status of a connection health check.
    - `steps` HealthCheckStepResponse[], required
      - `step` 'connectivity' | 'auth' | 'query', required: Identifies which health check step a result is for.
      - `passed` boolean, required
      - `message` string, required
      - `details` object
    - `checked_at` string, date-time, required
  - `connector_id` string, nullable: UUID of the org connector this instance routes through. Null when the instance connects over the public internet.
  - `network_access` string, nullable: Name of the network this integration connects through (e.g. an internal VPN). Null when the integration connects over the public internet.
  - `environment_labels` string[]: 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.

## Other responses

- `422`: Validation Error

## Changes

> 66 revisions in range; 9 not diffed.

- **2026-10-06** `31e1a8b7cf89`: 1 warning
  - added the new `azure` enum value to the `type` response property for the response status `200`
- **2026-09-26** `75b9e4398c46`: 1 warning
  - added the new `traversal` enum value to the `type` response property for the response status `200`
- **2026-09-24** `2fc80b73eb41`: 1 warning
  - added the new `pagerduty` enum value to the `type` response property for the response status `200`
- **2026-09-23** `3da9c3d0385f`: 1 warning
  - added the new `azure_devops` enum value to the `type` response property for the response status `200`
- **2026-09-18** `af140c3c54d8`: 1 warning
  - added the new `github_webhook` enum value to the `type` response property for the response status `200`

[Operation history](https://skmtc.dev/traversal/apis/traversal-api/changes/v3/integrations/:id/put.md)

---

[API](https://skmtc.dev/traversal/apis/traversal-api.md) - [All operations](https://skmtc.dev/traversal/apis/traversal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traversal/apis/traversal-api/revisions/31e1a8b7cf89?raw)