Sign in
latestOpenAPI 3.1.02026-08-223321,1001.6 MB

2134ebffd1ef

integrations-v3

Update

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.

put/v3/integrations/{id}

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

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

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' | '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_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.

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.