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

# Update

`PUT /v3/integrations/{id}`

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.

**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 — Agent-facing MCP tool descriptions keyed by raw MCP tool name. Dynamic MCP tools without a non-empty configured description are not searchable by the agent. This is metadata only and does not rotate integration credentials.

## 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' | 'gitlab' | 'thousandeyes' | 'linear' | 'notion' | 'loki' | 'opensearch' | 'splunk' | 'gcp' | 'motherduck' | 'confluence' | 'coralogix' | 'firehydrant' | 'slack' | 'teams' | 'jira' | 'kubernetes' | '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', 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
  - `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.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/traversal/apis/fastapi.md) · [All operations](https://skmtc.net/traversal/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/traversal/fastapi/revisions/2134ebffd1ef/schema)