---
title: "Register the given service in the organization. Services in the registry are deduplicated so that the same service running in different clusters are represented as a single entity in the registry. The service returned by this method is the result of deduplicating the service. This API is currently only intended for internal use by the discovery agents. $hide_from_docs"
method: POST
path: "/v2/organizations/{organization}/services"
tags: ["Registration"]
---

# Register the given service in the organization. Services in the registry are deduplicated so that the same service running in different clusters are represented as a single entity in the registry. The service returned by this method is the result of deduplicating the service. This API is currently only intended for internal use by the discovery agents. $hide_from_docs

`POST /v2/organizations/{organization}/services`

## Request

- Base URL: `https://docs.tetrate.io` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.tetrate.io/v2/organizations/{organization}/services`
- Auth: none declared
- TypeScript: <https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api/docs/v2/organizations/:organization/services/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `organization` string, required

## Request body

- object: Request to register a service in a given parent (organization).
  - `canonicalName` string: optional canonical name that identify this service.
  - `cluster` string, required: Name of the cluster where the service belongs to. This will be used to load the deduplication settings that have been configured for the cluster where the service belongs.
  - `externalAddresses` string[]: For kubernetes services of type load balancer, this field contains the list of lb hostnames or IPs assigned to the service.
  - `hostnames` string[]: The hostnames by which this service is accessed. Can correspond to the hostname of an internal service or that ones of a virtual host on a gateway.
  - `namespace` string, required: Namespace associated with the service. It will be used in deduplication logic.
  - `ports` V2Port[]: The set of ports on which this service is exposed.
    - `number` integer, required: A valid non-negative integer port number.
    - `name` string: Name assigned to the port.
    - `serviceDeployments` string[]
  - `serviceType` 'INVALID_TYPE' | 'INTERNAL' | 'LOADBALANCER' | 'MESH_EXTERNAL', required: ServiceType denotes the exposition of a service in the mesh. - INTERNAL: A regular service that is not directly exposed to the outside world. - LOADBALANCER: A load balancer service running only the proxy as the workload. - MESH_EXTERNAL: A mesh external service.
  - `shortName` string, required: Short name for the service, used to uniquely identify it within the organization.
  - `source` string, required: Source of the service: Kubernetes, Istio, Consul, etc.
  - `spiffeIds` string[]: List of SPIFFE identities used by the workloads of the service.
  - `state` 'INVALID_STATE' | 'EXTERNAL' | 'OBSERVED' | 'CONTROLLED', required: State denotes how deep is the knowledge of a service by the mesh. Meaning that if a service can be controlled, observed or none of these. - EXTERNAL: An external service is a service that is known, but that cannot be observed (we can't get metrics for it) and cannot be controlled. - OBSERVED: An observed service is a known service that we can have metrics for. For example, a service running the Skywalking agents. - CONTROLLED: A controlled service is a service that is part of the mesh and has a proxy we can configure.
  - `subsets` string[]: Subset denotes a specific version of a service. By default the 'version' label is used to designate subsets of a workload. Known subsets for the service.

## Response `200`

A successful response.

- V2Service: A service in the registry that represents an aggregated and logical view for all those individual services, and provides high-level features such as aggregated metrics.
  - `fqn` string: Fully-qualified name of the resource. This field is read-only.
  - `displayName` string: User friendly name for the resource.
  - `etag` string: The etag for the resource. This field is automatically computed and must be sent on every update to the resource to prevent concurrent modifications.
  - `description` string: A description of the resource.
  - `shortName` string, required: Short name for the service, used to uniquely identify it within the organization.
  - `hostnames` string[]: The hostnames by which this service is accessed. Can correspond to the hostname of an internal service or that ones of a virtual host on a gateway.
  - `ports` V2Port[]: The set of ports on which this service is exposed.
    - `number` integer, required: A valid non-negative integer port number.
    - `name` string: Name assigned to the port.
    - `serviceDeployments` string[]
  - `subsets` string[]: Deprecated. Use subset_deployments instead. Subset denotes a specific version of a service. By default the 'version' label is used to designate subsets of a workload. Known subsets for the service.
  - `serviceType` 'INVALID_TYPE' | 'INTERNAL' | 'LOADBALANCER' | 'MESH_EXTERNAL', required: ServiceType denotes the exposition of a service in the mesh. - INTERNAL: A regular service that is not directly exposed to the outside world. - LOADBALANCER: A load balancer service running only the proxy as the workload. - MESH_EXTERNAL: A mesh external service.
  - `externalAddresses` string[]: For kubernetes services of type load balancer, this field contains the list of lb hostnames or IPs assigned to the service.
  - `state` 'INVALID_STATE' | 'EXTERNAL' | 'OBSERVED' | 'CONTROLLED', required: State denotes how deep is the knowledge of a service by the mesh. Meaning that if a service can be controlled, observed or none of these. - EXTERNAL: An external service is a service that is known, but that cannot be observed (we can't get metrics for it) and cannot be controlled. - OBSERVED: An observed service is a known service that we can have metrics for. For example, a service running the Skywalking agents. - CONTROLLED: A controlled service is a service that is part of the mesh and has a proxy we can configure.
  - `metrics` ServiceMetricConfig[]: - global: *|productpage|bookinfo|*|* - v1: v1|productpage|bookinfo|*|* - v1 (cluster1): v1|productpage|bookinfo|cluster1|* This is only available for Observed and Controlled services.
    - `name` string: A user friendly name for this metric.
    - `description` string: A helpful description of what this metric represents.
    - `aggregationKey` string: An aggregation key that can be queried to get metrics for this service.
    - `type` 'INVALID' | 'SINGLE_INSTANCE' | 'SUBSET' | 'GLOBAL' | 'ENDPOINT' | 'ENDPOINT_INSTANCE': MetricType denotes the relation of a metrics with a physical service instance. - SINGLE_INSTANCE: A single instance metric config belongs to an specific physical service instance. - SUBSET: A subset metric config represents subsets across clusters or hostnames across clusters. - GLOBAL: A global metric config represents all the physical services. - ENDPOINT: An endpoint metric config represents an endpoint across clusters. - ENDPOINT_INSTANCE: An endpoint instance metric config represents an endpoint in a specific cluster.
    - `serviceDeployment` string: The FQN of the service deployment related with this metric. Will be empty for group metrics.
    - `parentMetric` string
  - `serviceDeployments` ServiceServiceDeployment[]: List of the existing deployments for this service. This is only available for internal and load balancer services and correspond to physical services in the onboarded clusters. This field is read-only.
    - `fqn` string: Fully-qualified name of the instance. This field is read-only.
    - `source` string: Source of the instance. This field is read-only.
  - `subsetDeployments` V2Subset[]: Subset denotes a specific version of a service. By default the 'version' label is used to designate subsets of a workload. Known subsets for the service.
    - `name` string: A valid subset name of a service.
    - `serviceDeployments` string[]
  - `canonicalName` string
  - `spiffeIds` string[]: List of SPIFFE identities used by the workloads of the service.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api.md) - [All operations](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tetrate/apis/tetrate-service-bridge-api/revisions/2f19c3a1ae57?raw)