Service Definition

API to create, update, retrieve and delete service definitions. Note: Service Catalog v3.0 schema has new API endpoints documented under Software Catalog. Use the following Service Definition endpoints for v2.2 and earlier.

GET https://api.ap1.datadoghq.com/api/v2/services/definitionshttps://api.datadoghq.eu/api/v2/services/definitionshttps://api.ddog-gov.com/api/v2/services/definitionshttps://api.datadoghq.com/api/v2/services/definitionshttps://api.us3.datadoghq.com/api/v2/services/definitionshttps://api.us5.datadoghq.com/api/v2/services/definitions

Overview

Get a list of all service definitions from the Datadog Service Catalog. This endpoint requires the apm_service_catalog_read permission.

OAuth apps require the apm_service_catalog_read authorization scope to access this endpoint.

Arguments

Query Strings

Name

Type

Description

page[size]

integer

Size for a given page. The maximum allowed value is 100.

page[number]

integer

Specific page number to return.

schema_version

enum

The schema version desired in the response.
Allowed enum values: v1, v2, v2.1, v2.2

Response

OK

Create service definitions response.

Expand All

Field

Type

Description

data

[object]

Data representing service definitions.

attributes

object

Service definition attributes.

meta

object

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

[object]

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

 <oneOf>

Service definition schema.

Option 1

object

DEPRECATED: Deprecated - Service definition V1 for providing additional service metadata and integrations.

contact

object

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

[object]

A list of external links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

info [required]

object

Basic information about a service.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

pagerduty

string

PagerDuty service URL for the service.

org

object

Org related information about the service.

application

string

App feature this service supports.

team

string

Team that owns the service.

schema-version [required]

enum

Schema version being used. Allowed enum values: v1

default: v1

tags

[string]

A set of custom tags.

Option 2

object

Service definition V2 for providing service metadata and integrations.

contacts

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

[object]

A list of documentation related to the services.

name [required]

string

Document name.

provider

string

Document provider.

url [required]

string

Document URL.

extensions

object

Extensions to V2 schema.

integrations

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

string

PagerDuty service URL for the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

repos

[object]

A list of code repositories related to the services.

name [required]

string

Repository name.

provider

string

Repository provider.

url [required]

string

Repository URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2

default: v2

tags

[string]

A set of custom tags.

team

string

Team that owns the service.

Option 3

object

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

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

PagerDuty integration for the service.

service-url

string

PagerDuty service url.

lifecycle

string

The current life cycle phase of the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

enum

Link type. Allowed enum values: doc,repo,runbook,dashboard,other

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.1

default: v2.1

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.

Option 4

object

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

[object]

A list of contacts related to the services.

contact [required]

string

Contact value.

name

string

Contact Name.

type [required]

string

Contact type. Datadog recognizes the following types: email, slack, and microsoft-teams.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

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

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

string

Link type. Datadog recognizes the following types: runbook, doc, repo, dashboard, and other.

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.2

default: v2.2

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

enum

The type of service. Allowed enum values: web,db,cache,function,browser,mobile,custom

id

string

Service definition id.

type

string

Service definition type.

{
  "data": [
    {
      "attributes": {
        "meta": {
          "github-html-url": "string",
          "ingested-schema-version": "string",
          "ingestion-source": "string",
          "last-modified-time": "string",
          "origin": "string",
          "origin-detail": "string",
          "warnings": [
            {
              "instance-location": "string",
              "keyword-location": "string",
              "message": "string"
            }
          ]
        },
        "schema": {
          "contact": {
            "email": "contact@datadoghq.com",
            "slack": "https://yourcompany.slack.com/archives/channel123"
          },
          "extensions": {
            "myorg/extension": "extensionValue"
          },
          "external-resources": [
            {
              "name": "Runbook",
              "type": "runbook",
              "url": "https://my-runbook"
            }
          ],
          "info": {
            "dd-service": "myservice",
            "description": "A shopping cart service",
            "display-name": "My Service",
            "service-tier": "Tier 1"
          },
          "integrations": {
            "pagerduty": "https://my-org.pagerduty.com/service-directory/PMyService"
          },
          "org": {
            "application": "E-Commerce",
            "team": "my-team"
          },
          "schema-version": "v1",
          "tags": [
            "my:tag",
            "service:tag"
          ]
        }
      },
      "id": "string",
      "type": "string"
    }
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

POST https://api.ap1.datadoghq.com/api/v2/services/definitionshttps://api.datadoghq.eu/api/v2/services/definitionshttps://api.ddog-gov.com/api/v2/services/definitionshttps://api.datadoghq.com/api/v2/services/definitionshttps://api.us3.datadoghq.com/api/v2/services/definitionshttps://api.us5.datadoghq.com/api/v2/services/definitions

Overview

Create or update service definition in the Datadog Service Catalog. This endpoint requires the apm_service_catalog_write permission.

OAuth apps require the apm_service_catalog_write authorization scope to access this endpoint.

Request

Body Data (required)

Service Definition YAML/JSON.

Expand All

Field

Type

Description

Option 1

object

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

[object]

A list of contacts related to the services.

contact [required]

string

Contact value.

name

string

Contact Name.

type [required]

string

Contact type. Datadog recognizes the following types: email, slack, and microsoft-teams.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

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

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

string

Link type. Datadog recognizes the following types: runbook, doc, repo, dashboard, and other.

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.2

default: v2.2

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

enum

The type of service. Allowed enum values: web,db,cache,function,browser,mobile,custom

Option 2

object

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

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

PagerDuty integration for the service.

service-url

string

PagerDuty service url.

lifecycle

string

The current life cycle phase of the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

enum

Link type. Allowed enum values: doc,repo,runbook,dashboard,other

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.1

default: v2.1

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.

Option 3

object

Service definition V2 for providing service metadata and integrations.

contacts

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

[object]

A list of documentation related to the services.

name [required]

string

Document name.

provider

string

Document provider.

url [required]

string

Document URL.

extensions

object

Extensions to V2 schema.

integrations

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

string

PagerDuty service URL for the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

repos

[object]

A list of code repositories related to the services.

name [required]

string

Repository name.

provider

string

Repository provider.

url [required]

string

Repository URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2

default: v2

tags

[string]

A set of custom tags.

team

string

Team that owns the service.

Option 4

string

Service Definition in raw JSON/YAML representation.

{
  "contacts": [
    {
      "contact": "contact@datadoghq.com",
      "name": "Team Email",
      "type": "email"
    }
  ],
  "dd-service": "service-exampleservicedefinition",
  "dd-team": "my-team",
  "docs": [
    {
      "name": "Architecture",
      "provider": "google drive",
      "url": "https://gdrive/mydoc"
    }
  ],
  "extensions": {
    "myorgextension": "extensionvalue"
  },
  "integrations": {
    "opsgenie": {
      "region": "US",
      "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000"
    },
    "pagerduty": "https://my-org.pagerduty.com/service-directory/PMyService"
  },
  "links": [
    {
      "name": "Runbook",
      "type": "runbook",
      "url": "https://my-runbook"
    }
  ],
  "repos": [
    {
      "name": "Source Code",
      "provider": "GitHub",
      "url": "https://github.com/DataDog/schema"
    }
  ],
  "schema-version": "v2",
  "tags": [
    "my:tag",
    "service:tag"
  ],
  "team": "my-team"
}
{
  "contacts": [
    {
      "contact": "contact@datadoghq.com",
      "name": "Team Email",
      "type": "email"
    }
  ],
  "dd-service": "service-exampleservicedefinition",
  "extensions": {
    "myorgextension": "extensionvalue"
  },
  "integrations": {
    "opsgenie": {
      "region": "US",
      "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000"
    },
    "pagerduty": {
      "service-url": "https://my-org.pagerduty.com/service-directory/PMyService"
    }
  },
  "links": [
    {
      "name": "Runbook",
      "type": "runbook",
      "url": "https://my-runbook"
    },
    {
      "name": "Source Code",
      "type": "repo",
      "provider": "GitHub",
      "url": "https://github.com/DataDog/schema"
    },
    {
      "name": "Architecture",
      "type": "doc",
      "provider": "Gigoogle drivetHub",
      "url": "https://my-runbook"
    }
  ],
  "schema-version": "v2.1",
  "tags": [
    "my:tag",
    "service:tag"
  ],
  "team": "my-team"
}
{
  "contacts": [
    {
      "contact": "contact@datadoghq.com",
      "name": "Team Email",
      "type": "email"
    }
  ],
  "dd-service": "service-exampleservicedefinition",
  "extensions": {
    "myorgextension": "extensionvalue"
  },
  "integrations": {
    "opsgenie": {
      "region": "US",
      "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000"
    },
    "pagerduty": {
      "service-url": "https://my-org.pagerduty.com/service-directory/PMyService"
    }
  },
  "links": [
    {
      "name": "Runbook",
      "type": "runbook",
      "url": "https://my-runbook"
    },
    {
      "name": "Source Code",
      "type": "repo",
      "provider": "GitHub",
      "url": "https://github.com/DataDog/schema"
    },
    {
      "name": "Architecture",
      "type": "doc",
      "provider": "Gigoogle drivetHub",
      "url": "https://my-runbook"
    }
  ],
  "schema-version": "v2.2",
  "tags": [
    "my:tag",
    "service:tag"
  ],
  "team": "my-team"
}

Response

CREATED

Create service definitions response.

Expand All

Field

Type

Description

data

[object]

Create service definitions response payload.

attributes

object

Service definition attributes.

meta

object

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

[object]

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

 <oneOf>

Service definition schema.

Option 1

object

DEPRECATED: Deprecated - Service definition V1 for providing additional service metadata and integrations.

contact

object

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

[object]

A list of external links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

info [required]

object

Basic information about a service.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

pagerduty

string

PagerDuty service URL for the service.

org

object

Org related information about the service.

application

string

App feature this service supports.

team

string

Team that owns the service.

schema-version [required]

enum

Schema version being used. Allowed enum values: v1

default: v1

tags

[string]

A set of custom tags.

Option 2

object

Service definition V2 for providing service metadata and integrations.

contacts

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

[object]

A list of documentation related to the services.

name [required]

string

Document name.

provider

string

Document provider.

url [required]

string

Document URL.

extensions

object

Extensions to V2 schema.

integrations

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

string

PagerDuty service URL for the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

repos

[object]

A list of code repositories related to the services.

name [required]

string

Repository name.

provider

string

Repository provider.

url [required]

string

Repository URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2

default: v2

tags

[string]

A set of custom tags.

team

string

Team that owns the service.

Option 3

object

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

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

PagerDuty integration for the service.

service-url

string

PagerDuty service url.

lifecycle

string

The current life cycle phase of the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

enum

Link type. Allowed enum values: doc,repo,runbook,dashboard,other

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.1

default: v2.1

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.

Option 4

object

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

[object]

A list of contacts related to the services.

contact [required]

string

Contact value.

name

string

Contact Name.

type [required]

string

Contact type. Datadog recognizes the following types: email, slack, and microsoft-teams.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

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

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

string

Link type. Datadog recognizes the following types: runbook, doc, repo, dashboard, and other.

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.2

default: v2.2

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

enum

The type of service. Allowed enum values: web,db,cache,function,browser,mobile,custom

id

string

Service definition id.

type

string

Service definition type.

{
  "data": [
    {
      "attributes": {
        "meta": {
          "github-html-url": "string",
          "ingested-schema-version": "string",
          "ingestion-source": "string",
          "last-modified-time": "string",
          "origin": "string",
          "origin-detail": "string",
          "warnings": [
            {
              "instance-location": "string",
              "keyword-location": "string",
              "message": "string"
            }
          ]
        },
        "schema": {
          "contact": {
            "email": "contact@datadoghq.com",
            "slack": "https://yourcompany.slack.com/archives/channel123"
          },
          "extensions": {
            "myorg/extension": "extensionValue"
          },
          "external-resources": [
            {
              "name": "Runbook",
              "type": "runbook",
              "url": "https://my-runbook"
            }
          ],
          "info": {
            "dd-service": "myservice",
            "description": "A shopping cart service",
            "display-name": "My Service",
            "service-tier": "Tier 1"
          },
          "integrations": {
            "pagerduty": "https://my-org.pagerduty.com/service-directory/PMyService"
          },
          "org": {
            "application": "E-Commerce",
            "team": "my-team"
          },
          "schema-version": "v1",
          "tags": [
            "my:tag",
            "service:tag"
          ]
        }
      },
      "id": "string",
      "type": "string"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "contacts": [ { "contact": "contact@datadoghq.com", "name": "Team Email", "type": "email" } ], "dd-service": "service-exampleservicedefinition", "dd-team": "my-team", "docs": [ { "name": "Architecture", "provider": "google drive", "url": "https://gdrive/mydoc" } ], "extensions": { "myorgextension": "extensionvalue" }, "integrations": { "opsgenie": { "region": "US", "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000" }, "pagerduty": "https://my-org.pagerduty.com/service-directory/PMyService" }, "links": [ { "name": "Runbook", "type": "runbook", "url": "https://my-runbook" } ], "repos": [ { "name": "Source Code", "provider": "GitHub", "url": "https://github.com/DataDog/schema" } ], "schema-version": "v2", "tags": [ "my:tag", "service:tag" ], "team": "my-team" } EOF
                          # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "contacts": [ { "contact": "contact@datadoghq.com", "name": "Team Email", "type": "email" } ], "dd-service": "service-exampleservicedefinition", "extensions": { "myorgextension": "extensionvalue" }, "integrations": { "opsgenie": { "region": "US", "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000" }, "pagerduty": { "service-url": "https://my-org.pagerduty.com/service-directory/PMyService" } }, "links": [ { "name": "Runbook", "type": "runbook", "url": "https://my-runbook" }, { "name": "Source Code", "type": "repo", "provider": "GitHub", "url": "https://github.com/DataDog/schema" }, { "name": "Architecture", "type": "doc", "provider": "Gigoogle drivetHub", "url": "https://my-runbook" } ], "schema-version": "v2.1", "tags": [ "my:tag", "service:tag" ], "team": "my-team" } EOF
                          # Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "contacts": [ { "contact": "contact@datadoghq.com", "name": "Team Email", "type": "email" } ], "dd-service": "service-exampleservicedefinition", "extensions": { "myorgextension": "extensionvalue" }, "integrations": { "opsgenie": { "region": "US", "service-url": "https://my-org.opsgenie.com/service/123e4567-e89b-12d3-a456-426614174000" }, "pagerduty": { "service-url": "https://my-org.pagerduty.com/service-directory/PMyService" } }, "links": [ { "name": "Runbook", "type": "runbook", "url": "https://my-runbook" }, { "name": "Source Code", "type": "repo", "provider": "GitHub", "url": "https://github.com/DataDog/schema" }, { "name": "Architecture", "type": "doc", "provider": "Gigoogle drivetHub", "url": "https://my-runbook" } ], "schema-version": "v2.2", "tags": [ "my:tag", "service:tag" ], "team": "my-team" } EOF

GET https://api.ap1.datadoghq.com/api/v2/services/definitions/{service_name}https://api.datadoghq.eu/api/v2/services/definitions/{service_name}https://api.ddog-gov.com/api/v2/services/definitions/{service_name}https://api.datadoghq.com/api/v2/services/definitions/{service_name}https://api.us3.datadoghq.com/api/v2/services/definitions/{service_name}https://api.us5.datadoghq.com/api/v2/services/definitions/{service_name}

Overview

Get a single service definition from the Datadog Service Catalog. This endpoint requires the apm_service_catalog_read permission.

OAuth apps require the apm_service_catalog_read authorization scope to access this endpoint.

Arguments

Path Parameters

Name

Type

Description

service_name [required]

string

The name of the service.

Query Strings

Name

Type

Description

schema_version

enum

The schema version desired in the response.
Allowed enum values: v1, v2, v2.1, v2.2

Response

OK

Get service definition response.

Expand All

Field

Type

Description

data

object

Service definition data.

attributes

object

Service definition attributes.

meta

object

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

[object]

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

 <oneOf>

Service definition schema.

Option 1

object

DEPRECATED: Deprecated - Service definition V1 for providing additional service metadata and integrations.

contact

object

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

[object]

A list of external links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

info [required]

object

Basic information about a service.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

pagerduty

string

PagerDuty service URL for the service.

org

object

Org related information about the service.

application

string

App feature this service supports.

team

string

Team that owns the service.

schema-version [required]

enum

Schema version being used. Allowed enum values: v1

default: v1

tags

[string]

A set of custom tags.

Option 2

object

Service definition V2 for providing service metadata and integrations.

contacts

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

[object]

A list of documentation related to the services.

name [required]

string

Document name.

provider

string

Document provider.

url [required]

string

Document URL.

extensions

object

Extensions to V2 schema.

integrations

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

string

PagerDuty service URL for the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

type [required]

enum

Link type. Allowed enum values: doc,wiki,runbook,url,repo,dashboard,oncall,code,link

url [required]

string

Link URL.

repos

[object]

A list of code repositories related to the services.

name [required]

string

Repository name.

provider

string

Repository provider.

url [required]

string

Repository URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2

default: v2

tags

[string]

A set of custom tags.

team

string

Team that owns the service.

Option 3

object

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

[ <oneOf>]

A list of contacts related to the services.

Option 1

object

Service owner's email.

contact [required]

string

Contact value.

name

string

Contact email.

type [required]

enum

Contact type. Allowed enum values: email

Option 2

object

Service owner's Slack channel.

contact [required]

string

Slack Channel.

name

string

Contact Slack.

type [required]

enum

Contact type. Allowed enum values: slack

Option 3

object

Service owner's Microsoft Teams.

contact [required]

string

Contact value.

name

string

Contact Microsoft Teams.

type [required]

enum

Contact type. Allowed enum values: microsoft-teams

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

PagerDuty integration for the service.

service-url

string

PagerDuty service url.

lifecycle

string

The current life cycle phase of the service.

links

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

enum

Link type. Allowed enum values: doc,repo,runbook,dashboard,other

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.1

default: v2.1

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.

Option 4

object

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

[object]

A list of contacts related to the services.

contact [required]

string

Contact value.

name

string

Contact Name.

type [required]

string

Contact type. Datadog recognizes the following types: email, slack, and microsoft-teams.

dd-service [required]

string

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

object

Third party integrations that Datadog supports.

opsgenie

object

Opsgenie integration for the service.

region

enum

Opsgenie instance region. Allowed enum values: US,EU

service-url [required]

string

Opsgenie service url.

pagerduty

object

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

[object]

A list of links related to the services.

name [required]

string

Link name.

provider

string

Link provider.

type [required]

string

Link type. Datadog recognizes the following types: runbook, doc, repo, dashboard, and other.

url [required]

string

Link URL.

schema-version [required]

enum

Schema version being used. Allowed enum values: v2.2

default: v2.2

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

enum

The type of service. Allowed enum values: web,db,cache,function,browser,mobile,custom

id

string

Service definition id.

type

string

Service definition type.

{
  "data": {
    "attributes": {
      "meta": {
        "github-html-url": "string",
        "ingested-schema-version": "string",
        "ingestion-source": "string",
        "last-modified-time": "string",
        "origin": "string",
        "origin-detail": "string",
        "warnings": [
          {
            "instance-location": "string",
            "keyword-location": "string",
            "message": "string"
          }
        ]
      },
      "schema": {
        "contact": {
          "email": "contact@datadoghq.com",
          "slack": "https://yourcompany.slack.com/archives/channel123"
        },
        "extensions": {
          "myorg/extension": "extensionValue"
        },
        "external-resources": [
          {
            "name": "Runbook",
            "type": "runbook",
            "url": "https://my-runbook"
          }
        ],
        "info": {
          "dd-service": "myservice",
          "description": "A shopping cart service",
          "display-name": "My Service",
          "service-tier": "Tier 1"
        },
        "integrations": {
          "pagerduty": "https://my-org.pagerduty.com/service-directory/PMyService"
        },
        "org": {
          "application": "E-Commerce",
          "team": "my-team"
        },
        "schema-version": "v1",
        "tags": [
          "my:tag",
          "service:tag"
        ]
      }
    },
    "id": "string",
    "type": "string"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Conflict

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export service_name="my-service"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions/${service_name}" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

DELETE https://api.ap1.datadoghq.com/api/v2/services/definitions/{service_name}https://api.datadoghq.eu/api/v2/services/definitions/{service_name}https://api.ddog-gov.com/api/v2/services/definitions/{service_name}https://api.datadoghq.com/api/v2/services/definitions/{service_name}https://api.us3.datadoghq.com/api/v2/services/definitions/{service_name}https://api.us5.datadoghq.com/api/v2/services/definitions/{service_name}

Overview

Delete a single service definition in the Datadog Service Catalog. This endpoint requires the apm_service_catalog_write permission.

OAuth apps require the apm_service_catalog_write authorization scope to access this endpoint.

Arguments

Path Parameters

Name

Type

Description

service_name [required]

string

The name of the service.

Response

OK

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export service_name="my-service"
# Curl command
curl -X DELETE "https://api.ap1.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/services/definitions/${service_name}" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"

PREVIEWING: drodriguezhdez/add_public_docs_log_summarization