Web API

Testspace provides a REST API, designed to have predictable, resource-oriented URLs that leverage built-in features of HTTP, like authentication, verbs and response codes. All data is sent and received in JSON format and UTF-8 encoding. Any off-the-shelf HTTP client can be used to communicate with the API.

This API is not for publishing test results. The Testspace client is required for pushing data to the server.

Overview

Authentication

Testspace API is authenticated using HTTP Basic Auth over HTTPS. Any requests over plain HTTP will fail.

The credentials may be given either as username:password or as access-token:(You can generate and get an Access token from your user settings).

For example using curl you can pass the -u flag:

$ curl -u <username:password> "https://domain.testspace.com/api/projects"
$ curl -u <access-token:> "https://domain.testspace.com/api/projects"

or set the Authorization header:

$ curl -H "Authorization: Token <access-token>" "https://domain.testspace.com/api/projects"

All requests are associated with a specific user in Testspace and permissions are limited to that user's capabilities.

Requests

The base URL of the API is https://domain.testspace.com/api where domain should be replaced with your organization subdomain.

Parameters

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter:

$ curl -u username:password "https://domain.testspace.com/api/projects/123/spaces?name=ABC"

In this example, the value '123' is provided for the project :id parameter in the path while :name is passed in the query string.

For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL must be encoded as JSON with a Content-Type of application/json, or the API will return a 415 Unsupported Media Type status code:

$ curl -u username:password "https://domain.testspace.com/api/spaces/1234" \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{"description":"some description"}'

HTTP Verbs

The API strives to use appropriate HTTP verbs for each action:

• GET - To retrieve a resource or a collection of resources
• POST - To create a resource
• PATCH or PUT - To modify a resource
• DELETE - To delete a resource

Responses

All response bodies, including errors, are JSON encoded with a Content-Type of application/json.

A single resource is represented as a JSON object:

{
  "field1": "value",
  "field2": true,
  "field3": []
}

A collection of resources is represented as a JSON array of objects:

[
  {
    "field1": "value",
    "field2": true,
    "field3": []
  },
  {
    "field1": "another value",
    "field2": false,
    "field3": []
  }
]

All timestamps are returned in ISO 8601 format.

Unset fields will be represented as a null instead of being omitted. If the field is an array, it will be represented as an empty array - i.e. [].

Errors

The API uses HTTP status codes to indicate success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. authentication failed, a resource not found, a validation error, etc.), and codes in the 5xx range indicate an internal server error.

All 4xx series errors will be returned with a JSON object in the body:

{
   "message": "Not Found"
}

5xx series error codes do not return JSON bodies.

Pagination

Listing resources will be paginated to 30 items by default. To control that you can pass the following parameters:

parameter	description
page	Page number (default: 1)
per_page	Number of items to list per page (default: 30, max: 100)

For example to list 50 projects per page:

$ curl -u username:password "https://domain.testspace.com/api/projects?per_page=50"

A Link header is sent back with each response. It has a rel set to prev/next/first/last and contains the relevant URL. Please use these links instead of constructing your own URLs.

Projects

All the information in Testspace is organized in Projects. A project contains one or more Spaces.

Field	Type	Notes
id	integer	The unique ID of the project
name	string	The name of the project
description	string	The description of the project
is_private	boolean	True if the project is private, false otherwise
source_repo_url	string	The URL of the repo if connected project
spaces_url	string	The URL of the contained Spaces list API
created_at	timestamp	The date/time when the project was created
updated_at	timestamp	The date/time when the project was last updated

To request details about projects and to create or modify projects use the following API methods.

List projects

GET /api/projects

A successful response includes an array of projects, as each entry in the list follows the same format as get a project:

200 OK
Content-Type: application/json

[
  { "id": 123, "name": "..." },
  { "id": 345, "name": "..." },
]

Get a project

GET /api/projects/:project_id

parameter	description
:project_id	The name or the ID of a project

A successful response looks like:

200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "MyProject",
  "description": "Some description for my project",
  "is_private": true,
  "source_repo_url": null,
  "spaces_url": "https://myorg.testspace.com/api/projects/123/spaces",
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Create a project

POST /api/projects

Field	Required	Notes
name	yes	The name of the project
description	no	The description of the project
is_private	no	True (default) if the project is private, false otherwise

Sample request:

POST /api/projects
Content-Type: application/json

{
  "name": "MyProject",
  "description": "Some description for my project",
  "...": "..."
}

A successful response returns the new project following the same format as get a project:

201 Created
Location: https://domain.testspace.com/api/projects/123
Content-Type: application/json

{
  "id": 123,
  "name": "MyProject",
  "...": "..."
}

Update a project

PATCH /api/projects/:project_id

parameter	description
:project_id	The ID of a project

Field	Required	Notes
name	no	The name of the project
description	no	The description of the project
is_private	no	True if the project is private, false otherwise

Sample request:

PATCH /api/projects/123
Content-Type: application/json

{
  "name": "NewProject",
  "...": "..."
}

A successful response returns no content:

205 Reset Content

Delete a project

DELETE /api/projects/:project_id

parameter	description
:project_id	The ID of a project

Sample request:

DELETE /api/projects/123

A successful response returns no content:

204 No Content

Spaces

Each Project consists of Spaces. A Space is a collection of test Resultsand Metrics.

Field	Type	Notes
id	integer	The unique ID of the space
name	string	The name of the space
description	string	The description of the space
project_id	integer	The associated project
sandbox	boolean	True if the space is a sandbox, false otherwise
min_run_period	integer	Publication deadline for results in days (0 to disable)
active_result_set_id	integer	The current active (aka latest-complete) result set
latest_result_set_id	integer	The latest result set
results_url	string	The URL of the contained Results list API
metrics_url	string	The URL of the contained Metrics list API
created_at	timestamp	The date/time when the space was created
updated_at	timestamp	The date/time when the space was last updated

To request details about spaces and to create or modify spaces use the following API methods.

List spaces

GET /api/projects/:project_id/spaces

parameter	description
:project_id	The name or the ID of the associated project

A successful response includes an array of spaces, as each entry in the list follows the same format as Get a space:

200 OK
Content-Type: application/json

[
  { "id": 1234, "name": "..." },
  { "id": 5678, "name": "..." },
]

Get a space

GET /api/spaces/:space_id

parameter	description
:space_id	The ID of a space

GET /api/projects/:project_id/spaces/:space_name

parameter	description
:project_id	The name or the ID of the associated project
:space_name	The URL-encoded name of a space

A successful response looks like:

200 OK
Content-Type: application/json

{
  "id": 1234,
  "name": "MySpace",
  "description": "Some description for my space",
  "project_id": 12,
  "sandbox": false,
  "min_run_period": 1,
  "active_result_set_id": 10823,
  "latest_result_set_id": 10823,
  "results_url": "https://myorg.testspace.com/api/spaces/1234/results",
  "metrics_url": "https://myorg.testspace.com/api/spaces/1234/metrics",
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Create a space

POST /api/projects/:project_id/spaces

parameter	description
:project_id	The ID of the associated project

Field	Required	Notes
name	yes	The name of the space
description	no	The description of the space
sandbox	no	True for a sandbox space, false (default) otherwise
base	no	The name of an existing Space to copy settings from

Sample request:

POST /api/projects/12/spaces
Content-Type: application/json

{
  "name": "MySpace",
  "description": "Some description for my space",
  "...": "..."
}

A successful response returns the new space following the same format as Get a space:

201 Created
Location: https://domain.testspace.com/api/spaces/1234
Content-Type: application/json

{
  "id": 1234,
  "name": "MySpace",
  "...": "..."
}

Update a space

PATCH /api/spaces/:space_id

parameter	description
:space_id	The ID of a space

Field	Required	Notes
name	no	The name of the space
description	no	The description of the space
sandbox	no	True for a sandbox space, false otherwise
min_run_period	no	Publication deadline for results in days (0 to disable)

Sample request:

PATCH /api/spaces/1234
Content-Type: application/json

{
  "name": "NewSpace",
  "...": "..."
}

A successful response returns no content:

205 Reset Content

Delete a space

DELETE /api/spaces/:space_id

parameter	description
:space_id	The ID of a space

Sample request:

DELETE /api/spaces/1234

A successful response returns no content:

204 No Content

Results

Each Space consists of a collection of Results. A Result is a collection of test cases organized in folders and suites.

Field	Type	Notes
id	integer	The unique ID of the result
name	string	The name of the result
description	string	The description of the result
complete	boolean	True if the result is a complete, false otherwise
pinned	boolean	True if the result is a pinned, false otherwise
space_id	integer	The associated space
user_id	integer	The user who created the result
commit_id	string	The associated repo commit id (e.g. SHA for git)
build_url	string	The URL of the originating CI build
suite_counts	array	The contained suites [passed, failed, na] counters
session_suite_counts	array	The contained suites [passed, failed, na] counters for session only results
case_counts	array	The contained cases [passed, failed, na, errored, untested] counters
session_case_counts	array	The contained cases [passed, failed, na, errored, untested] counters for session only results
annotation_counts	array	The contained annotations [error, warn, info] counters
failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters
session_failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters for session only results
duration	number	The duration of the result in milliseconds
session_duration	number	The duration of the result in milliseconds for session only results
health	object	The health of the result
result_contents_url	string	The URL of the Result contents API
result_failures_url	string	The URL of the Result failures API
created_at	timestamp	The date/time when the result was created
updated_at	timestamp	The date/time when the result was last updated

To request details about results and to create or modify results use the following API methods.

List results

GET /api/projects/:project_id/spaces/:space_id/results
GET /api/spaces/:space_id/results

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space

A successful response includes an array of results, as each entry in the list follows the same format as Get a result:

200 OK
Content-Type: application/json

[
  { "id": 1234, "name": "..." },
  { "id": 5678, "name": "..." },
]

Get a result

This API point is provided only for the purpose of accessing a result record without its content. To obtain a result's content please use the Get result content API or if interested in the associated result failures use the Get result failures API.

GET /api/projects/:project_id/spaces/:space_id/results/:result_id
GET /api/spaces/:space_id/results/:result_id

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:result_id	The name or the ID of a result

A successful response looks like:

200 OK
Content-Type: application/json

{
  "id": 123456,
  "name": "MyResult",
  "description": "Some description for my result",
  "complete": true,
  "pinned": false,
  "user_id": 15,
  "space_id": 1234,
  "commit_id": "220cc4abf6989d38726403a085c542290c7f4c13",
  "build_url": "https://...",
  "suite_counts": [1508, 147, 4],
  "session_suite_counts": [1508, 147, 4],
  "case_counts": [35093, 517, 292, 5, 0],
  "session_case_counts": [35093, 517, 292, 5, 0],
  "annotation_counts": [5951, 3558, 332415],
  "failure_counts": [5, 17, 495, 21, 8, 35],
  "session_failure_counts": [5, 17, 495, 21, 8, 35],
  "duration": 7201360.0,
  "session_duration": 7201360.0,
  "health": {
    "state": "failure",
    "description": "Unhealthy. One or more Testspace metrics were out of range...",
    "badges": [
      {
        "metric_id": 1234567,
        "name": "test",
        "value": 35,
        "status": "failing"
      },
    ]
  },
  "result_contents_url": "https://myorg.testspace.com/api/spaces/1234/results/123456/contents",
  "result_failures_url": "https://myorg.testspace.com/api/spaces/1234/results/123456/failures",
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Create a result

This API point is provided only for the purpose of creation of empty (no content) result records. To create a result and push content to it please use the Testspace client.

POST /api/spaces/:space_id/results

parameter	description
:space_id	The ID of the associated space

Field	Required	Notes
name	yes	The name of the result
description	no	The description of the result
commit_id	no	The associated repo commit id
build_url	no	The URL of the originating CI build

Sample request:

POST /api/spaces/1234/results
Content-Type: application/json

{
  "name": "MyResult",
  "description": "Some description for my result",
}

A successful response returns the new result following the same format as Get a result:

201 Created
Location: https://domain.testspace.com/api/spaces/1234/results/123456
Content-Type: application/json

{
  "id": 123456,
  "name": "MyResult",
  "...": "..."
}

Update a result

This API point is provided only for the purpose of updating a result record without affecting its content. To update a result's content please use the Testspace client.

PATCH /api/spaces/:space_id/results/:result_id

parameter	description
:space_id	The ID of a space
:result_id	The ID of a result

Field	Required	Notes
name	no	The name of the result
description	no	The description of the result
complete	no	True for a complete result, false otherwise
pinned	no	True for a pinned result, false otherwise
commit_id	no	The associated repo commit id
build_url	no	The URL of the originating CI build

Sample request:

PATCH /api/spaces/1234/results/123456
Content-Type: application/json

{
  "name": "NewResult",
  "...": "..."
}

A successful response returns no content:

205 Reset Content

Delete a result

DELETE /api/spaces/:space_id/results/:result_id

parameter	description
:space_id	The ID of a space
:result_id	The ID of a result

Sample request:

DELETE /api/spaces/1234/results/123456

A successful response returns no content:

204 No Content

Get result contents

Each Result is a collection of test cases organized in folders and suites.

Folder

Field	Type	Notes
id	integer	The unique ID of the folder
type	string	Always folder
name	string	The name of the folder
path	string	The full path to the folder
description	string	The description of the folder
carried	boolean	True if the folder has one or more suites carried from another session, false otherwise
suite_counts	array	The contained suites [passed, failed, na] counters
session_suite_counts	array	The contained suites [passed, failed, na] counters for session only results
case_counts	array	The contained cases [passed, failed, na, errored, untested] counters of result
session_case_counts	array	The contained cases [passed, failed, na, errored, untested] counters for session only results
annotation_counts	array	The contained annotations [error, warn, info] counters
failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters
session_failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters for session only results
duration	number	The duration of the folder in milliseconds
session_duration	number	The duration of the folder in milliseconds for session only results
folder_contents_url	string	The URL of the Folder's contents API

Suite

Field	Type	Notes
id	integer	The unique ID of the suite
type	string	Always suite
name	string	The name of the suite
path	string	The full path to the suite
description	string	The description of the suite
status	string	The status of the suite (i.e. passed, failed, na)
carried	boolean	True if the suite is carried from another session, false otherwise
case_counts	array	The contained cases [passed, failed, na, errored, untested] counters
session_case_counts	array	The contained cases [passed, failed, na, errored, untested] counters for session only results
annotation_counts	array	The contained annotations [error, warn, info] counters
failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters
session_failure_counts	array	The contained failures [new, flaky, consistent, passing, resolved, exempt] counters for session only results
duration	number	The duration of the suite in milliseconds
session_duration	number	The duration of the suite in milliseconds for session only results
suite_contents_url	string	The URL of the Suite's contents API
download_url	string	The URL to download from an XML-snippet of the contained test cases

Annotation

Field	Type	Notes
id	integer	The unique ID of the annotation
type	string	Always annotation
name	string	The name of the annotation
description	string	The description of the annotation
download_url	string	The URL to download from the associated file content

To get the contents of a result use the following API methods.

GET /api/projects/:project_id/spaces/:space_id/results/:result_id/contents/<:path>
GET /api/spaces/:space_id/results/:result_id/contents/<:path>

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:result_id	The name or the ID of a result
:path	The named folder/suite path

A successful response looks like:

• a collection, when :path represents a Folder

200 OK
Content-Type: application/json

[
  {
    "id": 1234,
    "result_id": 123456,
    "type": "folder",
    "name": "MyFolder",
    "path": "path/MyFolder",
    "description": "Some description for my folder",
    "suite_counts": [150, 14, 4],
    "case_counts": [3509, 51, 29, 5, 0],
    "annotation_counts": [5951, 355, 3324],
    "failure_counts": [5, 17, 49, 21, 8, 35],
    "duration": 1234.5,
    "folder_contents_url": "https://myorg.testspace.com/api/spaces/1234/results/123456/contents/path/MyFolder"
  },
  {
    "id": 5678,
    "result_id": 123456,
    "type": "suite",
    "name": "MySuite",
    "path": "path/MySuite",
    "description": "Some description for my suite",
    "status": "failed",
    "case_counts": [50, 6, 2, 0, 0],
    "annotation_counts": [10, 0, 3],
    "failure_counts": [5, 17, 4, 2, 8, 5],
    "duration": 1234.5,
    "suite_contents_url": "https://myorg.testspace.com/api/spaces/1234/results/123456/suite-contents/5678",
    "download_url": "https://..."
  },
  {
    "id": 16369873,
    "result_id": 123456,
    "type": "annotation",
    "name": "MyAnnotation",
    "description": "Some description for my annotation",
    "download_url": "https://..."
  },
]

• an object, when :path represents a Suite

200 OK
Content-Type: application/json

{
  "id": 5678,
  "result_id": 123456,
  "type": "suite",
  "name": "MySuite",
  "path": "path",
  "description": "Some description for my suite",
  "status": "failed",
  "case_counts": [50, 6, 2, 0, 0],
  "annotation_counts": [10, 0, 3],
  "failure_counts": [5, 17, 4, 2, 8, 5],
  "duration": 1234.5,
  "suite_contents_url": "https://myorg.testspace.com/api/spaces/1234/results/123456/suite-contents/5678",
  "download_url": "https://..."
}

Get suite contents

Each Suite is a collection of test cases.

Field	Type	Notes
id	integer	The unique ID of the test case
type	string	Always case
name	string	The name of the test case
description	string	The description of the test case
status	string	The status of the test case. Possible values are passed, failed, errored, or na
cause	string	The failure cause in case of failed/errored status
annotation_counts	array	The contained annotations [error, warn, info] counters
duration	number	The duration of the test case in milliseconds
tracking	object	A failure object if the test case is being tracked. For details see the Result failures API

To get the contents of a suite use the following API method.

GET /api/projects/:project_id/spaces/:space_id/results/:result_id/suite_contents/:suite_id

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:result_id	The name or the ID of a result
:suite_id	The ID of a suite

A successful response looks like:

200 OK
Content-Type: application/json

[
  {
    "id": 456789,
    "suite_id": 5678,
    "result_id": 123456,
    "name": "MyCase",
    "description": "blah blah",
    "status": "failed",
    "annotation_counts": [2, 0, 1],
    "duration": "567",
    "tracking":  {
      "state": "flaky",
      "history": ["F", "P", "F", "F"],
      "exempt": false,
      "message": null,
      "tracked_count": 4,
      "failed_at": "2014-10-06T18:02:54Z",
      "passed_at": null
    },
  }
]

Get result failures

For each Result any failed/errored test case is being tracked. The set of those test cases is provided via the Failures end point.

Field	Type	Notes
key	string	The key of a test case failure (formatted as path/to/suite().case)
state	string	The state of the failure (i.e. new, flaky, consistent, passing, resolved)
history	array	The history of the failure, represented with a first-letter-notation array, where: -F is for failed, -P - passed, -N - non-applicable, -E - errored, -M - missing In case of exemption X is prepended. If a type repeats the number of consecutive times is appended to the letter - Fn.
exempt	boolean	True if the failure is a 'exempt', false otherwise
message	string	The triage message associated with the failure
tracked_count	integer	The number of results the failure has been tracked for
failed_at	timestamp	The date/time when the failure first occurred
passed_at	timestamp	The date/time when the failure started passing before being resolved

To get the failures of a result use the following API methods.

GET /api/projects/:project_id/spaces/:space_id/results/:result_id/failures
GET /api/spaces/:space_id/results/:result_id/failures

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:result_id	The name or the ID of a result

A successful response looks like:

200 OK
Content-Type: application/json

[
  {
    "key": "path/to/MySuite().MyCase",
    "state": "flaky",
    "history": ["F", "P", "F", "F"],
    "exempt": false,
    "message": null,
    "tracked_count": 4,
    "failed_at": "2014-10-06T18:02:54Z",
    "passed_at": null
  },
]

Metrics

For each Result push to a Space a set of Metrics are collected. A Metric consists of a collection of historical datasets.

Field	Type	Notes
id	integer	The unique ID of the metric
name	string	The name of the metric
data_source	string	The path to the data source of the metric
chart_type	string	The type (i.e. lines or columns) of the metric's chart
max_range	integer	The "default" max range on the metric's chart y-axes
max_range_limit	integer	The max range "limit" (0 for unlimited) on the metric's chart y-axes
units	string	The units of the data being graphed
space_id	integer	The associated space
badge_url	string	The URL of the associated badge
embed_url	string	The URL of the associated graph
variables	array	The "variables" (calculated of the input dataset) being graphed
thresholds	array	The "thresholds" (calculated of the input dataset) being graphed
badge	object	The "badge" (calculated of the variables/thresholds and/or input datasets) being computed
created_at	timestamp	The date/time when the metric was created
updated_at	timestamp	The date/time when the metric was last updated

To request details about metrics and to create or modify metrics use the following API methods.

List metrics

GET /api/projects/:project_id/spaces/:space_id/metrics
GET /api/spaces/:space_id/metrics

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space

A successful response includes an array of metrics, as each entry in the list follows the same format as Get a metric:

200 OK
Content-Type: application/json

[
  { "id": 1234, "name": "..." },
  { "id": 5678, "name": "..." },
]

Get a metric

This API point is provided only for the purpose of accessing a metric record without its datasets. To obtain metric's datasets please use the Get Metric Datasets API.

GET /api/projects/:project_id/spaces/:space_id/metrics/:metric_id
GET /api/spaces/:space_id/metrics/:metric_id

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:metric_id	The ID of a metric

A successful response looks like:

200 OK
Content-Type: application/json

{
  "id": 123456,
  "name": "MyMetric",
  "data_source": "/path/to/suite[dataset_label]",
  "chart_type": "lines",
  "max_range": 10,
  "max_range_limit": 10,
  "units": "seconds",
  "space_id": 1234,
  "badge_url": "https://...",
  "embed_url": "https://...",
  "variables": [
    {
      "name": "var-one",
      "color": "#008000",
      "expression": "round(d1/1000,1)"
    },
  ],
  "thresholds": [
    {
      "name": "thresh-one",
      "color": "#464646",
      "expression": "3"
    },
  ],
  "badge": {
    "name": "thresh-one",
    "value_expression": "concat(v1,'s')",
    "criteria_expression": "v1 \u003c= t1",
    "is_enabled": true
  },
  "created_at": "2014-10-06T18:02:54Z",
  "updated_at": "2014-12-04T19:59:42Z"
}

Create a metric

Only Custom Metrics can be created via this API.

POST /api/spaces/:space_id/metrics

parameter	description
:space_id	The ID of the associated space

Field	Required	Notes
name	yes	The name of the metric
data_source	yes	The path to the data source of the metric
chart_type	no	The type (i.e. lines or columns) of the metric's chart
max_range	no	The "default" max range on the metric's chart y-axes
units	no	The units of the data being graphed
variables	yes	The "variables" (calculated of the input dataset) being graphed
thresholds	no	The "thresholds" (calculated of the input dataset) being graphed
badge	no	The "badge" (calculated of the variables/thresholds and/or input datasets) being computed

Sample request:

POST /api/spaces/1234/metrics
Content-Type: application/json

{
  "name": "MyMetric",
  "data_source": "/path/to/suite[dataset_label]",
  "...": "..."
}

A successful response returns the new metric following the same format as Get a metric:

201 Created
Location: https://domain.testspace.com/api/spaces/1234/metrics/123456
Content-Type: application/json

{
  "id": 123456,
  "name": "MyMetric",
  "...": "..."
}

Update a metric

PATCH /api/spaces/:space_id/metrics/:metric_id

parameter	description
:space_id	The ID of a space
:metric_id	The ID of a metric

Field	Required	Notes
name	no	The name of the metric
chart_type	no	The type (i.e. lines or columns) of the metric's chart
max_range	no	The "default" max range on the metric's chart y-axes
units	no	The units of the data being graphed
variables	no	The "variables" (calculated of the input dataset) being graphed
thresholds	no	The "thresholds" (calculated of the input dataset) being graphed
badge	no	The "badge" (calculated of the variables/thresholds and/or input datasets) being computed

Sample request:

PATCH /api/spaces/1234/metrics/123456
Content-Type: application/json

{
  "name": "NewMetric",
}

A successful response returns no content:

205 Reset Content

Delete a metric

DELETE /api/spaces/:space_id/metrics/:metric_id

parameter	description
:space_id	The ID of a space
:metric_id	The ID of a metric

Sample request:

DELETE /api/spaces/1234/metrics/123456

A successful response returns no content:

204 No Content

Get metric datasets

A Metric consists of a collection of historical datasets.

Field	Type	Notes
id	integer	The unique ID of the metric
metric_id	integer	The associated metric
result_set_id	integer	The associated result
raw_values	object	The set of raw metric data (named d1 to d10) pushed with the result
evaluated_values	object	The set of evaluated data (named v1..v5, t1, t2, b and bc) that are being graphed
created_at	timestamp	The date/time when the metric dataset was created
updated_at	timestamp	The date/time when the metric dataset was last updated

To get the datasets of a metric use the following API methods.

GET /api/projects/:project_id/spaces/:space_id/metrics/:metric_id/datasets
GET /api/spaces/:space_id/metrics/:metric_id/datasets

parameter	description
:project_id	The name or the ID of the associated project
:space_id	The name (only when project is specified) or the ID of the associated space
:metric_id	The ID of a metric

A successful response looks like:

200 OK
Content-Type: application/json

[
  {
    "id": 369040,
    "metric_id": 94828,
    "result_set_id": 112168,
    "raw_values": {"d1":2093,"d2":1900,"d3":2740,"d4":null,"d5":null,"d6":null,"d7":null,"d8":null,"d9":null,"d10":null},
    "evaluated_values": {"v1":"2.1","v2":"1.9","v3":"2.7","v4":null,"v5":null,"t1":3,"t2":null,"b":"2.1s","bc":true},
    "created_at":"2019-10-11T10:58:02.000-07:00",
    "updated_at":"2019-10-11T10:58:02.000-07:00",
    "published_at":"2019-10-11T10:58:02.000-07:00"
  },
]