---
title: "Install or replace an attribution plugin"
method: PUT
path: "/v1/ai-cost-management/ai-gateways/{gatewayId}/attribution-plugin"
tags: ["attribution-plugins"]
---

# Install or replace an attribution plugin

`PUT /v1/ai-cost-management/ai-gateways/{gatewayId}/attribution-plugin`

## Request

- Base URL: `https://global.api.konghq.com`
- URL: `https://global.api.konghq.com/v1/ai-cost-management/ai-gateways/{gatewayId}/attribution-plugin`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Installs the latest attribution plugin version on an AI Gateway with this configuration, or replaces the installed plugin and its configuration, and returns the installation.

- The plugin becomes a streaming custom policy named `ai-cost-attribution` and a global policy that turns it on. The request writes both through the AI Gateway API as the caller, so the caller also needs the AI Gateways Admin role on the gateway.
- Every request installs the latest version, so a `PUT` of the stored configuration updates an outdated installation.
- The plugin tags requests only on data planes that run AI Gateway 2.3 or later. Each data plane must run with `KONG_CUSTOM_PLUGIN_STREAMING_ENABLED=on`. A data plane with streaming off refuses the gateway's whole configuration while the plugin is installed.
- If the gateway doesn't have the plugin yet and a data plane the AI Gateway API lists reports streaming off, or doesn't report the setting because it runs an older release, the request fails with `409`, names those data planes, and changes nothing. The API lists a data plane for five minutes after its last ping, so a data plane replaced in that time can still be named. A data plane that connects later isn't checked, and neither is a gateway that already has the plugin.
- If the request fails partway, repeating it finishes the installation.
- If the body is invalid, the request fails with `400`. A header mapping that names a credential header, or repeats a header or tag key, counts as invalid.
- If the gateway already has a custom policy or policy of this name that this product didn't install, the request fails with `409` and changes nothing.
- If another change to the gateway's plugin is running, the request fails with `409` and changes nothing. Repeat it once that change has finished.

## Path parameters

- `gatewayId` string, uuid, required

## Request body

- AICostAttributionPluginConfiguration: The configuration of an attribution plugin installation. Header mappings follow tag capture's rules, so a credential header is refused, and `headers` and `prefixes` hold at most 32 entries together.
  - `integrations` AICostAttributionPluginIntegration[], required: The integrations whose headers the plugin reads. Any other tool's headers are ignored.
  - `headers` AICostAttributionPluginHeaderMapping[]: Request headers mapped to tag keys. Each header name and each tag key appears once, and `headers` and `prefixes` hold at most 32 entries together.
    - `name` string, required: The request header, compared case-insensitively. A credential header, or the start of one such as `x-goog` for `x-goog-api-key`, is refused.
    - `tag_key` string, required: The tag key the header's value becomes.
  - `prefixes` AICostAttributionPluginPrefixMapping[]: Header prefixes whose headers become tags. Each prefix appears once, and `headers` and `prefixes` hold at most 32 entries together.
    - `name` string, required: The prefix, compared case-insensitively. Every header named `<name>-<remainder>` becomes the tag `<remainder>`. A credential header, or the start of one, is refused.
  - `operator_tags` object: Tags the plugin adds to every request, as a map of tag key to value. A key has at most 128 characters: lowercase letters and digits in words joined by single hyphens.
  - `group_patterns` string[]: PCRE regular expressions that choose which groups the plugin keeps from the caller's token. A group is kept when any pattern matches its name, case-insensitively and anywhere in the name unless the pattern anchors itself. An empty list keeps every group, and each pattern appears once.

## Response `200`

The installation after the replacement.

- AICostAttributionPlugin: The attribution plugin installed on one AI Gateway, with its configuration.
  - `gateway_id` string, uuid, required: The ID of the AI Gateway the plugin is installed on.
  - `version` string, required: The plugin version installed on the gateway.
  - `latest_version` string, required: The newest plugin version. When it differs from `version`, a `PUT` of the stored configuration installs it.
  - `integrations` AICostAttributionPluginIntegration[], required: The integrations whose headers the plugin reads.
  - `headers` AICostAttributionPluginHeaderMapping[], required: Request headers mapped to tag keys.
    - `name` string, required: The request header, compared case-insensitively. A credential header, or the start of one such as `x-goog` for `x-goog-api-key`, is refused.
    - `tag_key` string, required: The tag key the header's value becomes.
  - `prefixes` AICostAttributionPluginPrefixMapping[], required: Header prefixes whose headers become tags.
    - `name` string, required: The prefix, compared case-insensitively. Every header named `<name>-<remainder>` becomes the tag `<remainder>`. A credential header, or the start of one, is refused.
  - `operator_tags` object, required: Tags the plugin adds to every request.
  - `group_patterns` string[], required: PCRE regular expressions that choose which groups the plugin keeps from the caller's token.
  - `created_at` string, date-time, required: An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time, required: An ISO-8601 timestamp representation of entity update date.

## Other responses

- `201`: The new installation.
- `400`: The request body is invalid, or the AI Gateway API refused it. `invalid_parameters` names each invalid field, such as `headers[2].name`.
- `401`: The request has no valid access token. The token is missing, malformed, or expired, or it fails another check, and the response doesn't say which.
- `403`: The access token is valid, but its principal lacks the permission this operation requires. For an operation on one resource, the response doesn't reveal whether that resource exists.
- `404`: The organization has no AI Gateway with this ID.
- `409`: The gateway already has a custom policy or policy of this name that this product didn't install, a data plane of a gateway without the plugin runs with streaming off, or another change to its plugin is running.

## Changes

- **2026-11-19** `3b071797f6e4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/kong/apis/konnect-api-go-sdk/changes/v1/ai-cost-management/ai-gateways/:gatewayId/attribution-plugin/put.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api-go-sdk.md) - [All operations](https://skmtc.dev/kong/apis/konnect-api-go-sdk/llms.txt) - [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api-go-sdk/revisions/3b071797f6e4?raw)
