---
title: "Upsert a service"
url: "https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd/operations/upsert-service"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-runtime-groups-configuration-0/versions/af18902c-58f1-49d7-8ec2-9987b4e0d1bd.md

# Upsert a service

`PUT` `/runtime-groups/{runtimeGroupId}/core-entities/services/{service_id}`

Operation ID: `upsert-service`

Create or Update service using ID or name.

## Path parameters

- `service_id` (string, required) - ID **or** name of the service to lookup
- `runtimeGroupId` (string, required) - The ID of your runtime group. This variable is available in the Konnect manager

## Request body

Content types: `application/json`

## Responses

- `200` - The service response object is returned when creating a new service or retreiving an existing service.
- `400` - Invalid service

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Konnect Runtime Groups Configuration
  version: 0.0.1
servers:
  - url: https://us.api.konghq.com/v2
    description: United-States Production region
  - url: https://eu.api.konghq.com/v2
    description: Europe Production region
  - url: https://au.api.konghq.com/v2
    description: Australia Production region
  - url: https://me.api.konghq.com/v2
    description: Middle-East Production region
  - url: https://in.api.konghq.com/v2
    description: India Production region
  - url: https://sg.api.konghq.com/v2
    description: Singapore Production region
paths:
  /runtime-groups/{runtimeGroupId}/core-entities/services/{service_id}:
    parameters:
      - $ref: "#/components/parameters/service_id"
      - $ref: "#/components/parameters/runtimeGroupId"
    put:
      operationId: upsert-service
      summary: Upsert a service
      description: Create or Update service using ID or name.
      requestBody:
        $ref: "#/components/requestBodies/service-request"
      responses:
        "200":
          $ref: "#/components/responses/service-response"
        "400":
          description: Invalid service
          content:
            application/json:
              schema:
                type: object
      tags:
        - Services
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    service_id:
      name: service_id
      description: ID **or** name of the service to lookup
      example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
      in: path
      required: true
      schema:
        type: string
    runtimeGroupId:
      name: runtimeGroupId
      in: path
      required: true
      schema:
        type: string
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The ID of your runtime group. This variable is available in the
        Konnect manager
  requestBodies:
    service-request:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                description: |
                  The service name.
                type: string
                example: my-service
              retries:
                description: >
                  The number of retries to execute upon failure to proxy.
                  Default:`5`.
                type: integer
                example: 5
                default: 5
              protocol:
                description: >-
                  The protocol used to communicate with the upstream. Accepted
                  values are: `grpc`, `grpcs`, `http`, `https`, `tcp`, `tls`,
                  `tls_passthrough`, `udp`, `ws`

                  , `wss`

                  . Default: `http`.
                type: string
                example: http
                default: http
                enum:
                  - grpc
                  - grpcs
                  - http
                  - https
                  - tcp
                  - "tls "
                  - tls_passthrough
                  - udp
                  - ws
                  - wss
              host:
                description: >
                  The host of the upstream server. Note that the host value is
                  case sensitive.
                type: string
                example: example.com
              port:
                description: |
                  The upstream server port. Default: `80`.
                type: integer
                example: 80
                default: 80
              path:
                description: |
                  The path to be used in requests to the upstream server.
                type: string
                example: /some_api
              connect_timeout:
                description: "The timeout in milliseconds for establishing a connection to the
                  upstream server. Default: `60000`."
                type: integer
                example: 6000
                default: 6000
              write_timeout:
                description: >
                  The timeout in milliseconds between two successive write
                  operations for transmitting a request to the upstream server.
                  Default: `60000`.
                type: integer
                example: 6000
                default: 6000
              read_timeout:
                description: >
                  The timeout in milliseconds between two successive read
                  operations for transmitting a request to the upstream server.
                  Default: `60000`.
                type: integer
                example: 6000
                default: 6000
              tags:
                description: >
                  An optional set of strings associated with the service for
                  grouping and filtering.
                type: array
                items:
                  type: string
                  example: user-level
              client_certificate:
                description: Certificate to be used as client certificate while TLS handshaking
                  to the upstream server. With form-encoded, the notation is
                  `client_certificate.id=<client_certificate id>`. With JSON,
                  use `client_certificate:{id:<client_certificate id>}`.
                type: object
                properties:
                  id:
                    type: string
                    example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
              tls_verify:
                description: >
                  Whether to enable verification of upstream server TLS
                  certificate. If set to null, then the Nginx default is
                  respected.
                type: boolean
                default: true
              tls_verify_depth:
                description: >
                  Maximum depth of chain while verifying Upstream server’s TLS
                  certificate. If set to null, then the Nginx default is
                  respected. Default: null.
                type: string
                example: respected
                default: null
                nullable: true
              ca_certificates:
                description: Array of CA Certificate object UUIDs that are used to build the
                  trust store while verifying upstream server’s TLS certificate.
                  If set to null when Nginx default is respected. With
                  form-encoded, the notation is
                  `ca_certificates[]=4e3ad2e4-0bc4-4638-8e34-c84a417ba39b&ca_certificates[]=51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515`.
                  With JSON, use an Array.
                type: array
                items:
                  type: string
                  example: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
              enabled:
                description: "Whether the service is active. If set to `false`, the proxy
                  behavior will be as if any routes attached to it do not exist
                  (404). Default: `true`."
                type: boolean
                default: true
            required:
              - protocol
              - host
              - port
              - enabled
            x-examples:
              Example 1:
                id: 9748f662-7711-4a90-8186-dc02f10eb0f5
                created_at: 1422386534
                updated_at: 1422386534
                name: my-service
                retries: 5
                protocol: http
                host: example.com
                port: 80
                path: /some_api
                connect_timeout: 60000
                write_timeout: 60000
                read_timeout: 60000
                tags:
                  - user-level
                  - low-priority
                client_certificate:
                  id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
                tls_verify: true
                tls_verify_depth: null
                ca_certificates:
                  - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
                  - 51e77dc2-8f3e-4afa-9d0e-0e3bbbcfd515
                enabled: true
          examples:
            Example:
              value:
                name: my-service
                retries: 5
                protocol: http
                host: example.com
                port: 80
                path: /some_api
                connect_timeout: 6000
                write_timeout: 6000
                read_timeout: 6000
                tags:
                  - user-level
                client_certificate:
                  id: 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
                tls_verify: true
                tls_verify_depth: null
                ca_certificates:
                  - 4e3ad2e4-0bc4-4638-8e34-c84a417ba39b
                enabled: true
            http service:
              value:
                name: my-service2
                retries: 5
                protocol: http
                host: example.com
                port: 80
                path: /some_api
                connect_timeout: 6000
                write_timeout: 6000
                read_timeout: 6000
                enabled: true
  responses:
    service-response:
      description: The service response object is returned when creating a new service
        or retreiving an existing service.
      content:
        application/json:
          schema:
            type: object
            properties:
              connect_timeout:
                type: integer
              created_at:
                description: Unix epoch when the resource was last created.
                type: integer
              enabled:
                description: Service enabled boolean
                type: boolean
              host:
                type: string
              id:
                type: string
              name:
                type: string
              path:
                type: string
              port:
                type: integer
              protocol:
                type: string
              read_timeout:
                type: integer
              retries:
                type: integer
              updated_at:
                type: integer
              write_timeout:
                type: integer
            x-examples:
              Example 1:
                connect_timeout: 6000
                created_at: 1684437851
                enabled: true
                host: example.com
                id: ebf4e826-b17a-4e23-9d58-2621c9faa135
                name: my-service
                path: /some_api
                port: 80
                protocol: http
                read_timeout: 6000
                retries: 5
                updated_at: 1684437851
                write_timeout: 6000
          examples:
            Returned Service:
              value:
                connect_timeout: 0
                created_at: 0
                enabled: true
                host: string
                id: string
                name: string
                path: string
                port: 0
                protocol: string
                read_timeout: 0
                retries: 0
                updated_at: 0
                write_timeout: 0
  securitySchemes:
    konnectAccessToken:
      type: http
      scheme: bearer
      description: >-
        The Konnect access token is meant to be used by the Konnect dashboard
        and the decK CLI to

        authenticate with.
    personalAccessToken:
      type: http
      scheme: bearer
      description: The personal access token is meant to be used as an alternative to
        basic-auth when accessing Konnect via APIs. You can generate a Personal
        Access Token (PAT) from the personal access token page in the Konnect
        dashboard.
```
