--- title: Get all service definitions description: Get a list of all service definitions from the Datadog Service Catalog. breadcrumbs: Docs > API > Get all service definitions --- > For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/llms.txt). # Get all service definitions ## v2 (latest) | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------- | | 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 | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/services/definitions | | 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 | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/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 | ### 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://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/scopes.md#service-definition) to access this endpoint. ### Arguments #### Query Strings | Field | Type | Description | | -------------- | ------- | -------------------------------------------------------------------------------------------- | | page[size] | integer | Number of items to return per page. The maximum allowed value is 100. Default: `10`. | | page[number] | integer | Specific page number to return. Default: `0`. | | schema_version | enum | The schema version desired in the response. Allowed enum values: `v1`, `v2`, `v2.1`, `v2.2`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="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 | | object | **DEPRECATED**: Deprecated - Service definition V1 for providing additional service metadata and integrations. | | | contact | object | Contact information about the service. | | contact | email | string | Service owner’s email. | | contact | 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. | | 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. | | | 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. | | | integrations | object | Third party integrations that Datadog supports. | | integrations | pagerduty | string | PagerDuty service URL for the service. | | | org | object | Org related information about the service. | | org | application | string | App feature this service supports. | | org | 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. | | schema | | object | Service definition V2 for providing service metadata and integrations. | | | contacts | [] | A list of contacts related to the services. | | contacts | | object | Service owner's email. | | | contact [*required*] | string | Contact value. | | | name | string | Contact email. | | | type [*required*] | enum | Contact type. Allowed enum values: `email`. | | contacts | | object | Service owner's Slack channel. | | | contact [*required*] | string | Slack Channel. | | | name | string | Contact Slack. | | | type [*required*] | enum | Contact type. Allowed enum values: `slack`. | | contacts | | 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. | | docs | name [*required*] | string | Document name. | | docs | provider | string | Document provider. | | docs | url [*required*] | string | Document URL. | | | extensions | object | Extensions to V2 schema. | | | 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. | | | 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. | | | 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. | | | 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. | | schema | | 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 | [] | A list of contacts related to the services. | | contacts | | object | Service owner's email. | | | contact [*required*] | string | Contact value. | | | name | string | Contact email. | | | type [*required*] | enum | Contact type. Allowed enum values: `email`. | | contacts | | object | Service owner's Slack channel. | | | contact [*required*] | string | Slack Channel. | | | name | string | Contact Slack. | | | type [*required*] | enum | Contact type. Allowed enum values: `slack`. | | contacts | | 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. | | 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. | | | lifecycle | string | The current life cycle phase of the service. | | | 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. | | | 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. | | schema | | 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. | | 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`. | | | 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. | | 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. | | | 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. | | 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. | | | 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 | string | The type of service. | | data | id | string | Service definition id. | | data | type | string | Service definition type. | {% /tab %} {% tab label="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 %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/services/definitions" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% tab label="Go" %} ```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()) ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN")) 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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ``` {% /tab %} {% tab label="Java" %} ```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(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); 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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ``` {% /tab %} {% tab label="Python" %} ```python """ Get all service definitions returns "OK" response """ from os import environ 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() configuration.access_token = environ["DD_BEARER_TOKEN"] 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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ``` {% /tab %} {% tab label="Ruby" %} ```ruby # Get all service definitions returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] end 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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" rb "example.rb" ``` {% /tab %} {% tab label="Rust" %} ```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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: ```bash DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ``` {% /tab %} {% tab label="TypeScript" %} ```typescript /** * Get all service definitions returns "OK" response */ import { client, v2 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration({ authMethods: { AuthZ: { accessToken: process.env.DD_BEARER_TOKEN as string, }, }, }); 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://dnd37xeb23o8n.cloudfront.net/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: ```bash DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" tsc "example.ts" ``` {% /tab %} {% /tabs %}