---
title: "Create an integration"
method: POST
path: "/v2/integrations"
tags: ["Integrations"]
---

# Create an integration

`POST /v2/integrations`

Create a new integration. The `type` field selects the config shape;
for `LLM`, `config.provider` selects the per-provider config. v1
supports `type=LLM` (provider `OPEN_AI`) and `type=AGENT`.

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

## Request body

- union
  - object
    - `type` 'LLM', required
    - `name` string, required — Integration name. Unique per (account, type).
    - `scopings` IntegrationScopingRequest[] — Visibility scoping rules. Defaults to account-wide.
      - `organization_id` string, nullable — Organization identifier (base64). Null means account-wide.
      - `space_id` string, nullable — Space identifier (base64). Null means organization-wide (or account-wide when organization_id is also null).
    - `config` union, required
      - object — Create config for an OpenAI LLM integration. `api_key` is required and is write-only (never returned in responses).
        - `is_function_calling_enabled` boolean — Enable function/tool calling. Defaults to true.
        - `provider` 'OPEN_AI', required
        - `api_key` string, required — API key for the provider (write-only, never returned).
      - object — Create config for an Anthropic LLM integration. `api_key` is required and is write-only (never returned in responses). `base_url` is optional; omit it to use the public Anthropic API.
        - `is_function_calling_enabled` boolean — Enable function/tool calling. Defaults to true.
        - `provider` 'ANTHROPIC', required
        - `api_key` string, required — API key for the provider (write-only, never returned).
        - `base_url` string — Endpoint URL (HTTPS) serving the Anthropic Messages API, including the version path (e.g. `https://api.anthropic.com/v1`). Do not include `/messages`, which is appended automatically. Defaults to the public Anthropic API.
      - object — Create config for a Google Gemini LLM integration. `api_key` is required and is write-only (never returned in responses).
        - `is_function_calling_enabled` boolean — Enable function/tool calling. Defaults to true.
        - `provider` 'GEMINI', required
        - `api_key` string, required — API key for the provider (write-only, never returned).
      - object — Create config for an AWS Bedrock LLM integration. `auth` selects one of three auth modes via `auth_type`. The integration must have at least one model available: enable `is_default_models_enabled` or provide at least one entry in `model_names`, otherwise the request is rejected with 422.
        - `provider` 'AWS_BEDROCK', required
        - `auth` union, required — AWS Bedrock auth settings for create and update, discriminated by `auth_type`. On PATCH this object replaces the stored auth settings wholesale (auth_type may change); omitted fields of the previous auth mode are cleared.
          - object — Create role-assumption auth. `role_arn` is required.
            - `auth_type` 'DEFAULT', required
            - `role_arn` string, required — AWS IAM role ARN Arize assumes for cross-account access.
            - `external_id` string — External ID on the assume-role policy. Defaults to not set.
            - `base_url` string — Custom Bedrock endpoint URL. Defaults to the provider default endpoint.
          - object — Create bearer-token auth. `api_key` is required and write-only (never returned; surfaces as `has_api_key` on read).
            - `auth_type` 'BEARER_TOKEN', required
            - `api_key` string, required — Bearer token for Bedrock (write-only, never returned).
            - `base_url` string — Custom Bedrock endpoint URL. Defaults to the provider default endpoint.
          - object — Create proxy auth. `base_url` is required. `headers` is write-only; names are returned as `header_names` on read.
            - `auth_type` 'PROXY_WITH_HEADERS', required
            - `base_url` string, required — Proxy URL requests are forwarded to (HTTPS).
            - `headers` object — Custom request headers sent to the proxy, as a name-to-value map. Write-only: values are never returned; names are exposed as `header_names` on read. Defaults to no headers. The serialized header map must not exceed 8,175 bytes.
        - `is_default_models_enabled` boolean — Enable Arize's default Bedrock model catalog. Defaults to false.
        - `model_names` string[] — Custom model names to make available. Defaults to none.
      - object — Create config for a custom OpenAI-compatible endpoint integration. `base_url` is required and must implement the OpenAI API shape (it is validated server-side and must resolve to a public address). `api_key` and `headers` are write-only (never returned; headers surface as `header_names` on read). The integration must have at least one model source: enable `is_default_models_enabled` or provide at least one entry in `model_names`, otherwise the request is rejected with 422.
        - `is_function_calling_enabled` boolean — Enable function/tool calling. Defaults to true.
        - `provider` 'CUSTOM', required
        - `base_url` string, required — Endpoint URL requests are sent to (HTTPS).
        - `api_key` string — API key for the endpoint (write-only, never returned).
        - `headers` object — Custom request headers sent to the endpoint, as a name-to-value map. Write-only: values are never returned; names are exposed as `header_names` on read. Defaults to no headers. The serialized header map must not exceed 8,175 bytes.
        - `is_default_models_enabled` boolean — Enable Arize's default model catalog. Defaults to false.
        - `model_names` string[] — Custom model names to make available. Defaults to none.
      - object — Create config for a Google Vertex AI integration. No credentials are stored: Arize accesses Vertex through the configured GCP project. `project_id`, `location`, and `project_access_label` are all required.
        - `provider` 'VERTEX_AI', required
        - `project_id` string, required — GCP project ID Arize accesses Vertex through.
        - `location` string, required — GCP region (e.g. us-central1).
        - `project_access_label` string, required — Label used to verify Arize's access to the GCP project.
      - object — Create config for an NVIDIA NIM integration. Every connection field is optional: omit `base_url` to use the provider default endpoint, or set it to a self-hosted NIM endpoint (validated server-side). `api_key` and `headers` are write-only (never returned; headers surface as `header_names` on read). The integration must have at least one model source: enable `is_default_models_enabled` or provide at least one entry in `model_names`, otherwise the request is rejected with 422.
        - `is_function_calling_enabled` boolean — Enable function/tool calling. Defaults to true.
        - `provider` 'NVIDIA_NIM', required
        - `base_url` string — Self-hosted NIM endpoint URL (HTTPS). Defaults to the provider default endpoint.
        - `api_key` string — API key for the endpoint (write-only, never returned).
        - `headers` object — Custom request headers sent to the endpoint, as a name-to-value map. Write-only: values are never returned; names are exposed as `header_names` on read. Defaults to no headers. The serialized header map must not exceed 8,175 bytes.
        - `is_default_models_enabled` boolean — Enable Arize's default model catalog. Defaults to false.
        - `model_names` string[] — Custom model names to make available. Defaults to none.
  - object
    - `type` 'AGENT', required
    - `name` string, required — Integration name (unique within the account).
    - `description` string, nullable
    - `scopings` IntegrationScopingRequest[] — Visibility scoping rules. Defaults to account-wide if omitted or empty. A scoping with `space_id` set MUST also set `organization_id`.
      - `organization_id` string, nullable — Organization identifier (base64). Null means account-wide.
      - `space_id` string, nullable — Space identifier (base64). Null means organization-wide (or account-wide when organization_id is also null).
    - `config` CreateAgentConfig, required
      - `endpoint` string, uri, required — HTTPS endpoint requests are sent to. Validated server-side and must resolve to a public address.
      - `headers` object — Cleartext header map. Encrypted at rest; never returned in responses.
      - `input_schema` object, required — JSON Schema (Draft-07) the endpoint's request body conforms to.
      - `request_presets` CreateAgentRequestPresetInput[] — Optional initial presets for the integration.
        - `name` string, required — Preset name (unique within the integration). Length 1-255.
        - `description` string, nullable — Optional preset description (length 0-1024).
        - `config` object, required — Partial request body. Validated against the parent integration's `input_schema` with `required` dropped.

## Response `201`

An integration object.

- union — A polymorphic integration resource. The `type` field selects the `config` shape; for `LLM`, `config.provider` selects the per-provider config.
  - object — An LLM integration (type=LLM).
    - `id` string, required — The unique identifier for the integration.
    - `type` 'LLM', required — Discriminator identifying an LLM integration.
    - `name` string, required — The integration name. Unique per (account, type).
    - `scopings` IntegrationScoping[], required — Visibility scoping rules. Account-wide when empty.
      - `organization_id` string, nullable — Organization identifier (base64). Null means account-wide.
      - `space_id` string, nullable — Space identifier (base64). Null means organization-wide (or account-wide when organization_id is also null).
    - `created_at` string, date-time, required — When the integration was created.
    - `updated_at` string, date-time, required — When the integration was last updated.
    - `created_by_user_id` string, required — Unique identifier of the user who created the integration.
    - `config` union, required — Per-provider LLM config, discriminated by `provider`.
      - object — Config for an OpenAI LLM integration.
        - `is_function_calling_enabled` boolean, required — Whether function/tool calling is enabled.
        - `provider` 'OPEN_AI', required — Discriminator identifying the OpenAI provider.
        - `has_api_key` boolean, required — Whether an API key is configured (the key itself is never returned).
      - object — Config for an Anthropic LLM integration.
        - `is_function_calling_enabled` boolean, required — Whether function/tool calling is enabled.
        - `provider` 'ANTHROPIC', required — Discriminator identifying the Anthropic provider.
        - `has_api_key` boolean, required — Whether an API key is configured (the key itself is never returned).
        - `base_url` string, nullable — Endpoint URL serving the Anthropic Messages API, including the version path. Null when not set.
      - object — Config for a Google Gemini LLM integration.
        - `is_function_calling_enabled` boolean, required — Whether function/tool calling is enabled.
        - `provider` 'GEMINI', required — Discriminator identifying the Gemini provider.
        - `has_api_key` boolean, required — Whether an API key is configured (the key itself is never returned).
      - object — Config for an AWS Bedrock LLM integration. The model catalog is caller-controlled via `is_default_models_enabled` and `model_names`. Function/tool-calling settings do not apply to Bedrock and are omitted.
        - `provider` 'AWS_BEDROCK', required — Discriminator identifying the AWS Bedrock provider.
        - `is_default_models_enabled` boolean, required — Whether Arize's default Bedrock model catalog is enabled.
        - `model_names` string[], required — Custom model names configured on this integration. Empty when none.
        - `auth` union, required — AWS Bedrock auth settings, discriminated by `auth_type`.
          - object — Role-assumption auth for AWS Bedrock: Arize assumes the provided IAM role to call Bedrock. The role ARN and external ID are not secrets and are returned on read.
            - `auth_type` 'DEFAULT', required — Discriminator identifying role-assumption auth.
            - `role_arn` string, required — AWS IAM role ARN Arize assumes for cross-account access.
            - `external_id` string, nullable, required — External ID on the assume-role policy. Null when not set.
            - `base_url` string, nullable, required — Custom Bedrock endpoint URL. Null when not set.
          - object — Bearer-token auth for AWS Bedrock. The token surfaces as `has_api_key` on read; the token itself is never returned.
            - `auth_type` 'BEARER_TOKEN', required — Discriminator identifying bearer-token auth.
            - `has_api_key` boolean, required — Whether a bearer token is configured (the token itself is never returned). Always true for integrations created through this API; may be false for integrations created through the Arize UI without a token.
            - `base_url` string, nullable, required — Custom Bedrock endpoint URL. Null when not set.
          - object — Proxy auth for AWS Bedrock: requests are forwarded to a proxy URL with custom headers. Header values are write-only; configured names are returned as `header_names`.
            - `auth_type` 'PROXY_WITH_HEADERS', required — Discriminator identifying proxy auth.
            - `base_url` string, required — Proxy URL requests are forwarded to.
            - `header_names` string[], required — Names of the custom request headers configured on this integration. Empty when none are configured. Header values are write-only and never returned.
      - object — Config for a custom OpenAI-compatible endpoint integration. `base_url` is the endpoint Arize sends requests to; it must implement the OpenAI API shape. Secrets are write-only: the API key surfaces as `has_api_key` and custom request headers surface as `header_names` (names only).
        - `is_function_calling_enabled` boolean, required — Whether function/tool calling is enabled.
        - `provider` 'CUSTOM', required — Discriminator identifying a custom OpenAI-compatible endpoint.
        - `has_api_key` boolean, required — Whether an API key is configured (the key itself is never returned).
        - `base_url` string, required — Endpoint URL requests are sent to.
        - `header_names` string[], required — Names of the custom request headers configured on this integration. Empty when none are configured. Header values are write-only and never returned.
        - `is_default_models_enabled` boolean, required — Whether Arize's default model catalog is enabled.
        - `model_names` string[], required — Custom model names configured on this integration. Empty when none.
      - object — Config for a Google Vertex AI integration. Vertex stores no credentials: Arize accesses Vertex through the configured GCP project. All fields are returned on read.
        - `provider` 'VERTEX_AI', required — Discriminator identifying the Vertex AI provider.
        - `project_id` string, required — GCP project ID Arize accesses Vertex through.
        - `location` string, required — GCP region (e.g. us-central1).
        - `project_access_label` string, required — Label used to verify Arize's access to the GCP project.
      - object — Config for an NVIDIA NIM integration. Every connection field is optional: `base_url` targets a self-hosted NIM endpoint (null when using the provider default). Secrets are write-only: the API key surfaces as `has_api_key` and custom request headers surface as `header_names` (names only).
        - `is_function_calling_enabled` boolean, required — Whether function/tool calling is enabled.
        - `provider` 'NVIDIA_NIM', required — Discriminator identifying the NVIDIA NIM provider.
        - `has_api_key` boolean, required — Whether an API key is configured (the key itself is never returned).
        - `base_url` string, nullable, required — Self-hosted NIM endpoint URL. Null when not set.
        - `header_names` string[], required — Names of the custom request headers configured on this integration. Empty when none are configured. Header values are write-only and never returned.
        - `is_default_models_enabled` boolean, required — Whether Arize's default model catalog is enabled.
        - `model_names` string[], required — Custom model names configured on this integration. Empty when none.
  - object — An agent integration (type=AGENT): a customer-hosted HTTPS endpoint plus a JSON Schema describing the request payload.
    - `id` string, required — The unique identifier for the integration.
    - `type` 'AGENT', required — Discriminator identifying an agent integration.
    - `name` string, required — The integration name. Unique per (account, type).
    - `description` string, nullable — Optional human-readable description of the integration.
    - `scopings` IntegrationScoping[], required — Visibility scoping rules. Account-wide when empty.
      - `organization_id` string, nullable — Organization identifier (base64). Null means account-wide.
      - `space_id` string, nullable — Space identifier (base64). Null means organization-wide (or account-wide when organization_id is also null).
    - `created_at` string, date-time, required — When the integration was created.
    - `updated_at` string, date-time, required — When the integration was last updated.
    - `created_by_user_id` string, nullable, required — Unique identifier of the user who created the integration. Null if that user has since been deleted.
    - `config` AgentConfig, required — Configuration for `type: AGENT` integrations: a customer-hosted HTTPS endpoint plus a JSON Schema describing the request payload.
      - `endpoint` string, uri, required — HTTPS endpoint URL Arize calls for replay. Validated server-side for SSRF (must resolve to a public address).
      - `has_headers` boolean, required — Whether any headers are configured. Read-only — derived from `headers` on write. Header values are never returned.
      - `input_schema` object, required — JSON Schema (Draft-07) the endpoint's request body conforms to.
      - `request_presets` AgentRequestPreset[], required — Named, reusable request payloads. Replace-on-provide on PATCH. Always present; an integration with no presets returns `[]`.
        - `id` string — Server-generated, opaque preset identifier. Read-only.
        - `name` string, required — Preset name (unique within the integration). Length 1-255.
        - `description` string, nullable — Optional preset description (length 0-1024).
        - `config` object, required — Partial request body. Validated against the parent integration's `input_schema` with `required` dropped.
        - `created_at` string, date-time
        - `updated_at` string, date-time

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `409` — Resource conflict
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)