View all methods

scorecards.update

Update an existing scorecard

Facts

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

Arguments

Required arguments

Name	Type	Description
token	Token	Auth token passed as an HTTP header.
id	Text	The unique ID of the scorecard.

Optional arguments

Name	Type	Description
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.
checks	Array<Check>	The individual checks that are applied to entities.

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.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/scorecards.update \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  --data '{
    "id": "b32jobtq7y3u",
    "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": "#ff0000",
    "levels": [
      {
        "key": "bronze",
        "id": "r6mh6hsf7j3n",
        "name": "Bronze",
        "color": "#ff0000",
        "rank": 1
      },
      {
        "key": "silver",
        "id": "u4gs3e92pdos",
        "name": "Silver",
        "color": "#00ff00",
        "rank": 2
      },
      {
        "key": "gold",
        "id": "aspobyccnttu",
        "name": "Gold",
        "color": "#0000ff",
        "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
      }
    ]
  }'

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": [],
    "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": "#ff0000"
      },
      {
        "id": "u4gs3e92pdos",
        "name": "Silver",
        "rank": 2,
        "color": "#00ff00"
      },
      {
        "id": "aspobyccnttu",
        "name": "Gold",
        "rank": 3,
        "color": "#0000ff"
      }
    ],
    "empty_level_label": "Incomplete",
    "empty_level_color": "#ff0000",
    "checks": [
      {
        "id": "l351pkre5qpx",
        "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": "xvpc48vapb7j",
        "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": "s5h7y9980va6",
        "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.