--- title: "Create or update service definition" method: POST path: "/api/v2/services/definitions" tags: ["Service Definition"] --- # Create or update service definition `POST /api/v2/services/definitions` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/services/definitions` - Auth: one of: - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY` - OAuth 2 - Authorization code: `/oauth2/v1/authorize` - Token URL: `/oauth2/v1/token` scopes: `apm_service_catalog_write` Create or update service definition in the Datadog Service Catalog. ## Request body - union: Create service definitions request. - ServiceDefinitionV2Dot2: Service definition v2.2 for providing service metadata and integrations. - `application` string: Identifier for a group of related services serving a product feature, which the service is a part of. - `ci-pipeline-fingerprints` string[]: A set of CI fingerprints. - `contacts` ServiceDefinitionV2Dot2Contact[]: A list of contacts related to the services. - `contact` string, required: Contact value. - `name` string: Contact Name. - `type` string, required: Contact type. Datadog recognizes the following types: `email`, `slack`, and `microsoft-teams`. - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `description` string: A short description of the service. - `extensions` object: Extensions to v2.2 schema. - `integrations` ServiceDefinitionV2Dot2Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Dot2Opsgenie: Opsgenie integration for the service. - `region` 'US' | 'EU': Opsgenie instance region. - `service-url` string, required: Opsgenie service url. - `pagerduty` ServiceDefinitionV2Dot2Pagerduty: PagerDuty integration for the service. - `service-url` string: PagerDuty service url. - `languages` string[]: The service's programming language. Datadog recognizes the following languages: `dotnet`, `go`, `java`, `js`, `php`, `python`, `ruby`, and `c++`. - `lifecycle` string: The current life cycle phase of the service. - `links` ServiceDefinitionV2Dot2Link[]: A list of links related to the services. - `name` string, required: Link name. - `provider` string: Link provider. - `type` string, required: Link type. Datadog recognizes the following types: `runbook`, `doc`, `repo`, `dashboard`, and `other`. - `url` string, required: Link URL. - `schema-version` 'v2.2', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. - `tier` string: Importance of the service. - `type` string: The type of service. - ServiceDefinitionV2Dot1: Service definition v2.1 for providing service metadata and integrations. - `application` string: Identifier for a group of related services serving a product feature, which the service is a part of. - `contacts` ServiceDefinitionV2Dot1Contact[]: A list of contacts related to the services. - union: Service owner's contacts information. - ServiceDefinitionV2Dot1Email: Service owner's email. - `contact` string, required: Contact value. - `name` string: Contact email. - `type` 'email', required: Contact type. - ServiceDefinitionV2Dot1Slack: Service owner's Slack channel. - `contact` string, required: Slack Channel. - `name` string: Contact Slack. - `type` 'slack', required: Contact type. - ServiceDefinitionV2Dot1MSTeams: Service owner's Microsoft Teams. - `contact` string, required: Contact value. - `name` string: Contact Microsoft Teams. - `type` 'microsoft-teams', required: Contact type. - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `description` string: A short description of the service. - `extensions` object: Extensions to v2.1 schema. - `integrations` ServiceDefinitionV2Dot1Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Dot1Opsgenie: Opsgenie integration for the service. - `region` 'US' | 'EU': Opsgenie instance region. - `service-url` string, required: Opsgenie service url. - `pagerduty` ServiceDefinitionV2Dot1Pagerduty: PagerDuty integration for the service. - `service-url` string: PagerDuty service url. - `lifecycle` string: The current life cycle phase of the service. - `links` ServiceDefinitionV2Dot1Link[]: A list of links related to the services. - `name` string, required: Link name. - `provider` string: Link provider. - `type` 'doc' | 'repo' | 'runbook' | 'dashboard' | 'other', required: Link type. - `url` string, required: Link URL. - `schema-version` 'v2.1', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. - `tier` string: Importance of the service. - ServiceDefinitionV2: Service definition V2 for providing service metadata and integrations. - `contacts` ServiceDefinitionV2Contact[]: A list of contacts related to the services. - union: Service owner's contacts information. - ServiceDefinitionV2Email: Service owner's email. - `contact` string, required: Contact value. - `name` string: Contact email. - `type` 'email', required: Contact type. - ServiceDefinitionV2Slack: Service owner's Slack channel. - `contact` string, required: Slack Channel. - `name` string: Contact Slack. - `type` 'slack', required: Contact type. - ServiceDefinitionV2MSTeams: Service owner's Microsoft Teams. - `contact` string, required: Contact value. - `name` string: Contact Microsoft Teams. - `type` 'microsoft-teams', required: Contact type. - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `dd-team` string: Experimental feature. A Team handle that matches a Team in the Datadog Teams product. - `docs` ServiceDefinitionV2Doc[]: A list of documentation related to the services. - `name` string, required: Document name. - `provider` string: Document provider. - `url` string, required: Document URL. - `extensions` object: Extensions to V2 schema. - `integrations` ServiceDefinitionV2Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Opsgenie: Opsgenie integration for the service. - `region` 'US' | 'EU': Opsgenie instance region. - `service-url` string, required: Opsgenie service url. - `pagerduty` string: PagerDuty service URL for the service. - `links` ServiceDefinitionV2Link[]: A list of links related to the services. - `name` string, required: Link name. - `type` 'doc' | 'wiki' | 'runbook' | 'url' | 'repo' | 'dashboard' | 'oncall' | 'code' | 'link', required: Link type. - `url` string, required: Link URL. - `repos` ServiceDefinitionV2Repo[]: A list of code repositories related to the services. - `name` string, required: Repository name. - `provider` string: Repository provider. - `url` string, required: Repository URL. - `schema-version` 'v2', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. - string: Service Definition in raw JSON/YAML representation. ## Response `200` CREATED - ServiceDefinitionCreateResponse: Create service definitions response. - `data` ServiceDefinitionData[]: Create service definitions response payload. - `attributes` ServiceDefinitionDataAttributes: Service definition attributes. - `meta` ServiceDefinitionMeta: Metadata about a service definition. - `github-html-url` string: GitHub HTML URL. - `ingested-schema-version` string: Ingestion schema version. - `ingestion-source` string: Ingestion source of the service definition. - `last-modified-time` string: Last modified time of the service definition. - `origin` string: User defined origin of the service definition. - `origin-detail` string: User defined origin's detail of the service definition. - `warnings` ServiceDefinitionMetaWarnings[]: A list of schema validation warnings. - `instance-location` string: The warning instance location. - `keyword-location` string: The warning keyword location. - `message` string: The warning message. - `schema` union: Service definition schema. - ServiceDefinitionV1: Deprecated - Service definition V1 for providing additional service metadata and integrations. - `contact` ServiceDefinitionV1Contact: Contact information about the service. - `email` string: Service owner’s email. - `slack` string: Service owner’s Slack channel. - `extensions` object: Extensions to V1 schema. - `external-resources` ServiceDefinitionV1Resource[]: A list of external links related to the services. - `name` string, required: Link name. - `type` 'doc' | 'wiki' | 'runbook' | 'url' | 'repo' | 'dashboard' | 'oncall' | 'code' | 'link', required: Link type. - `url` string, required: Link URL. - `info` ServiceDefinitionV1Info, required: Basic information about a service. - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `description` string: A short description of the service. - `display-name` string: A friendly name of the service. - `service-tier` string: Service tier. - `integrations` ServiceDefinitionV1Integrations: Third party integrations that Datadog supports. - `pagerduty` string: PagerDuty service URL for the service. - `org` ServiceDefinitionV1Org: Org related information about the service. - `application` string: App feature this service supports. - `team` string: Team that owns the service. - `schema-version` 'v1', required: Schema version being used. - `tags` string[]: A set of custom tags. - ServiceDefinitionV2: Service definition V2 for providing service metadata and integrations. - `contacts` ServiceDefinitionV2Contact[]: A list of contacts related to the services. - union: Service owner's contacts information. - … - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `dd-team` string: Experimental feature. A Team handle that matches a Team in the Datadog Teams product. - `docs` ServiceDefinitionV2Doc[]: A list of documentation related to the services. - `name` string, required: Document name. - `provider` string: Document provider. - `url` string, required: Document URL. - `extensions` object: Extensions to V2 schema. - `integrations` ServiceDefinitionV2Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Opsgenie: Opsgenie integration for the service. - … - `pagerduty` string: PagerDuty service URL for the service. - `links` ServiceDefinitionV2Link[]: A list of links related to the services. - `name` string, required: Link name. - `type` 'doc' | 'wiki' | 'runbook' | 'url' | 'repo' | 'dashboard' | 'oncall' | 'code' | 'link', required: Link type. - `url` string, required: Link URL. - `repos` ServiceDefinitionV2Repo[]: A list of code repositories related to the services. - `name` string, required: Repository name. - `provider` string: Repository provider. - `url` string, required: Repository URL. - `schema-version` 'v2', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. - ServiceDefinitionV2Dot1: Service definition v2.1 for providing service metadata and integrations. - `application` string: Identifier for a group of related services serving a product feature, which the service is a part of. - `contacts` ServiceDefinitionV2Dot1Contact[]: A list of contacts related to the services. - union: Service owner's contacts information. - … - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `description` string: A short description of the service. - `extensions` object: Extensions to v2.1 schema. - `integrations` ServiceDefinitionV2Dot1Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Dot1Opsgenie: Opsgenie integration for the service. - … - `pagerduty` ServiceDefinitionV2Dot1Pagerduty: PagerDuty integration for the service. - … - `lifecycle` string: The current life cycle phase of the service. - `links` ServiceDefinitionV2Dot1Link[]: A list of links related to the services. - `name` string, required: Link name. - `provider` string: Link provider. - `type` 'doc' | 'repo' | 'runbook' | 'dashboard' | 'other', required: Link type. - `url` string, required: Link URL. - `schema-version` 'v2.1', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. - `tier` string: Importance of the service. - ServiceDefinitionV2Dot2: Service definition v2.2 for providing service metadata and integrations. - `application` string: Identifier for a group of related services serving a product feature, which the service is a part of. - `ci-pipeline-fingerprints` string[]: A set of CI fingerprints. - `contacts` ServiceDefinitionV2Dot2Contact[]: A list of contacts related to the services. - `contact` string, required: Contact value. - `name` string: Contact Name. - `type` string, required: Contact type. Datadog recognizes the following types: `email`, `slack`, and `microsoft-teams`. - `dd-service` string, required: Unique identifier of the service. Must be unique across all services and is used to match with a service in Datadog. - `description` string: A short description of the service. - `extensions` object: Extensions to v2.2 schema. - `integrations` ServiceDefinitionV2Dot2Integrations: Third party integrations that Datadog supports. - `opsgenie` ServiceDefinitionV2Dot2Opsgenie: Opsgenie integration for the service. - … - `pagerduty` ServiceDefinitionV2Dot2Pagerduty: PagerDuty integration for the service. - … - `languages` string[]: The service's programming language. Datadog recognizes the following languages: `dotnet`, `go`, `java`, `js`, `php`, `python`, `ruby`, and `c++`. - `lifecycle` string: The current life cycle phase of the service. - `links` ServiceDefinitionV2Dot2Link[]: A list of links related to the services. - `name` string, required: Link name. - `provider` string: Link provider. - `type` string, required: Link type. Datadog recognizes the following types: `runbook`, `doc`, `repo`, `dashboard`, and `other`. - `url` string, required: Link URL. - `schema-version` 'v2.2', required: Schema version being used. - `tags` string[]: A set of custom tags. - `team` string: Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. - `tier` string: Importance of the service. - `type` string: The type of service. - `id` string: Service definition id. - `type` string: Service definition type. ## Other responses - `400`: Bad Request - `403`: Forbidden - `409`: Conflict - `429`: Too many requests --- [API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)