> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an AI integration

> Update an AI integration's configuration. At least one field must be provided.
Omitted fields are left unchanged.

**Payload Requirements**
- At least one of the updatable fields must be provided.
- `name`, if provided, must be unique within the account.
- `api_key` can be set to `null` to remove the existing key, or omitted to keep it unchanged.
- `scopings`, if provided, replaces all existing scoping rules.
- `provider_metadata`, if provided, replaces existing metadata. Set to `null` to remove.

**Valid example**
```json
{
  "name": "Updated Integration",
  "model_names": ["gpt-4o", "gpt-4o-mini"]
}
```

**Invalid example** (empty body)
```json
{}
```

<Warning>This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml patch /v2/ai-integrations/{integration_id}
openapi: 3.0.3
info:
  title: Arize REST API
  version: 2.0.0
  description: |
    API specification for the backend data server. The API is hosted globally
    at https://api.arize.com/v2 or in your own environment.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: eu-west-1a
        enum:
          - eu-west-1a
          - ca-central-1a
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
security:
  - bearerAuth: []
tags:
  - name: AI Integrations
    description: |
      AI integrations configure access to external LLM providers (e.g. OpenAI,
      Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
      entire account, a specific organization, or a specific space.
  - name: Annotation Configs
    description: >
      Annotation configs allow you to define consistent annotation schemas that

      can be reused across your workspace, ensuring evaluations are structured
      and

      comparable over time.
  - name: Annotation Queues
    description: >
      Annotation queues help you organize and manage human evaluation workflows.

      Use queues to assign spans or examples to annotators for review and
      labeling.
  - name: API Keys
    description: >
      API keys are used to authenticate requests to the Arize API. List your
      keys

      to view metadata; the raw secret is never returned after creation.
  - name: Datasets
    description: |
      Datasets are structured, version-controlled example collections you use to
      run, evaluate, and track LLM experiments.
  - name: Evaluators
    description: >
      Evaluators are reusable evaluation configurations used to assess the
      quality

      of LLM outputs. They can be template-based (using LLM judges) or
      code-based.
  - name: Experiments
    description: >
      Experiments let you systematically test prompt/model changes using
      datasets,

      tasks, and evaluators.
  - name: Integrations
    description: >
      Integrations configure access to external LLM providers (e.g. OpenAI,

      Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
      PagerDuty, Slack), and

      your own agents. Integrations can be scoped to the entire account, a
      specific

      organization, or a specific space.
  - name: Organizations
    description: >
      Organizations are top-level containers within an Arize AX account for
      grouping spaces.
  - name: Projects
    description: |
      Projects represent LLM applications being monitored in Arize where you can
      observe traces and spans.
  - name: Prompts
    description: >
      Prompts are reusable, versioned templates for LLM interactions. Use
      prompts

      to standardize and manage how you interact with LLMs across your
      application.
  - name: Resource Restrictions
    description: |
      Endpoints for restricting and unrestricting resources (projects, models).
  - name: Role Bindings
    description: |
      Role bindings assign a role to a user on a resource. REST currently
      supports space- and project-scoped bindings.
  - name: Roles
    description: >
      Roles define sets of permissions that can be assigned to users within an

      account. Create custom roles to tailor access control to your team's
      needs.
  - name: Spaces
    description: >
      Spaces are containers within an organization for grouping related
      projects,

      datasets, and experiments, enabling collaboration or isolated
      experimentation

      with role-based access control.
  - name: Spans
    description: |
      Spans represent individual operations within a trace. A span captures the
      timing, status, and attributes of a single operation in your application.
  - name: Tasks
    description: |
      Tasks are configurable units of work that tie one or more evaluators to a
      data source (project or dataset). Use tasks to automate evaluation of LLM
      outputs, with support for continuous evaluation and backfill runs.
  - name: Users
    description: >
      Users represent members of an account. The Users endpoints allow creating,

      listing, updating (display name), and removing users from the account
      programmatically.
paths:
  /v2/ai-integrations/{integration_id}:
    patch:
      tags:
        - AI Integrations
      summary: Update an AI integration
      description: >
        Update an AI integration's configuration. At least one field must be
        provided.

        Omitted fields are left unchanged.


        **Payload Requirements**

        - At least one of the updatable fields must be provided.

        - `name`, if provided, must be unique within the account.

        - `api_key` can be set to `null` to remove the existing key, or omitted
        to keep it unchanged.

        - `scopings`, if provided, replaces all existing scoping rules.

        - `provider_metadata`, if provided, replaces existing metadata. Set to
        `null` to remove.


        **Valid example**

        ```json

        {
          "name": "Updated Integration",
          "model_names": ["gpt-4o", "gpt-4o-mini"]
        }

        ```


        **Invalid example** (empty body)

        ```json

        {}

        ```


        <Warning>This endpoint is in alpha, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>
      operationId: ai_integrations_update
      parameters:
        - $ref: '#/components/parameters/AiIntegrationIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/UpdateAiIntegrationRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AiIntegration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    AiIntegrationIdPathParam:
      name: integration_id
      in: path
      description: The unique AI integration identifier (base64)
      required: true
      schema:
        $ref: '#/components/schemas/Id'
      example: TGxtSW50ZWdyYXRpb246MTI6YUJjRA==
  requestBodies:
    UpdateAiIntegrationRequestBody:
      description: >-
        Body containing AI integration update parameters. At least one field
        must be provided.
      required: true
      content:
        application/json:
          schema:
            type: object
            minProperties: 1
            properties:
              name:
                type: string
                description: New integration name
              provider:
                $ref: '#/components/schemas/AiIntegrationProvider'
              api_key:
                type: string
                nullable: true
                description: >-
                  New API key. Pass null to remove the existing key. Omit to
                  keep unchanged.
              base_url:
                type: string
                nullable: true
                description: Custom base URL. Pass null to remove.
              model_names:
                type: array
                items:
                  type: string
                description: Supported model names (replaces all)
              headers:
                type: object
                nullable: true
                additionalProperties:
                  type: string
                description: Custom headers. Pass null to remove.
              enable_default_models:
                type: boolean
                description: Enable provider's default model list
              function_calling_enabled:
                type: boolean
                description: Enable function/tool calling
              auth_type:
                $ref: '#/components/schemas/AiIntegrationAuthType'
              provider_metadata:
                type: object
                nullable: true
                discriminator:
                  propertyName: kind
                  mapping:
                    aws:
                      $ref: '#/components/schemas/AwsProviderMetadata'
                    gcp:
                      $ref: '#/components/schemas/GcpProviderMetadata'
                oneOf:
                  - $ref: '#/components/schemas/AwsProviderMetadata'
                  - $ref: '#/components/schemas/GcpProviderMetadata'
                description: >-
                  Provider-specific configuration. For awsBedrock, must include
                  role_arn. For vertexAI, must include project_id, location, and
                  project_access_label. Pass null to remove.
              scopings:
                type: array
                items:
                  $ref: '#/components/schemas/AiIntegrationScoping'
                description: Visibility scoping rules (replaces all existing scopings)
            additionalProperties: false
          example:
            name: Updated OpenAI Integration
            api_key: null
            model_names:
              - gpt-4o
              - gpt-4o-mini
  responses:
    AiIntegration:
      description: An AI integration object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AiIntegration'
          example:
            id: TGxtSW50ZWdyYXRpb246MTI6YUJjRA==
            name: My OpenAI Integration
            provider: openAI
            has_api_key: true
            model_names:
              - gpt-4
              - gpt-4o
            enable_default_models: true
            function_calling_enabled: true
            auth_type: default
            scopings:
              - {}
            created_at: '2026-02-13T21:27:19.055Z'
            updated_at: '2026-02-13T21:27:19.279Z'
            created_by_user_id: VXNlcjoxOm5OYkM=
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 400
            title: Invalid request parameters
            detail: The 'name' field is required and must be a non-empty string.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
    Unauthorized:
      description: Authentication is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Authentication required
            detail: You must be authenticated to access this resource.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#authentication-required
    Forbidden:
      description: Insufficient permissions to access this resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Access forbidden
            detail: You do not have permission to access this resource.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 404
            title: Resource not found
            detail: The requested resource with ID '12345' was not found.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
    Conflict:
      description: Resource conflict
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 409
            title: Resource conflict
            detail: A resource with the given identifier already exists.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#resource-conflict
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 422
            title: Unprocessable Entity
            detail: Minimum score must be less than maximum score.
            instance: /annotation-configs
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: |
            When throttled (429), how long to wait before retrying. Value is
            either a delta-seconds integer.
          schema:
            type: integer
            minimum: 0
          example: 42
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 429
            title: Rate limit exceeded
            detail: >-
              You have exceeded the allowed number of requests. Please try again
              later.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
  schemas:
    Id:
      type: string
      description: A universally unique identifier (base64-encoded opaque string).
      example: RW50aXR5OjEyMzQ1
    AiIntegrationProvider:
      type: string
      enum:
        - openAI
        - azureOpenAI
        - awsBedrock
        - vertexAI
        - anthropic
        - custom
        - nvidiaNim
        - gemini
      description: The AI provider for this integration
    AiIntegrationAuthType:
      type: string
      enum:
        - default
        - proxy_with_headers
        - bearer_token
      description: The authentication method for this integration
    AwsProviderMetadata:
      type: object
      description: AWS Bedrock provider metadata
      required:
        - kind
        - role_arn
      properties:
        kind:
          $ref: '#/components/schemas/AwsProviderMetadataKind'
        role_arn:
          type: string
          description: AWS IAM role ARN for cross-account access
        external_id:
          type: string
          nullable: true
          description: External ID for the assume-role policy
    GcpProviderMetadata:
      type: object
      description: Vertex AI (GCP) provider metadata
      required:
        - kind
        - project_id
        - location
        - project_access_label
      properties:
        kind:
          $ref: '#/components/schemas/GcpProviderMetadataKind'
        project_id:
          type: string
          description: GCP project ID
        location:
          type: string
          description: GCP region (e.g. us-central1)
        project_access_label:
          type: string
          description: Display label for the project
    AiIntegrationScoping:
      type: object
      description: Visibility scoping for the integration
      properties:
        organization_id:
          type: string
          nullable: true
          description: Organization identifier (base64). Null means account-wide.
        space_id:
          type: string
          nullable: true
          description: >-
            Space identifier (base64). Null means organization-wide (or
            account-wide if organization_id is also null).
    AiIntegration:
      type: object
      required:
        - id
        - name
        - provider
        - has_api_key
        - enable_default_models
        - function_calling_enabled
        - auth_type
        - scopings
        - created_at
        - updated_at
        - created_by_user_id
      properties:
        id:
          type: string
          description: The integration ID
        name:
          type: string
          description: The integration name
        provider:
          $ref: '#/components/schemas/AiIntegrationProvider'
        has_api_key:
          type: boolean
          description: Whether an API key is configured (the key itself is never returned)
        base_url:
          type: string
          nullable: true
          description: Custom base URL for the provider
        model_names:
          type: array
          nullable: true
          items:
            type: string
          description: Supported model names
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Custom headers included in requests
        enable_default_models:
          type: boolean
          description: Whether the provider's default model list is enabled
        function_calling_enabled:
          type: boolean
          description: Whether function/tool calling is enabled
        auth_type:
          $ref: '#/components/schemas/AiIntegrationAuthType'
        provider_metadata:
          type: object
          nullable: true
          discriminator:
            propertyName: kind
            mapping:
              aws:
                $ref: '#/components/schemas/AwsProviderMetadata'
              gcp:
                $ref: '#/components/schemas/GcpProviderMetadata'
          oneOf:
            - $ref: '#/components/schemas/AwsProviderMetadata'
            - $ref: '#/components/schemas/GcpProviderMetadata'
          description: >-
            Provider-specific configuration. For awsBedrock, must include
            role_arn. For vertexAI, must include project_id, location, and
            project_access_label.
        scopings:
          type: array
          items:
            $ref: '#/components/schemas/AiIntegrationScoping'
          description: Visibility scoping rules
        created_at:
          type: string
          format: date-time
          description: When the integration was created
        updated_at:
          type: string
          format: date-time
          description: When the integration was last updated
        created_by_user_id:
          type: string
          description: The user ID of the user who created the integration
      description: >
        An AI integration configures access to an external LLM provider (e.g.
        OpenAI,

        Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
        entire

        account, a specific organization, or a specific space.
      additionalProperties: false
    Problem:
      type: object
      description: RFC 9457 Problem Details
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem
        type:
          type: string
          format: uri-reference
          description: A URI reference that identifies the problem type
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
      required:
        - title
        - status
      additionalProperties: false
    AwsProviderMetadataKind:
      type: string
      enum:
        - aws
      description: Discriminator value identifying AWS Bedrock provider metadata.
    GcpProviderMetadataKind:
      type: string
      enum:
        - gcp
      description: Discriminator value identifying Vertex AI (GCP) provider metadata.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api-key>
      description: >
        Most Arize AI endpoints require authentication. For those endpoints that
        require authentication, include your API key in the request header using
        the format

        ``` Authorization: Bearer <api-key>

        ```

````