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

# Create endpoint connection

> Create a new endpoint connection. See [Endpoint Connections](https://docs.galtea.ai/concepts/product/endpoint-connection).

> [!WARNING]
>
> You are reading the docs of Galtea 5.17. [Read this page in the latest version](https://docs.galtea.ai/api-reference/endpoint-connections/create-endpoint-connection.md).


## OpenAPI

````yaml /v5.17/openapi.json post /endpointConnections
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /endpointConnections:
    post:
      tags:
        - endpoint-connections
      summary: Create endpoint connection
      description: >-
        Create a new endpoint connection. See [Endpoint
        Connections](https://docs.galtea.ai/concepts/product/endpoint-connection).
      operationId: createEndpointConnection
      parameters:
        - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EndpointConnectionCreate'
      responses:
        '201':
          description: >-
            Endpoint connection created successfully. On `Prefer:
            return=minimal`, or when the read after the write fails, the answer
            has no body.
          headers:
            Location:
              schema:
                type: string
                description: The path of the new resource
              required: true
              description: The path of the new resource
            Content-Location:
              schema:
                type: string
                description: >-
                  The path of the resource in the body; absent when there is no
                  body
              required: false
              description: >-
                The path of the resource in the body; absent when there is no
                body
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=minimal
                description: 'Present when the API honored `Prefer: return=minimal`'
              required: false
              description: 'Present when the API honored `Prefer: return=minimal`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointConnection'
        '400':
          description: >-
            Invalid request: a missing or malformed field, a URL the deployment
            does not allow, a credential the auth type needs and the body lacks,
            or a name another connection of the product already uses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    Prefer:
      schema:
        $ref: '#/components/schemas/Prefer'
      required: false
      description: >-
        Send `return=minimal` to get no body back from a write and skip reading
        the resource: a create answers `201` with only `Location`, and an update
        answers `204`.
      name: Prefer
      in: header
  schemas:
    EndpointConnectionCreate:
      type: object
      properties:
        id:
          type: string
          example: ec_123
        userId:
          type: string
          nullable: true
          example: user_123
        hasAuthToken:
          type: boolean
          description: Whether an auth token is configured (token value is not exposed)
        hasPassword:
          type: boolean
          description: Whether a password is configured (password value is not exposed)
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        productId:
          type: string
          example: prod_123
        name:
          type: string
          example: My API Connection
        url:
          type: string
          example: https://api.example.com/v1/chat/completions
        httpMethod:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          example: POST
        authType:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
          example: BEARER
        username:
          type: string
          nullable: true
          description: Username for Basic auth
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >-
            Custom headers as key-value pairs. A secret value is encrypted at
            rest once its headers are saved, and every read returns it as
            "••••••••". A value is secret unless its name is Content-Type,
            Accept, Accept-Language, Accept-Encoding, Cache-Control, User-Agent,
            traceparent or tracestate, or it holds only placeholders (for
            example "Bearer {{ bearer_token }}"). On update, send "••••••••" to
            keep the stored value of that header name; any other value replaces
            it. Sending "••••••••" for a header with no stored value is a 400,
            which includes an update that moves `url` to another origin, because
            that update clears the stored secret values first, and so is a value
            in the stored ciphertext shape or with a character a header cannot
            carry. A create or update that sends headers holding `traceparent`
            is a 400, because Galtea sets it on every turn call; a stored one is
            dropped on send.
          example:
            Content-Type: application/json
        inputTemplate:
          type: string
          nullable: true
          description: >-
            Jinja2/Nunjucks template for request body. Must contain {{
            input.user_message }} placeholder.
          example: '{"prompt": "{{ input.user_message }}"}'
        inputSchema:
          type: object
          description: >-
            Optional JSON Schema (draft 2020-12) defining the structure of input
            fields, their types, and valid values. Must have type "object" with
            a "properties" key.
          example:
            type: object
            properties:
              user_message:
                type: string
                description: The main user message to the agent
              reasoning_level:
                type: string
                enum:
                  - low
                  - medium
                  - high
                description: How much reasoning the agent should apply
              topic:
                type: string
                enum:
                  - billing
                  - shipping
                  - returns
                  - account
                description: Conversation topic
              customer_id:
                type: string
                pattern: ^C-\d{3,6}$
                description: Customer identifier
            required:
              - user_message
          nullable: true
        outputMapping:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >-
            JSONPath expressions to extract values from API response. Filter and
            script expressions are refused. Must include "output" key. Special
            keys: "retrieval_context", "session_id" (initialization), "traces",
            and "output_files". "output_files" matches one file or a list of
            files the endpoint answers with, each a data: URI, an http(s) URL,
            the storage URI of a Galtea file, or an object with "base64", "url"
            or "uri" plus optional "mime_type" and "filename". Each file is
            stored as a Galtea file on the turn output: at most 20 files and 20
            MB per output, an accepted file type (the file extension decides
            it), and a URL is downloaded once without the connection headers or
            credentials, over plain http only when the connection acknowledged
            it. A Galtea file is linked rather than copied, and must be an
            uploaded file of the product organization. A file that cannot be
            stored fails the turn. A metric scores an output file only when its
            judge model reads that kind of file (PNG, JPEG, WebP, GIF or PDF);
            any other metric that reads the output is skipped, except a human
            evaluation or self-hosted one, and the reason names the file. Every
            other key is stored on the session metadata.
          example:
            output: $.choices[0].message.content
            output_files: $.files
        type:
          type: string
          enum:
            - INITIALIZATION
            - CONVERSATION
            - FINALIZATION
          example: CONVERSATION
        timeout:
          type: integer
          nullable: true
          default: 15
          minimum: 1
          maximum: 120
          example: 15
          description: >-
            Per-attempt request timeout in seconds. Unset applies the default
            (15). Capped server-side at 120 seconds.
        rateLimit:
          type: integer
          nullable: true
          minimum: 1
          example: 60
          description: Maximum requests per minute. Unset (null) means no rate limit.
        retryEnabled:
          type: boolean
          default: true
          description: Whether automatic retry is enabled for failed requests
        retryMaxAttempts:
          type: integer
          nullable: true
          default: 1
          minimum: 0
          maximum: 10
          description: >-
            Maximum number of retry attempts (applied when retryEnabled is
            true). 0 is only valid when retryEnabled is false; with retry
            enabled the minimum is 1.
        retryInitialDelayMs:
          type: integer
          nullable: true
          default: 1000
          minimum: 0
          description: Initial delay in milliseconds before first retry
        retryBackoffStrategy:
          type: string
          nullable: true
          enum:
            - FIXED
            - EXPONENTIAL
            - LINEAR
          default: EXPONENTIAL
          description: Strategy for increasing delay between retries
        retryMaxDelayMs:
          type: integer
          nullable: true
          default: 3000
          minimum: 0
          maximum: 60000
          description: >-
            Maximum delay between retry attempts, in milliseconds. Capped
            server-side at 60000 (60 seconds) to bound retry blast radius.
        retryableStatusCodes:
          type: array
          items:
            type: integer
            minimum: 100
            maximum: 599
          default:
            - 429
            - 500
            - 502
            - 503
            - 504
          description: HTTP status codes that should trigger a retry
        acknowledgedInsecureHttp:
          type: boolean
          default: false
          description: >-
            Required true to use an http:// URL. It records that the creator
            accepted that traffic to this endpoint is not encrypted, so anyone
            on the network path can read prompts, responses and credentials. The
            acceptance covers the connection, not one host: a redirect may send
            an acknowledged request to any public http:// host, carrying the
            connection credentials with it. Without it every hop the platform
            makes to the endpoint must stay on https. It is stored as false for
            an https:// URL, whatever the request sends.
        conversationEndRules:
          type: array
          nullable: true
          items:
            type: object
            properties:
              statusCode:
                type: integer
                minimum: 100
                maximum: 599
                description: >-
                  HTTP status code of the response. A 2xx status code needs a
                  bodyMatch.
                example: 409
              bodyMatch:
                type: object
                nullable: true
                properties:
                  path:
                    type: string
                    description: >-
                      JSONPath into the response body, starting with $.
                      Surrounding spaces are trimmed, and filter expressions are
                      refused. Only the first match is compared, and only a
                      string, number or boolean value.
                    example: $.error.code
                  equals:
                    type: string
                    description: >-
                      Expected value, compared as text (a number 409 matches
                      "409").
                    example: conversation_ended
                required:
                  - path
                  - equals
                description: >-
                  Optional check on the response body. A body that is not JSON,
                  or has no value at the path, does not match.
            required:
              - statusCode
          maxItems: 20
          default: []
          description: >-
            Responses that mean the agent closed the conversation on its own.
            Only a CONVERSATION connection accepts rules. A rule matches a
            response with its status code and, when bodyMatch is set, a response
            body whose first JSONPath match equals the expected value as text.
            The rules are checked before the retry policy, and a matching
            response is never retried, even when its status code is in
            retryableStatusCodes. A matching 2xx response with an agent output
            keeps its turn as the last one, on any turn and in a single-turn
            test. A matching response with no agent output (a non-2xx response,
            or a 2xx response with no output) removes the rejected turn on a
            later turn of a scenario test. In both cases the session completes
            with the turns so far and is evaluated, with the stopping reason
            "The agent ended the conversation (HTTP <code>)". A match with no
            agent output on the first turn, or on a single-turn test, still
            fails the session. An empty list keeps the default behaviour.
        authToken:
          type: string
          nullable: true
          description: >-
            Authentication token (for BEARER or API_KEY). Never returned: a read
            answers `hasAuthToken`. On update, a blank value (null or empty
            string) keeps the stored token.
        password:
          type: string
          nullable: true
          description: >-
            Password (for BASIC auth). Never returned: a read answers
            `hasPassword`. On update, a blank value (null or empty string) keeps
            the stored password.
      required:
        - productId
        - name
        - url
        - httpMethod
        - authType
        - inputTemplate
        - outputMapping
    EndpointConnection:
      type: object
      properties:
        id:
          type: string
          example: ec_123
        productId:
          type: string
          example: prod_123
        userId:
          type: string
          nullable: true
          example: user_123
        name:
          type: string
          example: My API Connection
        url:
          type: string
          example: https://api.example.com/v1/chat/completions
        httpMethod:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          example: POST
        authType:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
          example: BEARER
        hasAuthToken:
          type: boolean
          description: Whether an auth token is configured (token value is not exposed)
        username:
          type: string
          nullable: true
          description: Username for Basic auth
        hasPassword:
          type: boolean
          description: Whether a password is configured (password value is not exposed)
        headers:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >-
            Custom headers as key-value pairs. A secret value is encrypted at
            rest once its headers are saved, and every read returns it as
            "••••••••". A value is secret unless its name is Content-Type,
            Accept, Accept-Language, Accept-Encoding, Cache-Control, User-Agent,
            traceparent or tracestate, or it holds only placeholders (for
            example "Bearer {{ bearer_token }}"). On update, send "••••••••" to
            keep the stored value of that header name; any other value replaces
            it. Sending "••••••••" for a header with no stored value is a 400,
            which includes an update that moves `url` to another origin, because
            that update clears the stored secret values first, and so is a value
            in the stored ciphertext shape or with a character a header cannot
            carry. A create or update that sends headers holding `traceparent`
            is a 400, because Galtea sets it on every turn call; a stored one is
            dropped on send.
          example:
            Content-Type: application/json
        inputTemplate:
          type: string
          nullable: true
          description: >-
            Jinja2/Nunjucks template for request body. Must contain {{
            input.user_message }} placeholder.
          example: '{"prompt": "{{ input.user_message }}"}'
        inputSchema:
          type: object
          description: >-
            Optional JSON Schema (draft 2020-12) defining the structure of input
            fields, their types, and valid values. Must have type "object" with
            a "properties" key.
          example:
            type: object
            properties:
              user_message:
                type: string
                description: The main user message to the agent
              reasoning_level:
                type: string
                enum:
                  - low
                  - medium
                  - high
                description: How much reasoning the agent should apply
              topic:
                type: string
                enum:
                  - billing
                  - shipping
                  - returns
                  - account
                description: Conversation topic
              customer_id:
                type: string
                pattern: ^C-\d{3,6}$
                description: Customer identifier
            required:
              - user_message
          nullable: true
        outputMapping:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: >-
            JSONPath expressions to extract values from API response. Filter and
            script expressions are refused. Must include "output" key. Special
            keys: "retrieval_context", "session_id" (initialization), "traces",
            and "output_files". "output_files" matches one file or a list of
            files the endpoint answers with, each a data: URI, an http(s) URL,
            the storage URI of a Galtea file, or an object with "base64", "url"
            or "uri" plus optional "mime_type" and "filename". Each file is
            stored as a Galtea file on the turn output: at most 20 files and 20
            MB per output, an accepted file type (the file extension decides
            it), and a URL is downloaded once without the connection headers or
            credentials, over plain http only when the connection acknowledged
            it. A Galtea file is linked rather than copied, and must be an
            uploaded file of the product organization. A file that cannot be
            stored fails the turn. A metric scores an output file only when its
            judge model reads that kind of file (PNG, JPEG, WebP, GIF or PDF);
            any other metric that reads the output is skipped, except a human
            evaluation or self-hosted one, and the reason names the file. Every
            other key is stored on the session metadata.
          example:
            output: $.choices[0].message.content
            output_files: $.files
        type:
          type: string
          enum:
            - INITIALIZATION
            - CONVERSATION
            - FINALIZATION
          example: CONVERSATION
        timeout:
          type: integer
          nullable: true
          default: 15
          minimum: 1
          maximum: 120
          example: 15
          description: >-
            Per-attempt request timeout in seconds. Unset applies the default
            (15). Capped server-side at 120 seconds.
        rateLimit:
          type: integer
          nullable: true
          minimum: 1
          example: 60
          description: Maximum requests per minute. Unset (null) means no rate limit.
        retryEnabled:
          type: boolean
          default: true
          description: Whether automatic retry is enabled for failed requests
        retryMaxAttempts:
          type: integer
          nullable: true
          default: 1
          minimum: 0
          maximum: 10
          description: >-
            Maximum number of retry attempts (applied when retryEnabled is
            true). 0 is only valid when retryEnabled is false; with retry
            enabled the minimum is 1.
        retryInitialDelayMs:
          type: integer
          nullable: true
          default: 1000
          minimum: 0
          description: Initial delay in milliseconds before first retry
        retryBackoffStrategy:
          type: string
          nullable: true
          enum:
            - FIXED
            - EXPONENTIAL
            - LINEAR
          default: EXPONENTIAL
          description: Strategy for increasing delay between retries
        retryMaxDelayMs:
          type: integer
          nullable: true
          default: 3000
          minimum: 0
          maximum: 60000
          description: >-
            Maximum delay between retry attempts, in milliseconds. Capped
            server-side at 60000 (60 seconds) to bound retry blast radius.
        retryableStatusCodes:
          type: array
          items:
            type: integer
            minimum: 100
            maximum: 599
          default:
            - 429
            - 500
            - 502
            - 503
            - 504
          description: HTTP status codes that should trigger a retry
        acknowledgedInsecureHttp:
          type: boolean
          default: false
          description: >-
            Required true to use an http:// URL. It records that the creator
            accepted that traffic to this endpoint is not encrypted, so anyone
            on the network path can read prompts, responses and credentials. The
            acceptance covers the connection, not one host: a redirect may send
            an acknowledged request to any public http:// host, carrying the
            connection credentials with it. Without it every hop the platform
            makes to the endpoint must stay on https. It is stored as false for
            an https:// URL, whatever the request sends.
        conversationEndRules:
          type: array
          items:
            type: object
            properties:
              statusCode:
                type: integer
                minimum: 100
                maximum: 599
                description: >-
                  HTTP status code of the response. A 2xx status code needs a
                  bodyMatch.
                example: 409
              bodyMatch:
                type: object
                nullable: true
                properties:
                  path:
                    type: string
                    description: >-
                      JSONPath into the response body, starting with $.
                      Surrounding spaces are trimmed, and filter expressions are
                      refused. Only the first match is compared, and only a
                      string, number or boolean value.
                    example: $.error.code
                  equals:
                    type: string
                    description: >-
                      Expected value, compared as text (a number 409 matches
                      "409").
                    example: conversation_ended
                required:
                  - path
                  - equals
                description: >-
                  Optional check on the response body. A body that is not JSON,
                  or has no value at the path, does not match.
            required:
              - statusCode
          maxItems: 20
          default: []
          description: >-
            Responses that mean the agent closed the conversation on its own.
            Only a CONVERSATION connection accepts rules. A rule matches a
            response with its status code and, when bodyMatch is set, a response
            body whose first JSONPath match equals the expected value as text.
            The rules are checked before the retry policy, and a matching
            response is never retried, even when its status code is in
            retryableStatusCodes. A matching 2xx response with an agent output
            keeps its turn as the last one, on any turn and in a single-turn
            test. A matching response with no agent output (a non-2xx response,
            or a 2xx response with no output) removes the rejected turn on a
            later turn of a scenario test. In both cases the session completes
            with the turns so far and is evaluated, with the stopping reason
            "The agent ended the conversation (HTTP <code>)". A match with no
            agent output on the first turn, or on a single-turn test, still
            fails the session. An empty list keeps the default behaviour.
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
      required:
        - productId
        - name
        - url
        - httpMethod
        - authType
        - inputTemplate
        - outputMapping
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    Prefer:
      type: string
      description: >-
        Send `return=minimal` to get no body back from a write and skip reading
        the resource: a create answers `201` with only `Location`, and an update
        answers `204`.
      example: return=minimal
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authorization. Pass your API key in the Authorization header as
        a Bearer token. Both new (`gsk_*`) and legacy (`gsk-`) API keys are
        accepted, e.g. `Authorization: Bearer gsk_...` or `Authorization: Bearer
        gsk-...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.