--- title: Get all service definitions description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Service Definition --- # Get all service definitions{% #get-all-service-definitions %} Copy pageCopied {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------- | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/services/definitions | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/services/definitions | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/services/definitions | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/services/definitions | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/services/definitions | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/services/definitions | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/services/definitions | | us5.datadoghq.com | GET https://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](https://docs.datadoghq.com/api/latest/scopes.md#service-definition) 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 {% tab title="200" %} OK {% tab title="Model" %} Create service definitions response. | Parent field | Field | Type | Description | | ------------------ | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | | data | [object] | Data representing service definitions. | | data | attributes | object | Service definition attributes. | | attributes | meta | object | Metadata about a service definition. | | meta | github-html-url | string | GitHub HTML URL. | | meta | ingested-schema-version | string | Ingestion schema version. | | meta | ingestion-source | string | Ingestion source of the service definition. | | meta | last-modified-time | string | Last modified time of the service definition. | | meta | origin | string | User defined origin of the service definition. | | meta | origin-detail | string | User defined origin's detail of the service definition. | | meta | warnings | [object] | A list of schema validation warnings. | | warnings | instance-location | string | The warning instance location. | | warnings | keyword-location | string | The warning keyword location. | | warnings | message | string | The warning message. | | attributes | schema | | Service definition schema. | | schema | Option 1 | object | **DEPRECATED**: Deprecated - Service definition V1 for providing additional service metadata and integrations. | | Option 1 | contact | object | Contact information about the service. | | contact | email | string | Service owner's email. | | contact | slack | string | Service owner's Slack channel. | | Option 1 | extensions | object | Extensions to V1 schema. | | Option 1 | external-resources | [object] | A list of external links related to the services. | | external-resources | name [*required*] | string | Link name. | | external-resources | type [*required*] | enum | Link type. Allowed enum values: `doc,wiki,runbook,url,repo,dashboard,oncall,code,link` | | external-resources | url [*required*] | string | Link URL. | | Option 1 | info [*required*] | object | Basic information about a service. | | info | 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. | | info | description | string | A short description of the service. | | info | display-name | string | A friendly name of the service. | | info | service-tier | string | Service tier. | | Option 1 | integrations | object | Third party integrations that Datadog supports. | | integrations | pagerduty | string | PagerDuty service URL for the service. | | Option 1 | org | object | Org related information about the service. | | org | application | string | App feature this service supports. | | org | team | string | Team that owns the service. | | Option 1 | schema-version [*required*] | enum | Schema version being used. Allowed enum values: `v1` | | Option 1 | tags | [string] | A set of custom tags. | | schema | Option 2 | object | Service definition V2 for providing service metadata and integrations. | | Option 2 | contacts | [ ] | A list of contacts related to the services. | | contacts | Option 1 | object | Service owner's email. | | Option 1 | contact [*required*] | string | Contact value. | | Option 1 | name | string | Contact email. | | Option 1 | type [*required*] | enum | Contact type. Allowed enum values: `email` | | contacts | Option 2 | object | Service owner's Slack channel. | | Option 2 | contact [*required*] | string | Slack Channel. | | Option 2 | name | string | Contact Slack. | | Option 2 | type [*required*] | enum | Contact type. Allowed enum values: `slack` | | contacts | Option 3 | object | Service owner's Microsoft Teams. | | Option 3 | contact [*required*] | string | Contact value. | | Option 3 | name | string | Contact Microsoft Teams. | | Option 3 | type [*required*] | enum | Contact type. Allowed enum values: `microsoft-teams` | | Option 2 | 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. | | Option 2 | dd-team | string | Experimental feature. A Team handle that matches a Team in the Datadog Teams product. | | Option 2 | docs | [object] | A list of documentation related to the services. | | docs | name [*required*] | string | Document name. | | docs | provider | string | Document provider. | | docs | url [*required*] | string | Document URL. | | Option 2 | extensions | object | Extensions to V2 schema. | | Option 2 | integrations | object | Third party integrations that Datadog supports. | | integrations | opsgenie | object | Opsgenie integration for the service. | | opsgenie | region | enum | Opsgenie instance region. Allowed enum values: `US,EU` | | opsgenie | service-url [*required*] | string | Opsgenie service url. | | integrations | pagerduty | string | PagerDuty service URL for the service. | | Option 2 | links | [object] | A list of links related to the services. | | links | name [*required*] | string | Link name. | | links | type [*required*] | enum | Link type. Allowed enum values: `doc,wiki,runbook,url,repo,dashboard,oncall,code,link` | | links | url [*required*] | string | Link URL. | | Option 2 | repos | [object] | A list of code repositories related to the services. | | repos | name [*required*] | string | Repository name. | | repos | provider | string | Repository provider. | | repos | url [*required*] | string | Repository URL. | | Option 2 | schema-version [*required*] | enum | Schema version being used. Allowed enum values: `v2` | | Option 2 | tags | [string] | A set of custom tags. | | Option 2 | team | string | Team that owns the service. | | schema | Option 3 | object | Service definition v2.1 for providing service metadata and integrations. | | Option 3 | application | string | Identifier for a group of related services serving a product feature, which the service is a part of. | | Option 3 | contacts | [ ] | A list of contacts related to the services. | | contacts | Option 1 | object | Service owner's email. | | Option 1 | contact [*required*] | string | Contact value. | | Option 1 | name | string | Contact email. | | Option 1 | type [*required*] | enum | Contact type. Allowed enum values: `email` | | contacts | Option 2 | object | Service owner's Slack channel. | | Option 2 | contact [*required*] | string | Slack Channel. | | Option 2 | name | string | Contact Slack. | | Option 2 | type [*required*] | enum | Contact type. Allowed enum values: `slack` | | contacts | Option 3 | object | Service owner's Microsoft Teams. | | Option 3 | contact [*required*] | string | Contact value. | | Option 3 | name | string | Contact Microsoft Teams. | | Option 3 | type [*required*] | enum | Contact type. Allowed enum values: `microsoft-teams` | | Option 3 | 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. | | Option 3 | description | string | A short description of the service. | | Option 3 | extensions | object | Extensions to v2.1 schema. | | Option 3 | integrations | object | Third party integrations that Datadog supports. | | integrations | opsgenie | object | Opsgenie integration for the service. | | opsgenie | region | enum | Opsgenie instance region. Allowed enum values: `US,EU` | | opsgenie | service-url [*required*] | string | Opsgenie service url. | | integrations | pagerduty | object | PagerDuty integration for the service. | | pagerduty | service-url | string | PagerDuty service url. | | Option 3 | lifecycle | string | The current life cycle phase of the service. | | Option 3 | links | [object] | A list of links related to the services. | | links | name [*required*] | string | Link name. | | links | provider | string | Link provider. | | links | type [*required*] | enum | Link type. Allowed enum values: `doc,repo,runbook,dashboard,other` | | links | url [*required*] | string | Link URL. | | Option 3 | schema-version [*required*] | enum | Schema version being used. Allowed enum values: `v2.1` | | Option 3 | tags | [string] | A set of custom tags. | | Option 3 | team | string | Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. | | Option 3 | tier | string | Importance of the service. | | schema | Option 4 | object | Service definition v2.2 for providing service metadata and integrations. | | Option 4 | application | string | Identifier for a group of related services serving a product feature, which the service is a part of. | | Option 4 | ci-pipeline-fingerprints | [string] | A set of CI fingerprints. | | Option 4 | contacts | [object] | A list of contacts related to the services. | | contacts | contact [*required*] | string | Contact value. | | contacts | name | string | Contact Name. | | contacts | type [*required*] | string | Contact type. Datadog recognizes the following types: `email`, `slack`, and `microsoft-teams`. | | Option 4 | 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. | | Option 4 | description | string | A short description of the service. | | Option 4 | extensions | object | Extensions to v2.2 schema. | | Option 4 | integrations | object | Third party integrations that Datadog supports. | | integrations | opsgenie | object | Opsgenie integration for the service. | | opsgenie | region | enum | Opsgenie instance region. Allowed enum values: `US,EU` | | opsgenie | service-url [*required*] | string | Opsgenie service url. | | integrations | pagerduty | object | PagerDuty integration for the service. | | pagerduty | service-url | string | PagerDuty service url. | | Option 4 | languages | [string] | The service's programming language. Datadog recognizes the following languages: `dotnet`, `go`, `java`, `js`, `php`, `python`, `ruby`, and `c++`. | | Option 4 | lifecycle | string | The current life cycle phase of the service. | | Option 4 | links | [object] | A list of links related to the services. | | links | name [*required*] | string | Link name. | | links | provider | string | Link provider. | | links | type [*required*] | string | Link type. Datadog recognizes the following types: `runbook`, `doc`, `repo`, `dashboard`, and `other`. | | links | url [*required*] | string | Link URL. | | Option 4 | schema-version [*required*] | enum | Schema version being used. Allowed enum values: `v2.2` | | Option 4 | tags | [string] | A set of custom tags. | | Option 4 | team | string | Team that owns the service. It is used to locate a team defined in Datadog Teams if it exists. | | Option 4 | tier | string | Importance of the service. | | Option 4 | type | string | The type of service. | | data | id | string | Service definition id. | | data | type | string | Service definition type. | {% /tab %} {% tab title="Example" %} ```json { "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" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \# Curl command curl -X GET "https://api.datadoghq.com/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" ##### ```python """ Get all service definitions returns "OK" response """ from datadog_api_client import ApiClient, Configuration from datadog_api_client.v2.api.service_definition_api import ServiceDefinitionApi from datadog_api_client.v2.model.service_definition_schema_versions import ServiceDefinitionSchemaVersions configuration = Configuration() with ApiClient(configuration) as api_client: api_instance = ServiceDefinitionApi(api_client) response = api_instance.list_service_definitions( schema_version=ServiceDefinitionSchemaVersions.V2_1, ) print(response) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" python3 "example.py" ##### ```ruby # Get all service definitions returns "OK" response require "datadog_api_client" api_instance = DatadogAPIClient::V2::ServiceDefinitionAPI.new opts = { schema_version: ServiceDefinitionSchemaVersions::V2_1, } p api_instance.list_service_definitions(opts) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" rb "example.rb" ##### ```go // Get all service definitions returns "OK" response package main import ( "context" "encoding/json" "fmt" "os" "github.com/DataDog/datadog-api-client-go/v2/api/datadog" "github.com/DataDog/datadog-api-client-go/v2/api/datadogV2" ) func main() { ctx := datadog.NewDefaultContext(context.Background()) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV2.NewServiceDefinitionApi(apiClient) resp, r, err := api.ListServiceDefinitions(ctx, *datadogV2.NewListServiceDefinitionsOptionalParameters().WithSchemaVersion(datadogV2.SERVICEDEFINITIONSCHEMAVERSIONS_V2_1)) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `ServiceDefinitionApi.ListServiceDefinitions`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `ServiceDefinitionApi.ListServiceDefinitions`:\n%s\n", responseContent) } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" go run "main.go" ##### ```java // Get all service definitions returns "OK" response import com.datadog.api.client.ApiClient; import com.datadog.api.client.ApiException; import com.datadog.api.client.v2.api.ServiceDefinitionApi; import com.datadog.api.client.v2.api.ServiceDefinitionApi.ListServiceDefinitionsOptionalParameters; import com.datadog.api.client.v2.model.ServiceDefinitionSchemaVersions; import com.datadog.api.client.v2.model.ServiceDefinitionsListResponse; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); ServiceDefinitionApi apiInstance = new ServiceDefinitionApi(defaultClient); try { ServiceDefinitionsListResponse result = apiInstance.listServiceDefinitions( new ListServiceDefinitionsOptionalParameters() .schemaVersion(ServiceDefinitionSchemaVersions.V2_1)); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling ServiceDefinitionApi#listServiceDefinitions"); System.err.println("Status code: " + e.getCode()); System.err.println("Reason: " + e.getResponseBody()); System.err.println("Response headers: " + e.getResponseHeaders()); e.printStackTrace(); } } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" java "Example.java" ##### ```rust // Get all service definitions returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV2::api_service_definition::ListServiceDefinitionsOptionalParams; use datadog_api_client::datadogV2::api_service_definition::ServiceDefinitionAPI; use datadog_api_client::datadogV2::model::ServiceDefinitionSchemaVersions; #[tokio::main] async fn main() { let configuration = datadog::Configuration::new(); let api = ServiceDefinitionAPI::with_config(configuration); let resp = api .list_service_definitions( ListServiceDefinitionsOptionalParams::default() .schema_version(ServiceDefinitionSchemaVersions::V2_1), ) .await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ##### ```typescript /** * Get all service definitions returns "OK" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration(); const apiInstance = new v2.ServiceDefinitionApi(configuration); const params: v2.ServiceDefinitionApiListServiceDefinitionsRequest = { schemaVersion: "v2.1", }; apiInstance .listServiceDefinitions(params) .then((data: v2.ServiceDefinitionsListResponse) => { console.log( "API called successfully. Returned data: " + JSON.stringify(data) ); }) .catch((error: any) => console.error(error)); ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" tsc "example.ts" {% /tab %}