View all methods

scorecards.create

Create a new scorecard.

Facts

Method	POST https://api.getdx.com/scorecards.create
Required scope	scorecards:write

Arguments

Required arguments

Name	Type	Description
token	Token	Auth token passed as an HTTP header.
name	Text	The name of the scorecard.
type	"LEVEL" | "POINTS"	The scorecard’s type—see the following two tables for required arguments based on this type.
entity_filter_type	"entity_types" | "sql"	The filtering strategy when deciding what entities this scorecard should assess. When entity_types is chosen, the entity_filter_type_identifiers argument must be present. When sql is chosen, the entity_filter_sql argument must be present.

For levels-based scorecards:

Key	Type	Description
empty_level_label	Text	The label to display when an entity has not achieved any levels in the scorecard, e.g. Not production-ready.
empty_level_color	Text	The color hex code to display when an entity has not achieved any levels in the scorecard, e.g. #ff0000.
levels	Array<Level>	The levels that can be achieved in this scorecard, e.g. Bronze, Silver, and Gold. There must be at least one level defined.

For points-based scorecards:

Key	Type	Description
check_groups	Array<Check Group>	Groups of checks, to help organize the scorecard for entity owners.

Optional arguments

Name	Type	Description
description	Text	A description about the scorecard’s purpose. Multi-line descriptions are supported.
published	Boolean	Whether the scorecard is published or unlisted.
entity_filter_type_identifiers	Array<Text>	A list of entity type identifiers to use when filtering for entities this scorecard applies to, e.g. ["service", "package"].
tags	Array<Tag>	A list of tags to apply to the scorecard, e.g. [{"value": "production"}]. When the tag does not exist, it will be created with a default color.
entity_filter_sql	Text	A SQL query for advanced filtering on entities that this scorecard applies to. For example, this query will select every entity in the DX catalog: SELECT identifier FROM dx_catalog_entities
checks	Array<Check>	The individual checks that are applied to entities.
editors	Array<Integer>	A list of User IDs that have edit permissions on the scorecard.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/scorecards.create \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "name": "Reliability",
    "description": "Quality checks related to deployments and observability",
    "type": "LEVEL",
    "published": true,
    "entity_filter_type": "entity_types",
    "entity_filter_type_identifiers": ["service"],
    "tags": [{"value": "production"}],
    "empty_level_label": "Incomplete",
    "empty_level_color": "#e5e7eb",
    "levels": [
      {
        "key": "bronze",
        "name": "Bronze",
        "color": "#fb923c",
        "rank": 1
      },
      {
        "key": "silver",
        "name": "Silver",
        "color": "#9ca3af",
        "rank": 2
      },
      {
        "key": "gold",
        "name": "Gold",
        "color": "#fbbf24",
        "rank": 3
      }
    ],
    "checks": [
      {
        "name": "HTTP health check defined",
        "sql": "select 'PASS' as status",
        "scorecard_level_key": "bronze",
        "output_enabled": false,
        "ordering": 0,
        "external_url": "http://example.com",
        "published": true
      },
      {
        "name": "OpenTelemetry is instrumented",
        "sql": "select 'PASS' as status",
        "scorecard_level_key": "silver",
        "output_enabled": false,
        "ordering": 0,
        "external_url": "http://example.com",
        "published": true
      },
      {
        "name": "Monitors are configured",
        "sql": "select 'PASS' as status",
        "scorecard_level_key": "gold",
        "output_enabled": false,
        "ordering": 0,
        "external_url": "http://example.com",
        "published": true
      }
    ],
    "editors": [
      2468
    ]
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "scorecard": {
    "id": "b32jobtq7y3u",
    "name": "Reliability",
    "description": "Quality checks related to deployments and observability",
    "type": "LEVEL",
    "published": true,
    "entity_filter_type": "entity_types",
    "entity_filter_sql": null,
    "entity_filter_type_ids": ["4aav7arl6mo6"],
    "entity_filter_type_identifiers": ["service"],
    "tags": [{ "value": "production", "color": "#38bdf8" }],
    "editors": [
      {
        "id": 2468,
        "email": "liszt@example.com",
        "name": "Franz Liszt",
        "avatar": "https://avatars.slack-edge.com/2024-07-05/1234567890.jpg",
        "created_at": "2024-06-28T04:03:53.245Z"
      }
    ],
    "admins": [
      {
        "id": 123456,
        "email": "beethoven@example.com",
        "name": "Ludwig van Beethoven",
        "avatar": "https://avatars.slack-edge.com/2024-07-05/1234567890.jpg",
        "created_at": "2024-06-28T04:03:53.245Z"
      }
    ],
    "sql_errors": [],
    "levels": [
      {
        "id": "r6mh6hsf7j3n",
        "name": "Bronze",
        "rank": 1,
        "color": "#fb923c"
      },
      {
        "id": "u4gs3e92pdos",
        "name": "Silver",
        "rank": 2,
        "color": "#9ca3af"
      },
      {
        "id": "aspobyccnttu",
        "name": "Gold",
        "rank": 3,
        "color": "#fbbf24"
      }
    ],
    "empty_level_label": "Incomplete",
    "empty_level_color": "#e5e7eb",
    "checks": [
      {
        "id": "mc3nh3ohhu94",
        "ordering": 0,
        "name": "HTTP health check defined",
        "description": null,
        "sql": "select 'PASS' as status",
        "filter_sql": null,
        "filter_message": null,
        "output_enabled": false,
        "output_type": null,
        "output_custom_options": null,
        "output_aggregation": null,
        "external_url": "http://example.com",
        "published": true,
        "level": {
          "id": "r6mh6hsf7j3n",
          "name": "Bronze"
        }
      },
      {
        "id": "5j7qeidau4wm",
        "ordering": 0,
        "name": "OpenTelemetry is instrumented",
        "description": null,
        "sql": "select 'PASS' as status",
        "filter_sql": null,
        "filter_message": null,
        "output_enabled": false,
        "output_type": null,
        "output_custom_options": null,
        "output_aggregation": null,
        "external_url": "http://example.com",
        "published": true,
        "level": {
          "id": "u4gs3e92pdos",
          "name": "Silver"
        }
      },
      {
        "id": "127k8vpx8mp1",
        "ordering": 0,
        "name": "Monitors are configured",
        "description": null,
        "sql": "select 'PASS' as status",
        "filter_sql": null,
        "filter_message": null,
        "output_enabled": false,
        "output_type": null,
        "output_custom_options": null,
        "output_aggregation": null,
        "external_url": "http://example.com",
        "published": true,
        "level": {
          "id": "aspobyccnttu",
          "name": "Gold"
        }
      }
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error	Description
not_authed	No authentication token provided.
invalid_auth	Some aspect of authentication cannot be validated.