---
title: "Upsert a Service in a workspace"
url: "https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-dev-3/versions/76e259e8-9e78-4c0e-ab4a-3df25bddc4f1/operations/upsert-service-in-workspace"
---

> Full API specification: https://nov18-dev.movespot.fyi/apis/konnect-control-planes-configuration-dev-3/versions/76e259e8-9e78-4c0e-ab4a-3df25bddc4f1.md

# Upsert a Service in a workspace

`PUT` `/control-planes/{controlPlaneId}/core-entities/{workspace}/services/{ServiceId}`

Operation ID: `upsert-service-in-workspace`

Create or Update Service using ID or name in a workspace.

## Path parameters

- `ServiceId` (string, required) - ID of the Service to lookup
- `controlPlaneId` (string, uuid, required) - The UUID of your control plane. This variable is available in the Konnect manager.
- `workspace` (string, string, required) - The name of the workspace

## Request body (required)

Content types: `application/json`

## Responses

- `200` - Successfully upserted Service
- `401` - Unauthorized

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Konnect Control Planes Configuration
  version: 3.14.0
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:
  /control-planes/{controlPlaneId}/core-entities/{workspace}/services/{ServiceId}:
    parameters:
      - $ref: "#/components/parameters/ServiceId"
      - $ref: "#/components/parameters/controlPlaneId"
    put:
      operationId: upsert-service-in-workspace
      summary: Upsert a Service in a workspace
      description: Create or Update Service using ID or name in a workspace.
      parameters:
        - $ref: "#/components/parameters/Workspace"
      requestBody:
        description: Description of the Service
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Service"
      responses:
        "200":
          description: Successfully upserted Service
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Service"
        "401":
          $ref: "#/components/responses/HTTP401Error"
      tags:
        - Services
security:
  - konnectAccessToken: []
  - personalAccessToken: []
components:
  parameters:
    ServiceId:
      description: ID of the Service to lookup
      example: 7fca84d6-7d37-4a74-a7b0-93e576089a41
      in: path
      name: ServiceId
      required: true
      schema:
        type: string
    controlPlaneId:
      name: controlPlaneId
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9524ec7d-36d9-465d-a8c5-83a3c9390458
      description: The UUID of your control plane. This variable is available in the
        Konnect manager.
    Workspace:
      description: The name of the workspace
      in: path
      name: workspace
      required: true
      schema:
        type: string
        format: string
        example: team-payments
  schemas:
    Service:
      description: Service entities, as the name implies, are abstractions of each of
        your own upstream services. Examples of Services would be a data
        transformation microservice, a billing API, etc. The main attribute of a
        Service is its URL (where Kong should proxy traffic to), which can be
        set as a single string or by specifying its `protocol`, `host`, `port`
        and `path` individually. Services are associated to Routes (a Service
        can have many Routes associated with it). Routes are entry-points in
        Kong and define rules to match client requests. Once a Route is matched,
        Kong proxies the request to its associated Service. See the [Proxy
        Reference][proxy-reference] for a detailed explanation of how Kong
        proxies traffic.
      type: object
      properties:
        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. If default CA list in
            Nginx are not specified and TLS verification is enabled, then
            handshake with upstream server will always fail (because no CA are
            trusted).
          type: array
          items:
            type: string
          nullable: true
        client_certificate:
          description: Certificate to be used as client certificate while TLS handshaking
            to the upstream server.
          type: object
          nullable: true
          properties:
            id:
              type: string
          x-foreign: true
        connect_timeout:
          description: The timeout in milliseconds for establishing a connection to the
            upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        created_at:
          description: Unix epoch when the resource was created.
          type: integer
          nullable: true
        description:
          description: User-defined entity description. Konnect only field, not synced to
            the Gateway.
          type: string
          nullable: true
        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
          nullable: true
        host:
          description: The host of the upstream server. Note that the host value is case
            sensitive.
          type: string
        id:
          description: A string representing a UUID (universally unique identifier).
          type: string
          minLength: 1
          nullable: true
        managed_by:
          description: Arbitrary JSON data for client responsible for managing the entity.
            Konnect only field, not synced to the Gateway.
          type: object
          additionalProperties: true
          nullable: true
        name:
          description: The Service name.
          type: string
          nullable: true
        path:
          description: The path to be used in requests to the upstream server.
          type: string
          nullable: true
        port:
          description: The upstream server port.
          type: integer
          default: 80
          maximum: 65535
          minimum: 0
          nullable: true
          x-go-type: types.IntOrString
          x-go-type-import:
            path: github.com/kong/koko/internal/server/public/openapi/controlplanesconfig/types
            name: types
        protocol:
          description: The protocol used to communicate with the upstream.
          type: string
          default: http
          enum:
            - grpc
            - grpcs
            - http
            - https
            - tcp
            - tls
            - tls_passthrough
            - udp
            - ws
            - wss
          nullable: true
        read_timeout:
          description: The timeout in milliseconds between two successive read operations
            for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
        retries:
          description: The number of retries to execute upon failure to proxy.
          type: integer
          default: 5
          maximum: 32767
          minimum: 0
          nullable: true
        tags:
          description: An optional set of strings associated with the Service for grouping
            and filtering.
          type: array
          items:
            description: A string representing a tag.
            type: string
          nullable: true
        tls_sans:
          description: Additional Subject Alternative Names that can be matched on
            Upstream server's TLS certificate (in addition to `host`).
          type: object
          nullable: true
          properties:
            dnsnames:
              description: A dnsName for TLS verification.
              type: array
              items:
                description: A string representing an SNI (server name indication) value for
                  TLS.
                type: string
            uris:
              description: An URI for TLS verification.
              type: array
              items:
                description: A string representing a URL, such as
                  https://example.com/path/to/resource?q=search.
                type: string
        tls_verify:
          description: Whether to enable verification of upstream server TLS certificate.
            If set to `null`, then the Nginx default is respected.
          type: boolean
          nullable: 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.
          type: integer
          maximum: 64
          minimum: 0
          nullable: true
        updated_at:
          description: Unix epoch when the resource was last updated.
          type: integer
          nullable: true
        url:
          description: Helper field to set `protocol`, `host`, `port` and `path` using a
            URL. This field is write-only and is not returned in responses.
          type: string
          writeOnly: true
        write_timeout:
          description: The timeout in milliseconds between two successive write operations
            for transmitting a request to the upstream server.
          type: integer
          default: 60000
          maximum: 2147483646
          minimum: 1
          nullable: true
      example:
        host: example.internal
        id: 49fd316e-c457-481c-9fc7-8079153e4f3c
        name: example-service
        path: /
        port: 80
        protocol: http
      additionalProperties: false
      required:
        - host
    GatewayUnauthorizedError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
      required:
        - message
        - status
  responses:
    HTTP401Error:
      description: Unauthorized
      content:
        application/json:
          examples:
            DuplicateApiKey:
              summary: Duplicate API key found
              value:
                message: Duplicate API key found
                status: 401
            InvalidAuthCred:
              summary: Invalid authentication credentials
              value:
                message: Unauthorized
                status: 401
            NoAPIKey:
              summary: No API key found
              value:
                message: No API key found in request
                status: 401
          schema:
            $ref: "#/components/schemas/GatewayUnauthorizedError"
  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.
```
