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

# Create or update custom integration



## OpenAPI

````yaml https://api.galileo.ai/public/v2/openapi.json put /v2/integrations/custom
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.galileo.ai
    description: Galileo Public APIs - galileo-v2
security: []
paths:
  /v2/integrations/custom:
    put:
      tags:
        - integrations
      summary: Create or update custom integration
      operationId: create_or_update_integration_v2_integrations_custom_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomIntegrationCreate'
              examples:
                - authentication_type: oauth2
                  models:
                    - custom-model-1
                    - custom-model-2
                  endpoint: https://api.custom-provider.com/v1
                  authentication_scope: chat.completions
                  oauth2_token_url: https://api.custom-provider.com/oauth2/token
                  token: your_oauth2_client_credentials_json
                  default_model: custom-model-1
                - authentication_type: none
                  models:
                    - custom-model-1
                    - custom-model-2
                  endpoint: https://internal-gateway.local/v1
                  default_model: custom-model-1
                - authentication_type: api_key
                  models:
                    - custom-model-1
                    - custom-model-2
                  endpoint: https://api.gateway-provider.com/v1
                  api_key_header: X-API-Key
                  api_key_value: your_api_key_here
                  headers:
                    X-Custom-Header: custom-value
                    X-Another-Header: another-value
                  default_model: custom-model-1
                  custom_llm_config:
                    file_name: proprietary_handler.py
                    class_name: ProprietaryLLMHandler
                    init_kwargs:
                      timeout: 60
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationDB'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
        - OAuth2PasswordBearer: []
        - HTTPBasic: []
components:
  schemas:
    CustomIntegrationCreate:
      properties:
        multi_modal_config:
          anyOf:
            - $ref: '#/components/schemas/MultiModalModelIntegrationConfig'
            - type: 'null'
          description: Configuration for multi-modal (file upload) capabilities.
        authentication_type:
          $ref: '#/components/schemas/CustomAuthenticationType'
          default: oauth2
        models:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Models
          description: >-
            List of model names for the custom integration. Deprecated: use
            model_properties instead.
        model_properties:
          anyOf:
            - items:
                $ref: '#/components/schemas/ModelProperties'
              type: array
            - type: 'null'
          title: Model Properties
          description: >-
            List of model properties with name and alias for the custom
            integration.
        is_legacy_format:
          type: boolean
          title: Is Legacy Format
          description: >-
            Internal: whether this config was created from the legacy 'models'
            field.
          default: false
        default_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Default Model
          description: Default model to use. If not provided, defaults to the first model.
        endpoint:
          type: string
          title: Endpoint
          description: Endpoint URL for the custom integration.
        authentication_scope:
          anyOf:
            - type: string
            - type: 'null'
          title: Authentication Scope
          description: Optional scope for OAuth2 authentication.
        oauth2_token_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Oauth2 Token Url
          description: >-
            OAuth2 token URL for custom OAuth2 authentication. If not provided,
            defaults to the endpoint.
        api_key_header:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key Header
          description: >-
            HTTP header name to use for API key authentication (e.g.,
            'X-API-Key', 'Authorization').
        api_key_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Api Key Value
          description: API key value to send in the specified header for authentication.
        custom_llm_config:
          anyOf:
            - $ref: '#/components/schemas/CustomLLMConfig'
            - type: 'null'
          description: >-
            Optional configuration for a custom LiteLLM handler class. When
            specified, the handler's acompletion() method is used instead of the
            default litellm.acompletion().
        custom_header_mapping:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Custom Header Mapping
          description: >-
            Custom header mapping from internal fields (job_id, user_id,
            project_id, run_id) to custom header names to be included in LLM
            requests.
        headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
              maxProperties: 50
            - type: 'null'
          title: Headers
          description: >-
            Optional custom HTTP headers to include in requests to the
            integration endpoint. Stored encrypted at rest.
        token:
          anyOf:
            - type: string
            - type: 'null'
          title: Token
      type: object
      required:
        - endpoint
      title: CustomIntegrationCreate
      description: >-
        Schema for creating custom integrations.


        Inherits api_key field validation from CustomConfig:

        - api_key_header and api_key_value are required when authentication_type
        is api_key


        Token field is only used for oauth2 authentication (contains OAuth2
        client credentials).

        For api_key auth, the api_key_value field is used instead.
    IntegrationDB:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
        permissions:
          items:
            $ref: '#/components/schemas/Permission'
          type: array
          title: Permissions
          default: []
        name:
          $ref: '#/components/schemas/IntegrationName'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        created_by:
          type: string
          format: uuid4
          title: Created By
        is_selected:
          type: boolean
          title: Is Selected
          default: false
        is_disabled:
          type: boolean
          title: Is Disabled
          default: false
      type: object
      required:
        - id
        - name
        - created_at
        - updated_at
        - created_by
      title: IntegrationDB
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MultiModalModelIntegrationConfig:
      properties:
        max_files:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Files
          description: Maximum number of files allowed per request. None means no limit.
        max_file_size_bytes:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max File Size Bytes
          description: Maximum file size in bytes per file. None means no limit.
      type: object
      title: MultiModalModelIntegrationConfig
      description: Configuration for multi-modal capabilities (file uploads).
    CustomAuthenticationType:
      type: string
      enum:
        - api_key
        - none
        - oauth2
      title: CustomAuthenticationType
      description: |-
        Authentication types for custom integrations.

        Values:
        - none: No authentication required
        - oauth2: OAuth2 token-based authentication
        - api_key: API key header-based authentication
    ModelProperties:
      properties:
        name:
          type: string
          title: Name
          description: The model name used when calling the API.
        alias:
          anyOf:
            - type: string
            - type: 'null'
          title: Alias
          description: The display name/alias for the model. Defaults to name.
        based_on:
          anyOf:
            - type: string
            - type: 'null'
          title: Based On
          description: >-
            Alias of a built-in model whose parameter map should be used. For
            example, 'gpt-5.4'. Mutually exclusive with supported_parameters.
        supported_parameters:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Supported Parameters
          description: >-
            Explicit list of parameter names this model supports (e.g.,
            ['max_tokens', 'temperature', 'verbosity']). Each name must be a
            valid RunParamsMap field. Mutually exclusive with based_on.
      type: object
      required:
        - name
      title: ModelProperties
      description: |-
        Properties for a model in a custom integration.

        Attributes:
            name: The model name used when calling the API.
            alias: The display name/alias for the model in the UI.
                  Defaults to ``name`` when not provided.
            based_on: Alias of a built-in model whose parameter map should be used.
                      Mutually exclusive with ``supported_parameters``.
            supported_parameters: Explicit list of parameter names this model supports.
                                  Mutually exclusive with ``based_on``.
    CustomLLMConfig:
      properties:
        file_name:
          type: string
          title: File Name
          description: >-
            Python file name containing the CustomLLM class (e.g.,
            'my_handler.py')
        class_name:
          type: string
          title: Class Name
          description: Class name within the module (must be a litellm.CustomLLM subclass)
        init_kwargs:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Init Kwargs
          description: Optional keyword arguments to pass to the CustomLLM constructor
      type: object
      required:
        - file_name
        - class_name
      title: CustomLLMConfig
      description: >-
        Configuration for a custom LiteLLM handler class.


        Allows users to specify a custom implementation of litellm.CustomLLM

        that handles acompletion() calls with custom request/response
        transformation.
    Permission:
      properties:
        action:
          anyOf:
            - $ref: '#/components/schemas/UserAction'
            - $ref: '#/components/schemas/GroupAction'
            - $ref: '#/components/schemas/GroupMemberAction'
            - $ref: '#/components/schemas/ProjectAction'
            - $ref: '#/components/schemas/RegisteredScorerAction'
            - $ref: '#/components/schemas/ApiKeyAction'
            - $ref: '#/components/schemas/GeneratedScorerAction'
            - $ref: '#/components/schemas/FineTunedScorerAction'
            - $ref: '#/components/schemas/DatasetAction'
            - $ref: '#/components/schemas/IntegrationAction'
            - $ref: '#/components/schemas/OrganizationAction'
            - $ref: '#/components/schemas/AnnotationQueueAction'
          title: Action
        allowed:
          type: boolean
          title: Allowed
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
      type: object
      required:
        - action
        - allowed
      title: Permission
    IntegrationName:
      type: string
      enum:
        - anthropic
        - aws_bedrock
        - aws_sagemaker
        - azure
        - custom
        - databricks
        - mistral
        - nvidia
        - openai
        - vegas_gateway
        - vertex_ai
        - writer
      title: IntegrationName
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    UserAction:
      type: string
      enum:
        - update
        - delete
        - read_api_keys
        - change_role_to_admin
        - change_role_to_manager
        - change_role_to_user
        - change_role_to_read_only
      title: UserAction
    GroupAction:
      type: string
      enum:
        - update
        - list_members
        - join
        - request_to_join
      title: GroupAction
    GroupMemberAction:
      type: string
      enum:
        - update_role
        - delete
      title: GroupMemberAction
    ProjectAction:
      type: string
      enum:
        - update
        - delete
        - rename
        - share
        - create_run
        - delete_run
        - rename_run
        - move_run
        - export_data
        - configure_human_feedback
        - record_human_feedback
        - log_data
        - toggle_metric
        - edit_alert
        - create_stage
        - edit_stage
        - configure_crown_logic
        - delete_data
        - set_metric
        - edit_run_tags
        - dismiss_alert
        - edit_slice
        - edit_edit
      title: ProjectAction
    RegisteredScorerAction:
      type: string
      enum:
        - update
        - delete
      title: RegisteredScorerAction
    ApiKeyAction:
      type: string
      enum:
        - update
        - delete
      title: ApiKeyAction
    GeneratedScorerAction:
      type: string
      enum:
        - update
        - delete
      title: GeneratedScorerAction
    FineTunedScorerAction:
      type: string
      enum:
        - update
        - delete
      title: FineTunedScorerAction
    DatasetAction:
      type: string
      enum:
        - update
        - delete
        - share
        - export
        - rename
      title: DatasetAction
    IntegrationAction:
      type: string
      enum:
        - update
        - delete
        - share
      title: IntegrationAction
    OrganizationAction:
      type: string
      enum:
        - rename
        - delete
        - delete_log_data
        - read_settings
        - update_settings
      title: OrganizationAction
    AnnotationQueueAction:
      type: string
      enum:
        - update
        - delete
        - share
        - record_annotation
      title: AnnotationQueueAction
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Galileo-API-Key
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: https://api.galileo.ai/login
    HTTPBasic:
      type: http
      scheme: basic

````