NAV
http shell

Introduction

Welcome to the CucumberStudio API! You can use our API endpoints to get information on your projects in our database. It is RESTful and follows the {json:api} specification.

Since we don't provide integration with any programming languages (yet!), the examples are written in shell, using the curl command.

Our API documentation was created with Slate.

API rate limits

HTTP/1.1 429 Too Many Requests
Retry-After: 42
HTTP/1.1 429 Too Many Requests
# snip #
Retry-After: 42
# snip #

Your application can make up to 200 API requests per minute.

Once the limit is exceeded, clients receive an HTTP 429 with a Retry-After: X header to indicate how long their timeout period is before they will be able to send requests again. The timeout period is set to 60 seconds once the limit is exceeded.

Note

The rate limit is based on the IP address.

Getting Started

This little tutorial will guide you to request our API for the first time.

Your API credentials

Before accessing our API you need to generate your API credentials. Sign in to your account on CucumberStudio then go to your profile page. Click the Generate new API credentials button.

User profile page

User API credentials

Your first request

Replace $PROJECT_ID, $ACCESS_TOKEN, $CLIENT_ID and $UID with yours

GET https://studio.cucumber.io/api/projects/$PROJECT_ID/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: $ACCESS_TOKEN
client: $CLIENT_ID
uid: $UID
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl https://studio.cucumber.io/api/projects/$PROJECT_ID/scenarios \
    -H 'Accept: application/vnd.api+json; version=1' \
    -H 'access-token: $ACCESS_TOKEN' \
    -H 'client: $CLIENT_ID' \
    -H 'uid: $UID'
{
  "data": [
    {
      "type": "scenarios",
      "id": "668555",
      "attributes": {
        "name": "Card has been disabled (1)",
        "description": "An error is displayed when the cart has been disabled"
      },
      "links": {
        "self": "/scenarios/668555"
      }
    },
    {
      "type": "scenarios",
      "id": "668556",
      "attributes": {
        "name": "Account has sufficient funds for transferring cash (1)",
        "description": ""
      },
      "links": {
        "self": "/scenarios/668556"
      }
    }
  ]
}

For your first request, you'll need your API credentials, and a project ID. All the API endpoints depend on a project. You can retrieve their ID in the address bar of your browser while you are viewing the dashboard of your project.

In the following example we are looking for the ID of the sample project Testing CASH WITHDRAWAL: the ID is 116088.

Retrieve project id

Now to retrieve all the scenarios of your project use the endpoint api/projects/$PROJECT_ID/scenarios. The HTTP call looks like the following:

GET https://studio.cucumber.io/api/projects/$PROJECT_ID/scenarios

Replace the $PROJECT_ID with the ID of one of your project. The following headers MUST be part of the query:

Every requests to the API must include those 4 headers.

The access token, the client ID and the UID are your API Credentials.

The header Accept tells the API to respond using the {json:api} format and asks for the version 1 of the API.

Renewing your API Credentials

Replace $EMAIL_ADDRESS and $PASSWORD with your CucumberStudio credentials

POST https://studio.cucumber.io/api/auth/sign_in HTTP/1.1
Content-Type: application/json

{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
access-token: iHr2dTV-UBK3Xa9vXOXERA
token-type: Bearer
client: TscNP_R2vdAV-yQc8ZjftQ
expiry: 1518274095
uid: ...@...
curl -XPOST https://studio.cucumber.io/api/auth/sign_in \
    -H 'Content-Type: application/json' \
    -d '{"email": "$EMAIL_ADDRESS", "password": "$PASSWORD"}' \
    -D /dev/stdout

HTTP/1.1 200 OK
# some response headers have been sniped
access-token: iHr2dTV-UBK3Xa9vXOXERA
token-type: Bearer
client: TscNP_R2vdAV-yQc8ZjftQ
expiry: 1518274095
uid: ...@...
# other response headers have been sniped
{
  "data": [
    {
        ...
    }
  ]
}

Your access token, as explain on your profile page after it has been generated, will expire. You can generate a new one on your profile page by clicking the Generate new API credentials button again, but it is also possible to manage it programmaticaly, using the API.

To generate or renew your API credentials use this endpoint: api/auth/sign_in.

POST https://studio.cucumber.io/api/auth/sign_in

Post your CucumberStudio credentials (email and password) encoded as JSON. If you have been successfully authenticated your API credentials will be in the response headers within the keys access-token, client and uid. The expiry header is the expiration timestamp of your new token.

Authentication

To get your credentials:

POST https://studio.cucumber.io/api/auth/sign_in HTTP/1.1
Content-Type: application/json

{"email": "my_cucumberstudio_account", "password": "my_cucumberstudio_account"}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
access-token: sUaWO8m8v5Lkv5pxnLCXzA
token-type: Bearer
client: AfLp4PsN9ZieqHas-X5lrA
expiry: 1486047985
uid: my_cucumberstudio_account
curl -XPOST \
    -H "Content-Type: application/json" \
    -d '{"email": "my_cucumberstudio_account", "password": "my_cucumberstudio_account"}' \
    -D - https://studio.cucumber.io/api/auth/sign_in

HTTP/1.1 200 OK
# snip.
access-token: sUaWO8m8v5Lkv5pxnLCXzA
token-type: Bearer
client: AfLp4PsN9ZieqHas-X5lrA
expiry: 1486047985
uid: my_cucumberstudio_account
# snip.

An API call example

GET https://studio.cucumber.io/api/<endpoint> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
curl https://studio.cucumber.io/api/<endpoint> \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Before sending requests to our endpoints, you need an authentication token. This token is made up of three data:

You can get this authentication token using the auth/sign_in endpoint (only working if you registered to CucumberStudio using your email) or directly in your CucumberStudio profile page.

CucumberStudio expects for the authentication token to be included in all API requests to the server, in the HTTP headers of your requests

Useful information about the access-token

Projects

Get projects

GET https://studio.cucumber.io/api/projects/ HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "projects",
      "id": "1",
      "attributes": {
        "created-at": "2017-10-02T12:01:27.125Z",
        "updated-at": "2018-01-10T14:55:49.848Z",
        "last-author": "harry@example.org",
        "name": "And the Philosopher's Stone",
        "description": "This is where all starts",
        "bdd-mode": true
      },
      "links": {
        "self": "/projects/1"
      },
      "relationships": {
        "scenarios-folder": {
          "links": {
            "self": "/projects/1/relationships/scenarios-folder",
            "related": "/projects/1/scenarios-folder"
          }
        }
      }
    },
    {
      "type": "projects",
      "id": "2",
      "attributes": {
        "created-at": "2017-10-02T12:01:27.125Z",
        "updated-at": "2018-01-10T14:55:49.848Z",
        "last-author": "harry@example.org",
        "name": "And the Chamber of Secrets",
        "description": "With douchebag Draco Malfoy...",
        "bdd-mode": false
      },
      "links": {
        "self": "/projects/2"
      },
      "relationships": {
        "scenarios-folder": {
          "links": {
            "self": "/projects/2/relationships/scenarios-folder",
            "related": "/projects/2/scenarios-folder"
          }
        }
      }
    }
  ]
}

This endpoint retrieves all projects of the logged-in user

Get a particular project

GET https://studio.cucumber.io/api/projects/<project_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "projects",
      "id": "1",
      "attributes": {
        "created-at": "2017-10-02T12:01:27.125Z",
        "updated-at": "2018-01-10T14:55:49.848Z",
        "last-author": "harry@example.org",
        "name": "And the Philosopher's Stone",
        "description": "This is where all starts",
        "bdd-mode": true
      },
      "links": {
        "self": "/projects/1"
      },
      "relationships": {
        "scenarios-folder": {
          "links": {
            "self": "/projects/1/relationships/scenarios-folder",
            "related": "/projects/1/scenarios-folder"
          }
        }
      }
    }
  ]
}

This endpoint retrieves a specific project of the logged-in user

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve

Create a project backup

Create the project backup

POST https://studio.cucumber.io/api/projects/<project_id>/backups HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/backups" \
    -X POST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "projects",
      "id": "1",
      "attributes": {
        "created-at": "2017-10-02T12:01:27.125Z",
        "updated-at": "2018-01-10T14:55:49.848Z",
        "last-author": "harry@example.org",
        "name": "And the Philosopher's Stone",
        "description": "This is where all starts",
        "bdd-mode": true,
        "new-backup-in-progress": true
      },
      "links": {
        "self": "/projects/1"
      },
      "relationships": {
        "scenarios-folder": {
          "links": {
            "self": "/projects/1/relationships/scenarios-folder",
            "related": "/projects/1/scenarios-folder"
          }
        }
      }
    }
  ]
}

This endpoint will schedule the backup creation of a given project. The operation is acknownledged with a 202 Accepted HTTP code. The returned project attributes include a "new-backup-in-progress" field set to true.

URL Parameters

Parameter Description
project_id The ID of the project you want to create the backup for

Get last backup state

GET https://studio.cucumber.io/api/projects/<project_id>/backups/last HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/backups/last" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "backups",
    "id": "9876",
    "attributes": {
      "project-id": 1234,
      "new-backup-in-progress": false,
      "updated-at": "2018-06-13T13:19:28.380Z",
      "file-name": "coffee_machine__hiptest_publisher_sample_20180419.zip",
      "file-size": 33968,
      "url": "https://attachments-hiptest-production.s3.amazonaws.com/backups/backup_files/000/012/345/original/coffee_machine__hiptest_publisher_sample_20180419.zip?AWSAccessKeyId=XXXXX&Expires=1528298175&Signature=XXX"
    },
    "links": {
      "self": "/backups/9876"
    }
  }
}

This endpoint is useful to track the state of a project backup creation and get the last created backup URL.

If the project does not have any backups yet, or when the very first backup is in progress, this endpoint will respond with empty data: { "data": null }.

URL Parameters

Parameter Description
project_id The ID of the project you want to see the last backup of

Getting root scenarios folder of a project

GET https://studio.cucumber.io/api/projects?include=scenarios-folder HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/project?include=scenarios-folder" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Also works when retrieving a single project

You can use the JSONAPI include syntax to fetch the scenarios root folder of your project

Action words

Get action words of a given project

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "actionwords",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "definition": "actionword 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n",
        "errors": []
      },
      "links": {
        "self": "/actionwords/1"
      }
    },
    {
      "type": "actionwords",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Defeat Voldemort",
        "description": "And save the world, hurray!",
        "definition": "actionword 'Defeat Voldemort' do\nend\n",
        "errors": []
      },
      "links": {
        "self": "/actionwords/2"
      }
    }
  ]
}

This endpoint retrieves all action words of a given project.

You can retrieve tags of an action word from the tags endpoint.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the actionwords from

Find actionwords by tags

Find actionwords by tags key

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "type": "actionwords",
            "id": "2585231",
            "attributes": {
                "created-at": "2019-05-02T19:21:58.344Z",
                "updated-at": "2019-12-02T14:07:01.018Z",
                "last-author": "harry@example.org",
                "name": "I handle coffee grounds",
                "description": "",
                "definition": "actionword 'I handle coffee grounds' do\nend\n",
                "is-shared": false,
                "is-outdated": false,
                "errors": []
            },
            "links": {
                "self": "/actionwords/2585231"
            },
            "relationships": {
                "tags": {},
                "callers": {}
            }
        },
        {
            "type": "actionwords",
            "id": "2585234",
            "attributes": {
                "created-at": "2019-05-02T19:21:58.587Z",
                "updated-at": "2019-12-02T14:06:29.856Z",
                "last-author": "harry@example.org",
                "name": "displayed message is:",
                "description": "",
                "definition": "actionword 'displayed message is:' (__free_text = \"\") do\n  call 'message \"message\" should be displayed' (message = __free_text)\nend\n",
                "is-shared": false,
                "is-outdated": false,
                "errors": []
            },
            "links": {
                "self": "/actionwords/2585234"
            },
            "relationships": {
                "tags": {},
                "callers": {}
            }
        }
    ],
    "included": []
}

Find actionwords by tags key and value

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords/find_by_tags?key=<tag_key>&value=<tag_value>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "type": "actionwords",
            "id": "2585234",
            "attributes": {
                "created-at": "2019-05-02T19:21:58.587Z",
                "updated-at": "2019-12-02T14:06:29.856Z",
                "last-author": "harry@example.org",
                "name": "displayed message is:",
                "description": "",
                "definition": "actionword 'displayed message is:' (__free_text = \"\") do\n  call 'message \"message\" should be displayed' (message = __free_text)\nend\n",
                "is-shared": false,
                "is-outdated": false,
                "errors": []
            },
            "links": {
                "self": "/actionwords/2585234"
            },
            "relationships": {
                "tags": {},
                "callers": {}
            }
        }
    ],
    "included": []
}

This endpoint retrieves all actionwords of a given project and having the given tag.

Field name Description
tag_key The KEY of the tag you use to retrieve the actionwords
tag_value The VALUE of the tag you use to retrieve the actionwords

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the actionwords from

Request parameters

Parameter Description
key The key of the tag
value The value of the tag

Get a single action word

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "actionwords",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "definition": "actionword 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n",
        "errors": []
      },
      "links": {
        "self": "/actionwords/1"
      }
    }
}

This endpoint retrieves a single action word of a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the actionword from
actionword_id The ID of the action word you want to get

Create an action word

POST https://studio.cucumber.io/api/projects/<project_id>/actionwords HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "Find horcruxes",
      "description": "That will help to kill Voldemort",
      "definition": "step {action: \"Find the last one\"}\n step {result: \"Found it!\"}"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/actionwords" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "Find horcruxes", "description": "That will help to kill Voldemort", "definition": "step {action: \"Find the last one\"}\n step {result: \"Found it!\"}" } } }'
{
  "data":
    {
      "type": "actionwords",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "definition": "actionword 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n",
        "errors": []
      },
      "links": {
        "self": "/actionwords/1"
      }
    }
}

This endpoint create new action word.

URL Parameters

Parameter Description
project_id The ID of the project in wich you want to create the actionword

Mandatory fields

Field Description
name (String) The name of the action word.

Other fields

Field Description
description (String) The description of the action word.
definition (String) The body of the definition of the action word.

Update an action word

PATCH https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "actionwords",
    "id": <actionword_id>,
    "attributes": {
      "name": "Find horcruxes",
      "description": "That will help to kill Voldemort",
      "definition": "actionword 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data $'{ "data": { "type": "actionwords", "id": <actionword_id>, "attributes": { "name": "Find horcruxes", "description": "That will help to kill Voldemort", "definition": "actionword \'Find horcruxes\' do\\n  step {action: \\"Find the last one\\"}\\n  step {result: \\"Found it!\\"}\\nend\\n" } } }'
{
  "data":
    {
      "type": "actionwords",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "definition": "actionword 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n",
        "errors": []
      },
      "links": {
        "self": "/actionwords/1"
      }
    }
}

This endpoint updates the name, descrpition and/or definition of a single action word of a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the action word from
actionword_id The ID of the action word you want to update

Delete an action word

DELETE https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

This endpoint delete an action word.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the action word from
actionword_id The ID of the action word you want to delete

Get an action word callers

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/callers HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/callers" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "type": "scenarios",
            "id": "1",
            "attributes": {
                "created-at": "2018-08-31T09:12:18.338Z",
                "updated-at": "2018-08-31T09:12:18.338Z",
                "last-author": "harry@example.org",
                "name": "It is possible to take 40 coffees before there is really no more beans",
                "description": "...",
                "folder-id": 1,
                "definition": "..."
            },
            "links": {
                "self": "/scenarios/503"
            },
            "relationships": {
                "folder": {},
                "tags": {}
            }
        },
        {
            "type": "folders",
            "id": "1",
            "attributes": {
                "created-at": "2018-08-31T09:12:17.797Z",
                "updated-at": "2018-09-03T14:19:57.066Z",
                "last-author": "harry@example.org",
                "name": "Serve coffee",
                "description": "...",
                "definition": "...",
                "parent-id": 0
            },
            "links": {
                "self": "/folders/263"
            },
            "relationships": {
                "tags": {}
            }
        }
    ]
}

This endpoint retrieves the list of action word callers (scenarios, folders, actionwords).

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the actionword from
actionword_id The ID of the action word you want to get

Scenarios

Get scenarios of a given project

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios[?include=<fields>] HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios[?include=<fields>]" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "folder-id": 162629,
        "definition": "scenario 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n"
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
          "folder": {},
          "tags": {},
          "actionwords": {},
          "test-snapshots": {}
      }
    },
    {
      "type": "scenarios",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Defeat Voldemort",
        "description": "And save the world, hurray !",
        "folder-id": 162629,
        "definition": "scenario 'Defeat Voldemort' do\nend\n"
      },
      "links": {
        "self": "/scenarios/2"
      },
      "relationships": {
          "folder": {},
          "tags": {},
          "actionwords": {},
          "test-snapshots": {}
      }
    }
  ]
}

This endpoint retrieves all scenarios of a given project.

You can use the JSONAPI include syntax to fetch additional data about your tests.

The available additional data are the following:

Field name Description
folder The folder scenarios belongs to
tags The tags of the scenarios
actionwords Actionwords used by the scenarios
test-snapshots All linked test-snapshots in test runs including their last test results

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from

Find scenarios by tags

Find scenarios by tags key

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "created-at" : "2018-01-31T16:03:45.387Z",
        "updated-at" : "2018-02-05T14:54:50.826Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "folder-id": 162629,
        "definition": "scenario 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n"
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
        "folder": {}
      }
    },
    {
      "type": "scenarios",
      "id": "2",
      "attributes": {
        "created-at" : "2018-02-05T13:15:13.285Z",
        "updated-at" : "2018-02-05T13:18:19.397Z",
        "last-author" : "harry@example.org",
        "name": "Defeat Voldemort",
        "description": "And save the world, hurray !",
        "folder-id": 162629,
        "definition": "scenario 'Defeat Voldemort' do\nend\n"
      },
      "links": {
        "self": "/scenarios/2"
      },
      "relationships": {
        "folder": {}
      }
    }
  ],
  "included": []
}

Find scenarios by tags key and value

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/find_by_tags?key=<tag_key>&value=<tag_value>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "created-at" : "2018-01-31T16:03:45.387Z",
        "updated-at" : "2018-02-05T14:54:50.826Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "folder-id": 162629,
        "definition": "scenario 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n"
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
        "folder": {}
      }
    }
  ],
  "included": []
}

This endpoint retrieves all scenarios of a given project and having the given tag.

Field name Description
tag_key The KEY of the tag you use to retrieve the scenarios
tag_value The VALUE of the tag you use to retrieve the scenarios

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from

Request parameters

Parameter Description
key The key of the tag
value The value of the tag

Get a single scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>[?include=<fields>] HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>[?include=<fields>]" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "folder-id": 162629,
        "definition": "scenario 'Find horcruxes' do\n  step {action: \"Find the last one\"}\n  step {result: \"Found it!\"}\nend\n",
        "errors": []
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
        "folder": {}
      }
    }
}

This endpoint retrieves a single scenario of a given project.

You can use the JSONAPI include syntax to fetch additional data about your tests.

The available additional data are the following:

Field name Description
folder The folder the scenario belongs to
tags The tags of the scenario
actionwords Actionwords used by the scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenario from
scenario_id The ID of the scenario you want to get

Create a scenario

POST https://studio.cucumber.io/api/projects/<project_id>/scenarios HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "Find horcruxes",
      "folder-id": 1234
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/scenarios" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "Find horcruxes", "folder-id": "1234" } } }'
{
  "data":
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "description": "",
        "folder-id": "1234",
        "definition": "",
        "errors": []
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
        "folder": {}
      }
    }
}

This endpoint create a new scenario.

URL Parameters

Parameter Description
project_id The ID of the project in which you want to create the scenario

Mandatory fields

Field Description
name (String) The name of the scenario

Other fields

Field Description
folder-id (Integer) The id of the folder containing the scenario

Update a scenario

PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "scenarios",
    "id": <scenario_id>,
    "attributes": {
      "name": "The new name of the scenario",
      "description": "The new description of the scenario",
      "definition": "scenario 'The new definition of the scenario' do\nend\n",
      "folder-id": "162630"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "scenarios", "id": <scenario_id>, "attributes": {"name": "The new name of the scenario", "description": "The new description of the scenario", "definition": "scenario \'The new definition of the scenario\' do\\nend\\n", "folder-id": "162630" }}}'
{
  "data":
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "name": "The new definition of the scenario",
        "description": "The new description of the scenario",
        "folder-id": "162630",
        "definition": "scenario 'The new definition of the scenario' do\nend\n"
      },
      "links": {
        "self": "/scenarios/1"
      },
      "relationships": {
        "folder": {}
      }
    }
}

This endpoint updates the name, descrpition, folder and definition of a single scenario of a given project. Note that the attributes are all optional, you can update only one of them if wanted, just don't set the key in the "attributes" hash.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenario from
scenario_id The ID of the scenario you want to update

Delete a scenario

DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

This endpoint delete a scenario.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenario from
scenario_id The ID of the scenario you want to delete

List attachments of a given scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "attachments",
      "id": "1",
      "attributes": {
        "id": 1,
        "file-name": "my-attachment.jpg",
        "file-url": "/api/projects/1/scenarios/1/attachments/1",
        "file-size": 100
      },
      "links": {
        "self": "/attachments/1"
      }
    }
  ]
}

This endpoint list all the attachments of a given scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from
scenario_id The ID of the target scenario

Get a given attachment of a given scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET -L "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --output my-attachment.jpg

This endpoint return the requested attachment of a given scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from
scenario_id The ID of the target scenario
attachment_id The ID of the target attachment

Create an attachment to a given scenario

POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/scenarios/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint create an attachment to a given scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from
scenario_id The ID of the target scenario

Update an attachment to a given scenario

PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/scenarios/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint update the attachment to a given scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from
scenario_id The ID of the target scenario
attachment_id The ID of the target attachment

Delete an attachment to a given scenario

DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
{}

This endpoint delete a given attachment of a given scenario

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenarios from
scenario_id The ID of the target scenario
attachment_id The ID of the target attachment

Features

Get feature from a given folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/feature HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders</folder_id>/feature" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": {
        "type": "folders",
        "id": "1",
        "attributes": {
            "created-at": "2018-05-22T09:15:01.430Z",
            "updated-at": "2018-10-08T14:42:00.688Z",
            "last-author": "harry@example.org",
            "name": "HP Saga",
            "description": "This project is designed to keep track of the evolution of the HP saga,
            in the most expressive way possible, thanks to BDD!",
            "definition": "folder do\nend\n",
            "parent-id": null,
            "feature": "Feature: The Philosopher's Stone\n\nScenario: Read a Hogwarts letter"
        },
        "links": {
            "self": "/folders/1"
        },
        "relationships": {
            "tags": {}
        }
    },
    "included": []
}

This endpoint retrieves Gherkin formatted feature from a specific folder.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the folder you want to get

Create from feature

POST https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/create_from_feature HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
    "data": {
        "attributes": {
            "feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley"
        }
    }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/folders</folder_id>/create_from_feature" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{ "data": { "attributes": { "feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley" } } }'
{
    "data": {
        "type": "folders",
        "id": "2",
        "attributes": {
            "created-at": "2018-05-22T09:15:01.430Z",
            "updated-at": "2018-10-08T14:42:00.688Z",
            "last-author": "harry@example.org",
            "name": "HP Saga",
            "description": "",
            "definition": "folder do\nend\n",
            "parent-id": null,
            "running-feature-imports": [
                "the_chamber_of_secrets"
            ]
        },
        "links": {
            "self": "/folders/2"
        },
        "relationships": {
            "tags": {}
        }
    },
    "included": []
}

This endpoint creates every resources from the feature into a specific folder.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the folder you want to get

Mandatory fields

Field Description
feature (String) The Gherkin formatted feature text

Update from feature

PATCH https://your_cucumberstudio_url/api/projects/<project_id>/folders/<folder_id>/update_from_feature HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
    "data": {
        "attributes": {
            "feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley\n\nScenario: ignore Dobby"
        }
    }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
    curl -XPATCH "https://your_cucumberstudio_url/api/projects/<project_id>/folders/<folder_id>/update_from_feature" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your_access_token>' \
    -H 'uid: <your_email>' \
    -H 'client: <your_client_ID>' \
    --data '{ "data": { "attributes": { "feature": "Feature: The Chamber of Secrets\n\nScenario: Shopping on Diagon Alley\n\nScenario: ignore Dobby" } } }'

{
    "data": {
        "type":"folders",
        "id":"2",
        "attributes":{
            "created-at":"2018-05-22T09:15:01.430Z",
            "updated-at":"2018-10-08T14:42:00.688Z",
            "last-author": "harry@example.org",
            "name": "HP Saga",
            "description": "This project is designed to keep track of the evolution of the HP saga,
            in the most expressive way possible, thanks to BDD!",
            "definition":"folder do\nend\n",
            "parent-id":1,
            "running-feature-imports":["the_chamber_of_secrets"],
            "scenarios-count": 1,
            "feature-updated-at":"2018-10-08T14:42:00.688Z"
        },
        "links":{
            "self":"/folders/2"
        },
        "relationships":{
            "tags":{}
        }
    },
    "included":[]
}

This endpoint update a folder and its scenarios with the content of a feature file written in Gherkin

URL Parameters

Parameter Description
project_id The ID of the project containing the folder you want to update
folder_id The ID of the folder you want to update

Mandatory fields

Field Description
feature (String) The Gherkin formatted feature text

Folders

Get folders of a given project

GET https://studio.cucumber.io/api/projects/<project_id>/folders HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "folders",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "HP Saga",
        "description": "This project is designed to keep track of the evolution of the HP saga,
        in the most expressive way possible, thanks to BDD!",
        "parent-id": null
      },
      "links": {
        "self": "/folders/1"
      }
    },
    {
      "type": "folders",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "The Philosopher's Stone",
        "description": "",
        "parent-id": 1
      },
      "links": {
        "self": "/folders/2"
      }
    }
  ]
}

This endpoint retrieves all folders of a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from

Find folders by tags

Find folders by tag key

GET https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "type": "folders",
            "id": "791625",
            "attributes": {
                "created-at": "2019-01-20T22:29:45.135Z",
                "updated-at": "2020-07-29T14:34:20.739Z",
                "last-author": "harry@example.org",
                "name": "Support internationalisation",
                "description": "As a polyglot coffee lover\nI can select the language on the coffee machine\nSo I can practice my use of greetings in several languages",
                "definition": "folder do\nend\n",
                "parent-id": 791623,
                "scenarios-count": 0,
                "feature-updated-at": "2020-07-29T14:34:20.739Z"
            },
            "links": {
                "self": "/folders/791625"
            },
            "relationships": {
                "tags": {}
            }
        },
        {
            "type": "folders",
            "id": "791626",
            "attributes": {
                "created-at": "2019-01-20T22:29:45.190Z",
                "updated-at": "2020-07-29T14:34:20.549Z",
                "last-author": "harry@example.org",
                "name": "Can be configured",
                "description": "**In order to** get the best possible coffees\n**As a** geeky coffee lover\n**I can** configure it to match my needs\n",
                "definition": "folder do\nend\n",
                "parent-id": 791623,
                "scenarios-count": 0,
                "feature-updated-at": "2020-07-29T14:34:20.549Z"
            },
            "links": {
                "self": "/folders/791626"
            },
            "relationships": {
                "tags": {}
            }
        }
    ],
    "included": []
}

Find folders by tag key and value

GET https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key>&value=<tag_value> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/find_by_tags?key=<tag_key>&value=<tag_value>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "type": "folders",
            "id": "1245135",
            "attributes": {
                "created-at": "2020-02-11T10:42:19.094Z",
                "updated-at": "2020-07-29T14:34:20.663Z",
                "last-author": "harry@example.org",
                "name": "Serve coffee",
                "description": "As a coffee lover\nI can get coffee from the machine\nSo I can enjoy the rest of the day",
                "definition": "folder do\nend\n",
                "parent-id": 791623,
                "scenarios-count": 1,
                "feature-updated-at": "2020-07-29T14:34:20.663Z"
            },
            "links": {
                "self": "/folders/1245135"
            },
            "relationships": {
                "tags": {}
            }
        }
    ],
    "included": []
}

This endpoint retrieves all folders of a given project and having the given tag.

Field name Description
tag_key The KEY of the tag you use to retrieve the folders
tag_value The VALUE of the tag you use to retrieve the folders

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from

Request parameters

Parameter Description
key The key of the tag
value The value of the tag

Get a single folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "folders",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "The Philosopher's Stone",
        "description": "",
        "parent-id": 1
      },
      "links": {
        "self": "/folders/2"
      }
    }
}

This endpoint retrieves a specific folder of a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the folder you want to get

Get children of a folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "folders",
      "id": "2",
      "attributes": {
        "name": "The Philosopher's stone",
        "description": "",
        "parent-id": 1
      },
      "links": {
        "self": "/folders/2"
      }
    },
    {
      "type": "folders",
      "id": "3",
      "attributes": {
        "name": "The Chamber of Secrets",
        "description": "",
        "parent-id": 1
      },
      "links": {
        "self": "/folders/3"
      }
    }
  ]
}

This endpoint retrieves the subfolders of a specific folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the folder you want to get the children

Get scenarios of a folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "scenarios",
      "id": "1",
      "attributes": {
        "name": "Read a Hogwarts letter"
      },
      "links": {
        "self": "/scenarios/1"
      }
    },
    {
      "type": "scenarios",
      "id": "2",
      "attributes": {
        "name": "Shopping on Diagon Alley"
      },
      "links": {
        "self": "/scenarios/2"
      }
    }
  ]
}

This endpoint retrieves the scenarios of a specific folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the folder you want to get the scenarios

Create a folder

POST https://studio.cucumber.io/api/projects/<project_id>/folders HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "A new folder",
      "parent-id": 1234
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/folders" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "A new folder", "parent-id": "1234" } } }'
{
  "data": {
    "type": "folders",
    "id": "1235",
    "attributes": {
      "created-at": "2017-10-17T08:00:33.978Z",
      "updated-at": "2017-10-18T08:28:07.791Z",
      "last-author": "harry@example.org",
      "name": "A new folder",
      "description": "",
      "definition": "folder do\nend\n",
      "parent-id": 1234
    },
    "links": {
      "self": "/folders/1235"
    }
  }
}

This endpoint create a new folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from

Mandatory fields

Field Description
name (String) The name of the folder.

Other fields

Field Description
parent-id (Integer) The id of the folder that will contain the created folder.

Update a folder

PATCH https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "folders",
    "id": "<folder_id>",
    "attributes": {
      "name": "A new folder name",
      "description": "A new description",
      "definition": "folder do end"
      "parent-id": 1233
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "A new folder name", "parent-id": "1233", "description: "A new description", "definition": "folder do end" } } }'
{
  "data": {
    "type": "folders",
    "id": "1234",
    "attributes": {
      "created-at": "2017-10-17T08:00:33.978Z",
      "updated-at": "2017-10-18T08:28:07.791Z",
      "last-author": "harry@example.org",
      "name": "A new folder name",
      "description": "A new descriptio",
      "definition": "folder do\nend\n",
      "parent-id": 1233
    },
    "links": {
      "self": "/folders/1234"
    }
  }
}

This endpoint updates a folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from

Fields

Field Description
name (String) The name of the folder.
description (String) The description of the folder.
definition (String) The definition of the folder.
parent-id (Integer) The id of the parent folder.

Delete a folder

DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {}
}

This endpoint destroy a folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder

Delete a folder children

DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/children" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {}
}

This endpoint destroys all sub-folders of the target folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder

Delete a folder scenarios

DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/scenarios" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {}
}

This endpoint destroy a folder scenarios

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder

List attachments of a given folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "attachments",
      "id": "1",
      "attributes": {
        "id": 1,
        "file-name": "my-attachment.jpg",
        "file-url": "/api/projects/1/folders/1/attachments/1",
        "file-size": 100
      },
      "links": {
        "self": "/attachments/1"
      }
    }
  ]
}

This endpoint list all the attachments of a given folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder

Get a given attachment of a given folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET -L "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --output my-attachment.jpg

This endpoint return the requested attachment of a given folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder
attachment_id The ID of the target attachment

Create an attachment to a given folder

POST https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/folders/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint create an attachment to a given folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder

Update an attachment to a given folder

PATCH https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/folders/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint update the attachment to a given folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder
attachment_id The ID of the target attachment

Delete an attachment to a given folder

DELETE https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
{}

This endpoint delete a given attachment of a given folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
folder_id The ID of the target folder
attachment_id The ID of the target attachment

Tags

Include tags when requesting elements

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>?include=tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>?include=tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "folders",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "The Philosopher's Stone",
        "description": "",
        "parent-id": 1
      },
      "links": {
        "self": "/folders/2"
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "type": "tags",
              "id": "6537"
            }
          ]
        }
      }
    },
  "included": [
    {
      "type": "tags",
      "id": "6539",
      "attributes": {
        "key": "horcruxes",
        "value": ""
      },
      "links": {
        "self": "/tags/6539"
      }
    }
  ]
}

You can use the JSONAPI include syntax to fetch tags alongside parent elements. Elements can be scenarios, actionwords, folders, test runs, tests and test folders. This is working when requesting for a list of elements, and for a single element.

Get tags of a given action word

GET https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/actionwords/<actionword_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "platform",
        "value": "Android"
      },
      "links": {
        "self": "/tags/1"
      }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": {
        "key": "automated",
        "value": "yes"
      },
      "links": {
        "self": "/tags/2"
      }
    }
  ]
}

This endpoint retrieves all tags of a given action word.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted action word
actionword_id The ID of the action word you want to retrieve the tags from

Get tags of a given scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "Status",
        "value": "InProgress"
      },
      "links": {
        "self": "/tags/1"
      }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": {
        "key": "Priority",
        "value": "Over9000"
      },
      "links": {
        "self": "/tags/2"
      }
    }
  ]
}

This endpoint retrieves all tags of a given scenario.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the tags from

Get tags of a given folder

GET https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/folders/<folder_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "Javascript",
        "value": ""
      },
      "links": {
        "self": "/tags/1"
      }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": {
        "key": "Sprint",
        "value": "1"
      },
      "links": {
        "self": "/tags/2"
      }
    }
  ]
}

This endpoint retrieves all tags of a given folder.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted folder
folder_id The ID of the folder you want to retrieve the tags from

Get tags of a given test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "priority",
        "value": "high"
      },
      "links": {
        "self": "/tags/1"
      }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": {
        "key": "jira",
        "value": "test"
      },
      "links": {
        "self": "/tags/2"
      }
    }
  ]
}

This endpoint retrieves all tags of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run you want to retrieve the tags from

Get tags of a given test

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "priority",
        "value": "high"
      },
      "links": {
        "self": "/tags/1"
      }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": {
        "key": "jira",
        "value": "test"
      },
      "links": {
        "self": "/tags/2"
      }
    }
  ]
}

This endpoint retrieves all tags of a given test.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where the test is
test_snapshot_id The ID of the test in the test-run you want to retrieve the tags from

Create tag in a scenario

POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "key": "priority",
      "value": "high"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "priority",
        "value": "high"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint creates a new tag in a scenario.

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario where you want to create the tag

Create tag in a test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "key": "priority",
      "value": "high"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "priority",
        "value": "high"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint creates a new tag in a test run.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where you want to create the tag

Create tag in a test

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "key": "priority",
      "value": "high"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "tags",
      "id": "1",
      "attributes": {
        "key": "priority",
        "value": "high"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint creates a new tag in a test.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where the test is
test_snapshot_id The ID of the test in the test-run where you want to create the tag

Update a tag in a scenario

PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "tags",
    "id": 5,
    "attributes": {
      "key": "priority",
      "value": "low"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags/<tag_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "tags","id": 5,"attributes": {"key": "priority","value": "low"}}}'
{
  "data": [
    {
      "type": "tags",
      "id": "5",
      "attributes": {
        "key": "priority",
        "value": "low"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint updates a tag in a scenario.

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario where you want to update the tag
tag_id The ID of the tag you want to update

Update a tag in a test run

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "tags",
    "id": 5,
    "attributes": {
      "key": "priority",
      "value": "low"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags/<tag_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "tags","id": 5,"attributes": {"key": "priority","value": "low"}}}'
{
  "data": [
    {
      "type": "tags",
      "id": "5",
      "attributes": {
        "key": "priority",
        "value": "low"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint updates a tag in a test run.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where you want to update the tag
tag_id The ID of the tag you want to update

Update a tag in a test

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags/<tag_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "tags",
    "id": 5,
    "attributes": {
      "key": "priority",
      "value": "low"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags/<tag_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "tags","id": 5,"attributes": {"key": "priority","value": "low"}}}'
{
  "data": [
    {
      "type": "tags",
      "id": "5",
      "attributes": {
        "key": "priority",
        "value": "low"
      },
      "links": {
        "self": "/tags/1"
      }
    }
  ]
}

This endpoint updates a tag in a test run.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where the test is
test_snapshot_id The ID of the test you want to update the tag
tag_id The ID of the tag you want to update

Delete a tag in a scenario

DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/tags<tag_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{}

This endpoint deletes a tag in a scenario.

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario where you want to delete the tag
tag_id The ID of the tag you want to delete

Delete a tag in a test run

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/tags<tag_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{}

This endpoint deletes a tag in a test run.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where you want to delete the tag
tag_id The ID of the tag you want to delete

Delete a tag in a test

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags/<tag_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/tags<tag_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{}

This endpoint deletes a tag in a test run.

Parameter Description
project_id The ID of the project that contains the wanted test run
test_run_id The ID of the test run where the test is
test_snapshot_id The ID of the test where you want to delete the tag
tag_id The ID of the tag you want to delete

Create tags alongside elements

POST https://studio.cucumber.io/api/projects/<project_id>/<element_type> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      ...
    },
    "relationships": {
      "tags": {
        "data": [
          { "type": "tag", "key": "automated" },
          { "type": "tag", "key": "sprint", value: "2" },
          { "type": "tag", "key": "priority", value: "high" }
        ]
      }
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/<element_type>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {}, "relationships": { "tags": { "data": [ { "type": "tag", "key": "automated" }, { "type": "tag", "key": "sprint", "value": "2" }, { "type": "tag", "key": "priority", "value": "high" }] } }}'
{
  "data":
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        ...
      },
      "links": {
        "self": "/test-runs/1"
      },
      "included": [
        { "type": "tags", "id": "1", "attributes": { "key": "automated", "value": "" }, "links": { "self": "/tags/1" } },
        { "type": "tags", "id": "2", "attributes": { "key": "sprint", "value": "2" }, "links": { "self": "/tags/2" } },
        { "type": "tags", "id": "3", "attributes": { "key": "priority", "value": "high" }, "links": { "self": "/tags/3" } }
      ]
    }
}

With some elements (such as the test runs and scenarios), you can create one or multiple tags linked to the created element. This can be done by specifying the "relationships" element.

Parameter Description
project_id The ID of the project in wich you want to create the actionword
element_type The type of element you want to create (scenarios, test_runs)

Datasets

Get datasets of a given scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "datasets",
      "id": "1",
      "attributes": {
        "name": "dataset-1",
        "data": {
          "parameter-1": "value 1-1",
          "parameter-2": "value 1-2"
        }
      },
      "links": {
        "self": "/datasets/1"
      }
    },
    {
      "type": "datasets",
      "id": "2",
      "attributes": {
        "name": "dataset-2",
        "data": {
          "parameter-1": "value 2-1",
          "parameter-2": "value 2-2"
        }
      },
      "links": {
        "self": "/datasets/2"
      }
    }
  ]
}

This endpoint retrieves all datasets of a given scenario.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the datasets from

Get a given dataset

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
      "type": "datasets",
      "id": "1",
      "attributes": {
          "name": "dataset-1",
          "data": {
              "parameter-1": "value 1-1",
              "parameter-2": "value 1-2"
          }
      },
      "links": {
          "self": "/datasets/1"
      }
  }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the datasets from
dataset_id The ID of the dataset you want to show

Create a dataset

POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "dataset-3",
      "data": {
        "parameter-1": "value 3-1",
        "parameter-2": "value 3-2"
      }
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "dataset-3","data": {"parameter-1": "value 3-1", "parameter-2": "value 3-2"}}}}'
{
  "data": {
      "type": "datasets",
      "id": "3",
      "attributes": {
          "name": "dataset-3",
          "data": {
              "parameter-1": "value 3-1",
              "parameter-2": "value 3-2"
          }
      },
      "links": {
          "self": "/datasets/3"
      }
  }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the datasets from

Update a dataset

PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
      "type": "datasets",
      "id": "3",
      "attributes": {
          "name": "new dataset-3 name",
          "data": {
              "parameter-1": "new value 3-1",
              "parameter-2": "new value 3-2"
          }
      }
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": { "type": "datasets", "id": "3", "attributes": {"name": "new dataset-3 name","data": {"parameter-1": "new value 3-1", "parameter-2": "new value 3-2"}}}}'
{
    "data": {
        "type": "datasets",
        "id": "3",
        "attributes": {
            "name": "new dataset-3 name",
            "data": {
                "parameter-1": "new value 3-1",
                "parameter-2": "new value 3-2"
            }
        },
        "links": {
            "self": "/datasets/3"
        }
    }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the datasets from
dataset_id The ID of the dataset you want to update

Delete a dataset

DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datasets/<dataset_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the datasets from
dataset_id The ID of the dataset you want to destroy

Datatables

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datatable HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/datatable" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "datasets",
      "id": "1",
      "attributes": {
        "name": "dataset-1",
        "data": {
          "parameter-1": "value 1-1",
          "parameter-2": "value 1-2"
        }
      },
      "links": {
        "self": "/datasets/1"
      }
    },
    {
      "type": "datasets",
      "id": "2",
      "attributes": {
        "name": "dataset-2",
        "data": {
          "parameter-1": "value 2-1",
          "parameter-2": "value 2-2"
        }
      },
      "links": {
        "self": "/datasets/2"
      }
    }
  ]
}

A datatable endpoint is available as an alias for the datasets resource.

Parameters

Get parameters of a given scenario

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "parameters",
      "id": "1",
      "attributes": {
        "name": "parameter-1"
      },
      "links": {
        "self": "/parameters/1"
      }
    },
    {
      "type": "parameters",
      "id": "2",
      "attributes": {
        "name": "parameter-2"
      },
      "links": {
        "self": "/parameters/2"
      }
    }
  ]
}

This endpoint retrieves all parameters of a given scenario.

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the parameters from

Get a given parameter

GET https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
      "type": "parameters",
      "id": "1",
      "attributes": {
          "name": "parameter-1"
      },
      "links": {
          "self": "/parameters/1"
      }
  }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the parameters from
parameter_id The ID of the parameter you want to show

Create a parameter

POST https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "parameter-3"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "parameter-3"}}}'
{
  "data": {
      "type": "parameters",
      "id": "3",
      "attributes": {
          "name": "parameter-3"
      },
      "links": {
          "self": "/parameters/3"
      }
  }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the parameters from

Update a parameter

PATCH https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
      "type": "parameters",
      "id": "3",
      "attributes": {
          "name": "new parameter-3 name"
      }
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": { "type": "parameters", "id": "3", "attributes": {"name": "new parameter-3 name"}}}'
{
    "data": {
        "type": "parameters",
        "id": "3",
        "attributes": {
            "name": "new_parameter-3_name"
        },
        "links": {
            "self": "/parameters/3"
        }
    }
}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the parameters from
parameter_id The ID of the parameter you want to update

Delete a parameter

DELETE https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/scenarios/<scenario_id>/parameters/<parameter_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{}

URL Parameters

Parameter Description
project_id The ID of the project that contains the wanted scenario
scenario_id The ID of the scenario you want to retrieve the parameters from
parameter_id The ID of the parameter you want to destroy

Test runs

Get test runs of a project

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 765,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    },
    {
      "type": "test-runs",
      "id": "2",
      "attributes": {
        "name": "Sprint 2",
        "description": "Bank robbery and blowing up things",
        "statuses": {
          "passed": 15,
          "failed": 42,
          "retest": 0,
          "undefined": 0,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": true,
        "external": false
      },
      "links": {
        "self": "/test-runs/2"
      },
      "relationships": {
        "tags": {}
      }
    }
  ]
}

This endpoint retrieves all test runs of a given project. The order is undefined.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test runs from
filter[status] "active" or "archived"

Get a single test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 765,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint retrieves a single test run of a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the test run you want to get

Archive test runs

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/archive?older_than=2021-02-13 HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/archive?older_than=2021-02-13" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "meta": {
    "archived_test_run_ids": [12, 15]
  }
}

This endpoint archives all test runs older than the specified date.

URL Parameters

Parameter Description
older_than An ISO 8601 date (YYYY-MM-DD). All test runs created before this date will be archived. Mandatory.

Include tags when fetching your test run(s)

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs?include=tags HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs?include=tags" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Also works when retrieving a single test run

You can use the JSONAPI include syntax to fetch the tags of your test runs

Create a test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "attributes": {
      "name": "Sprint 1",
      "description": "My TR description",
      "scenario_ids": [1, 2, 3]
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "Sprint 1", "description": "My TR description", "scenario_ids": [1, 2, 3]} } }'
{
  "data":
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "My TR description",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 3,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint creates a new test run.

URL Parameters

Parameter Description
project_id The ID of the project in which you want to create the test run.

Mandatory fields

Field Description
name (String) The name of the test run.

Other fields

Field Description
scenario_ids (List of Integer) The ids of scenarios you want in the test run.
external 1 or true to create an external test run.
description (String) The description of the test run.

Update test run description

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "test_runs",
    "id": <test_run_id>,
    "attributes": {
      "description": "My new test run description"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X PATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": { "type": "test_runs", "id": <test_run_id>, {"attributes": {"description": "My new test run description" } } }'
{
  "data":
    {
      "type": "test-runs",
      "id": "3",
      "attributes": {
        "created-at": "2021-06-10T09:35:01.975Z",
        "updated-at": "2021-06-14T12:19:32.607Z",
        "last-author" : "harry@example.org",
        "name": "My new test run",
        "description": "My new test run description",
        "statuses": {},
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/3"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint updates the description of a given test run.

Clone a test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "attributes": {
      "name": "My new test run",
      "test_run_id": 1
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": {"name": "My new test run", "test_run_id": 1} } }'
{
  "data":
    {
      "type": "test-runs",
      "id": "2",
      "attributes": {
        "created-at": "2019-05-23T08:30:17.398Z",
        "updated-at": "2019-05-23T08:30:17.398Z",
        "last-author" : "harry@example.org",
        "name": "My new test run",
        "description": "first test run description",
        "statuses": {},
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/2"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint clones a test run.

URL Parameters

Parameter Description
project_id The ID of the project in which you want to create the test run.

Mandatory fields

Field Description
name (String) The name of the test run.
test_run_id (Integer) The id of the source test run.

Synchronize a test run

Synchronization give you the ability to update the tests of your test run with their last version, based on the current scenarios definitions

Watch synchronization state

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>?show_synchronization_information=true HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>?show_synchronization_information=true" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 765,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false,
        "synchronization-information": {
          "synchronizable": true,
          "synchronizing": false,
          "details": {
            "deleted_folders_snapshots": [],
            "deleted_scenarios_snapshots": [],
            "deleted_tests_snapshots": []
          }
        }
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint is useful to track the state of a test run synchronization.

The synchronization operation can be dangerous. If some of your test run tests and folders are based on scenarios and folders that no longer exist, they will be destroyed. It is strongly advised to use this endpoint to get the potential impacts of a synchronization before running one.

Synchronize the test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/synchronize HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/synchronize" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data":
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 765,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false,
        "synchronization-information": {
          "synchronizable": true,
          "synchronizing": true,
          "details": {
            "deleted_folders_snapshots": [],
            "deleted_scenarios_snapshots": [],
            "deleted_tests_snapshots": []
          }
        }
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
}

This endpoint will start the synchronization of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project containing the test run
test_run_id The ID of the test run you want to synchronize

Get builds history of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/build_history HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/build_history" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
    "data": [
        {
            "id": 3,
            "date": "2018-09-12T08:19:28.446Z",
            "values": {
                "passed": 1,
                "failed": 1,
                "wip": 0,
                "retest": 1,
                "blocked": 0,
                "skipped": 0,
                "undefined": 0
            },
            "platform": "Default"
        },
        {
            "id": 2,
            "date": "2018-09-12T08:19:09.615Z",
            "values": {
                "passed": 2,
                "failed": 0,
                "wip": 1,
                "retest": 0,
                "blocked": 0,
                "skipped": 0,
                "undefined": 0
            },
            "platform": "Default"
        },
        {
            "id": 1,
            "date": "2018-09-12T07:21:21.606Z",
            "values": {
                "passed": 2,
                "failed": 1,
                "wip": 0,
                "retest": 0,
                "blocked": 0,
                "skipped": 0,
                "undefined": 0
            },
            "platform": "Default"
        }
    ]
}

This endpoint retrieves build history of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the test run you want to get

Add a scenario to an existing test run

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "test_runs",
    "id": 1,
    "attributes": {
      "scenario_id": 1
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "test_runs", "id": 1, "attributes": {"scenario_id": 1}}}'
{
  "data": [
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2019-05-27T11:39:08.281Z",
        "updated-at" : "2019-05-27T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 765,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
  ]
}

This endpoint adds a scenario to a given test run.

Add multiple scenarios to an existing test run

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "test_runs",
    "id": 1,
    "attributes": {
      "scenario_ids": [2233,76547]
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id> \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "test_runs", "id": 1, "attributes": {"scenario_ids":  [2233,76547] }}}'
{
  "data": [
    {
      "type": "test-runs",
      "id": "1",
      "attributes": {
        "created-at" : "2019-05-27T11:39:08.281Z",
        "updated-at" : "2019-05-27T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Sprint 1",
        "description": "Wandering in the countryside, doing boring stuff",
        "statuses": {
          "passed": 0,
          "failed": 0,
          "retest": 0,
          "undefined": 767,
          "blocked": 0,
          "skipped": 0,
          "wip": 0
        },
        "archived": false,
        "external": false
      },
      "links": {
        "self": "/test-runs/1"
      },
      "relationships": {
        "tags": {}
      }
    }
  ]
}

This endpoint adds several scenarios to a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the test run you want to get

List attachments of a given test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "attachments",
      "id": "1",
      "attributes": {
        "id": 1,
        "file-name": "my-attachment.jpg",
        "file-url": "/api/projects/1/test_runs/1/attachments/1",
        "file-size": 100
      },
      "links": {
        "self": "/attachments/1"
      }
    }
  ]
}

This endpoint list all the attachments of a given test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the target test run

Get a given attachment of a given test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET -L "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --output my-attachment.jpg

This endpoint return the requested attachment of a given test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the target test run
attachment_id The ID of the target attachment

Create an attachment to a given test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -X POST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/test_runs/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint create an attachment to a given test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the target test run

Update an attachment to a given test run

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/test_runs/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint update the attachment to a given test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the target test run
attachment_id The ID of the target attachment

Delete an attachment to a given test run

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
{}

This endpoint delete a given attachment of a test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test run from
test_run_id The ID of the target test run
attachment_id The ID of the target attachment

Tests

Get tests of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

{
  "data": [
    {
      "type": "test-snapshots",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Find horcruxes",
        "definition-json": {
          "scenario_name": "Find horcruxes",
          "dataset_name": null,
          "dataset_id": null,
          "steps": [
            {
              "action": "Given Harry has one horcrux"
            },
            {
              "result": "Then he should destroy it"
            },
          ],
          "index": 0
        },
        "status": "failed",
        "scenario-snapshot-id": 1,
        "folder-snapshot-id": 2
      },
      "links": {
        "self": "/test-snapshots/1"
      },
      "relationships": {
        "scenario": {},
        "dataset": {},
        "last-result": {}
      }
    },
    {
      "type": "test-snapshots",
      "id": "2",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "last-author" : "harry@example.org",
        "name": "Defeat Voldemort",
        "definition-json": {
          "scenario_name": "Defeat Voldemort",
          "dataset_name": null,
          "dataset_id": null,
          "steps": [
            {
              "action": "Given Harry cast the Expelliarmus spell"
            },
            {
              "result": "Then Voldemort should be defeated"
            }
          ],
          "index": 0
        },
        "status": "success",
        "scenario-snapshot-id": 1,
        "folder-snapshot-id": 5
      },
      "links": {
        "self": "/test-snapshots/2"
      },
      "relationships": {
        "scenario": {},
        "dataset": {},
        "last-result": {}
      }
    }
  ]
}

This endpoint retrieves all test snapshots of a test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the tests you want

Optional parameter

Parameter Description
show_step_statuses (value: 'true') Embed detailed test results including statuses per step with every tests

Errors

If the test run has just been created and the tests generation is still in progress, this endpoint will return a HTTP 423 Locked error until the tests generation finishes.

Get a test

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "test-snapshots",
    "id": "1",
    "attributes": {
      "created-at" : "2017-02-28T11:39:08.281Z",
      "updated-at" : "2017-02-28T11:39:08.281Z",
      "last-author" : "harry@example.org",
      "name": "Find horcruxes",
      "definition-json": {
        "scenario-name": "Find horcruxes",
        "dataset_name": null,
        "dataset_id": null,
        "steps": [
          {
            "action": "Given Harry has one horcrux"
          },
          {
            "result": "Then he should destroy it"
          },
        ],
        "index": 0
      },
      "status": "failed",
      "scenario-snapshot-id": 1,
      "folder-snapshot-id": 5
    },
    "links": {
      "self": "/test-snapshots/1"
    },
    "relationships": {
      "scenario": {},
      "dataset": {},
      "last-result": {}
    }
  }
}

This endpoint retrieves a particular test of a test run

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
test_snapshot_id The ID of the test you want to get

Get a test additional data

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=<fields> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=<fields>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

You can use the JSONAPI include syntax to fetch additional data about your tests.

Following example returns a test with scenario, last result and the pass rate.

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=dataset,scenario&show_passrate HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>?include=dataset,scenario&show_passrate" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "test-snapshots",
    "id": "1",
    "attributes": {
      "created-at" : "2017-02-28T11:39:08.281Z",
      "updated-at" : "2017-02-28T11:39:08.281Z",
      "last-author" : "harry@example.org",
      "name": "Find horcruxes",
      "definition-json": {
        "scenario-name": "Find horcruxes",
        "dataset_name": null,
        "dataset_id": null,
        "steps": [
          {
            "action": "Given Harry has one horcrux"
          },
          {
            "result": "Then he should destroy it"
          },
        ],
        "index": 0
      },
      "status": "passed",
      "scenario-snapshot-id": 1,
      "folder-snapshot-id": 5,
      "pass-rate": "75"
    },
    "links": {
      "self": "/test-snapshots/1"
    },
    "relationships": {
      "scenario": {
        "data": {
          "type": "scenarios",
          "id": "10"
        }
      },
      "dataset": {},
      "last-result": {
        "links": {
          "self": "/test-snapshots/1/relationships/last-result",
          "related": "/test-snapshots/1/last-result"
        },
        "data": {
          "type": "test-results",
          "id": "7"
        }
      }
    }
  },
  "included": [
    {
      "type": "scenarios",
      "id": "10",
      "attributes": {
        "created-at": "2017-02-26T07:10:42.651Z",
        "updated-at": "2017-02-26T10:22:23.206Z",
        "last-author": "harry@example.org",
        "name": "Find horcruxes",
        "description": "That will help to kill Voldemort",
        "folder-id": 162629,
        "definition": "scenario 'Find horcruxes' do\n  call given 'Harry has one horcrux'\n  call then 'he should destroy it\nend\n"
      },
      "links": {
        "self": "/scenarios/10"
      },
      "relationships": {
        "folder": {}
      }
    },
    {
      "type": "test-results",
      "id": "7",
      "attributes": {
        "created-at": "2017-03-01T14:38:16.612Z",
        "updated-at": "2018-03-01T14:38:16.612Z",
        "last-author": "harry@example.org",
        "status": "passed",
        "description": null,
        "status-author": "Harry",
        "step-statuses": [
          "passed",
          "passed"
        ]
      },
      "links": {
        "self": "/test-results/7"
      },
      "relationships": {
        "test-snapshot": {},
        "build": {},
        "execution-environment": {}
      }
    }
  ]
}

The available additional data are the following:

Field name Description
scenario The original scenario that produced the test
dataset The dataset that produced the test (if it comes from a scenario using a datatable)
last-result The details of the last test result of the test

show_passrate parameter can be added to include test pass rate in the response.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
test_snapshot_id The ID of the test you want to get

Request parameters

Parameter Description
include The data to include in the test JSON response. Fields must be comma-separated
show_passrate Add this parameter to get the test pass rate in the data

Delete a test

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

This endpoint delete a test.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
test_snapshot_id The ID of the test you want to get

Test folders

Get test folders of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
"data": [
        {
                     "type": "folder-snapshots",
                       "id": "1",
               "attributes": {
                 "created-at": "2017-09-15T12:59:08.328Z",
                 "updated-at": "2017-09-15T12:59:08.710Z",
                "last-author": "HarryP",
                       "name": "A Hogwarts project",
                "description": "",
                   "statuses": {
                       "passed_count": 0,
                       "failed_count": 0,
                       "retest_count": 0,
                    "undefined_count": 3,
                      "blocked_count": 0,
                      "skipped_count": 0,
                          "wip_count": 0
                },
                  "parent-id": null,
                "test-run-id": 1
            },
                    "links": {
                "self": "/folder-snapshots/1"
            },
            "relationships": {
                        "folder": {},
                      "children": {},
                "test-snapshots": {}
            }
        },
        {
                     "type": "folder-snapshots",
                       "id": "1",
               "attributes": {
                 "created-at": "2017-09-15T12:59:08.328Z",
                 "updated-at": "2017-09-15T12:59:08.710Z",
                "last-author": "HarryP",
                       "name": "The Philosopher's Stone",
                "description": "",
                   "statuses": {
                       "passed_count": 0,
                       "failed_count": 0,
                       "retest_count": 0,
                    "undefined_count": 3,
                      "blocked_count": 0,
                      "skipped_count": 0,
                          "wip_count": 0
                },
                  "parent-id": 1,
                "test-run-id": 1
            },
                    "links": {
                "self": "/folder-snapshots/1"
            },
            "relationships": {
                        "folder": {},
                      "children": {},
                "test-snapshots": {}
            }
        }
      ]
    }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test folders from
test_run_id The ID of the test run that contains the test folders you want

Get a test folder

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
"data": [
        {
                     "type": "folder-snapshots",
                       "id": "1",
               "attributes": {
                 "created-at": "2017-09-15T12:59:08.328Z",
                 "updated-at": "2017-09-15T12:59:08.710Z",
                "last-author": "HarryP",
                       "name": "A Hogwarts project",
                "description": "",
                   "statuses": {
                       "passed_count": 0,
                       "failed_count": 0,
                       "retest_count": 0,
                    "undefined_count": 3,
                      "blocked_count": 0,
                      "skipped_count": 0,
                          "wip_count": 0
                },
                  "parent-id": null,
                "test-run-id": 1
            },
                    "links": {
                "self": "/folder-snapshots/1"
            },
            "relationships": {
                        "folder": {},
                      "children": {},
                "test-snapshots": {}
            }
        }
      ]
    }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test folders from
test_run_id The ID of the test run that contains the test folders you want
folder_snapshot_id The ID of the test folder you want to get

Get a test folder additional data

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=<fields> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=<fields>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

The data you want to include in the response must be comma-separated

You can use the JSONAPI include syntax to fetch additional data about your tests.

The available additional data are the following:

Field name Description
folder The original folder that produced the test folder
children The subfolders of the test folder
test-snapshots The tests contained by the test folder
GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=folder HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=folder" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Get a test folder original scenario folder

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=children HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=children" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Get the subfolders of a test folder

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=test-snapshots HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/folder_snapshots/<folder_snapshot_id>?include=test-snapshots" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

Get the tests of a test folder

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test folders from
test_run_id The ID of the test run that contains the test folders you want
folder_snapshot_id The ID of the test folder you want to get

Request parameters

Parameter Description
include The data to include in the test JSON response. Fields must be comma-separated

Test execution

Getting started with test executions

Test execution results in CucumberStudio are organized in the following way:

The notion of execution environments is entirely optional. You can use them if you have several environments on which you want to execute your tests. If you do not wish to have specific environments, you can ignore them and work directly with builds at test run level.

The Builds section specifies all operations that can be performed without execution environments.

The Execution environments section specifies how to work with multiple environments.

Each entry in the Builds section has a warning if an execution environment ID is mandatory when working with multiple environments.

Add a test execution result

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "test-results",
    "attributes": {
      "status": "passed",
      "status-author": "Harry",
      "description": "All was well",
      "step-statuses": ["passed", "passed", "passed"]
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "test-results", "attributes": {"status": "passed", "status-author": "Harry", "description": "All was well", "step-statuses": ["passed", "passed", "passed"]}}}'

Newly created test result

{
  "data": {
    "type": "test-results",
    "id": "1",
    "attributes": {
      "created-at" : "2017-02-28T11:39:08.281Z",
      "updated-at" : "2017-02-28T11:39:08.281Z",
      "last-author" : "harry@example.org",
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "",
      "status-author": "Harry",
      "step-statuses": ["passed", "passed", "passed"]
    },
    "links": {
      "self": "/test-results/1"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": "1"
        }
      },
      "build": {
        "data": null
      }
    }
  },
  "included": [
    {
      "test-snapshot": "test data"
    }
  ]
}

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
test_snapshot_id The ID of the test whose you want add a test result to

Mandatory fields

Field Description
status (String) The result of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'.
status-author (String) The name of the author of the test execution
description (String) A comment about the test execution

Optional fields

Field Description
build (JSONAPI Relationship) The build containing your test execution result
execution-environment (JSONAPI Relationship) The execution environment containing your test execution result
step-statuses (String Array) The status for each individual step

If a build is provided, the test result will be created into that build.

If an execution environment is provided, the test result will be created into the current build of that execution environment

If step statuses are provided, anything different from 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', or 'undefined' will be interpreted as 'undefined'. If providing something else than a array of statuses, it will be interpreted as empty array, which means all step statuses are 'undefined'.

When setting step statuses on creation, they can match the steps of the scenario, or the steps of the test. The number of steps in each case can be different because a call to an actionword step can expand into multiple steps:. So the following rules apply:

For instance, if a scenario has two steps, and each one is a call to an actionword having 2 steps, then the scenario has 2 steps and the corresponding test has 4 steps. Here are the possibilities:

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "test-results",
    "attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
    "relationships": {
      "build": {
        "data": {
          "type": "build",
          "id": 1
        }
      }
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{
      "type": "test-results", "attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
      "relationships": {
        "build": {
          "data": {
            "type: "build",
            "id": 1
          }
        }
      }
    }'

Newly created test result

{
  "data": {
    "type": "test-results",
    "id": "1",
    "attributes": {
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "",
      "status-author": "Harry"
    },
    "links": {
      "self": "/test-results/1"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": "1"
        }
      },
      "build": {
        "data": {
          "type": "builds",
          "id": "1"
        }
      }
    }
  },
  "included": [
    {
      "type": "test-snapshots",
      "attributes": "test data"
    },

    {
      "type": "builds",
      "attributes": "build data"
    }
  ]
}
POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "test-results",
    "attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
    "relationships": {
      "execution-environment": {
        "data": {
          "type": "execution-environment",
          "id": 1
        }
      }
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{
      "type": "test-results", "attributes": {"status": "passed", "status-author": "Harry", "description": "All was well"},
      "relationships": {
        "execution-environment": {
          "data": {
            "type: "execution-environment",
            "id": 1
          }
        }
      }
    }'

Newly created test result

{
  "data": {
    "type": "test-results",
    "id": "1",
    "attributes": {
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "",
      "status-author": "Harry"
    },
    "links": {
      "self": "/test-results/1"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": "1"
        }
      },
      "build": {
        "data": {
          "type": "builds",
          "id": "1"
        }
      }
    }
  },
  "included": [
    {
      "type": "test-snapshots",
      "attributes": "test data"
    },

    {
      "type": "builds",
      "attributes": "build data"
    }
  ]
}

Update a test execution result

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "test-results",
    "id": <test_result_id>,
    "attributes": {
      "status": "passed",
      "status-author": "Jenkins",
      "description": "Automated jenkins job"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "test-results", "id": <test_result_id>, "attributes": {"status": "passed", "status-author": "Jenkins", "description": "Automated jenkins job"}}}'

Updated test result

{
  "data": {
    "type": "test-results",
    "id": "<test_result_id>",
    "attributes": {
      "created-at" : "2017-02-28T11:39:08.281Z",
      "updated-at" : "2017-02-28T11:39:08.281Z",
      "last-author" : "harry@example.org",
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "Automated jenkins job",
      "status-author": "Jenkins"
    },
    "links": {
      "self": "/test-results/<test_result_id>"
    },
    "relationships": {
      "test-snapshot": {},
      "build": {}
    }
  }
}

The API allows you to update a test result following the {json:api} way to patch resources.

Status, author and/or description may be updated specifying the status, status-author and/or description attributes of the resource.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
test_snapshot_id The ID of the test whose you want to update a test result to
test_result_id The ID of the test result you want to update

Attributes that may be updated

Field Description
status (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'.
status-author (String) The name of the author of the test execution
description (String) A comment about the test execution

List attachments of a given test execution result

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "attachments",
      "id": "1",
      "attributes": {
        "id": 1,
        "file-name": "my-attachment.jpg",
        "file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
        "file-size": 100
      },
      "links": {
        "self": "/attachments/1"
      }
    }
  ]
}

This endpoint list all the attachments of a given test execution result

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test execution result from
test_run_id The ID of the test run you want to retrieve the test execution result from
test_snapshot_id The ID of the test that you want to retrieve the test execution result from
test_result_id The ID of the test execution result you want

Get a given attachment of a given test execution result

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XGET -L "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --output my-attachment.jpg

This endpoint return the requested attachment of a given test execution result

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test execution result from
test_run_id The ID of the test run you want to retrieve the test execution result from
test_snapshot_id The ID of the test that you want to retrieve the test execution result from
test_result_id The ID of the test execution result you want

Create an attachment to a given test execution result

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint create an attachment to a given test execution result

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test execution result from
test_run_id The ID of the test run you want to retrieve the test execution result from
test_snapshot_id The ID of the test that you want to retrieve the test execution result from
test_result_id The ID of the test execution result you want

Update an attachment to a given test run

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
Content-Disposition: form-data; name="file"; filename="my-attachment.jpg"

(data)
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --form 'file=@./my-attachment.jpg'
{
  "data": {
    "type": "attachments",
    "id": "1",
    "attributes": {
      "id": 1,
      "file-name": "my-attachment.jpg",
      "file-url": "/api/projects/1/test_runs/1/test_snapshots/1/test_results/1/attachments/1",
      "file-size": 100
    },
    "links": {
      "self": "/attachments/1"
    }
  }
}

This endpoint update the attachment to a given test execution result

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test execution result from
test_run_id The ID of the test run you want to retrieve the test execution result from
test_snapshot_id The ID of the test that you want to retrieve the test execution result from
test_result_id The ID of the test execution result you want
attachment_id The ID of the target attachment

Delete an attachment to a given test execution result

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results/<test_result_id>/attachments/<attachment_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
{}

This endpoint delete a given attachment of a test execution result

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the test execution result from
test_run_id The ID of the test run you want to retrieve the test execution result from
test_snapshot_id The ID of the test that you want to retrieve the test execution result from
test_result_id The ID of the test execution result you want
attachment_id The ID of the target attachment

Builds

What's a build?

A build is a way to group the execution results of the tests contained in a CucumberStudio test run.

You can find more details on test executions and builds in the Test execution introduction section.

List builds of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "builds",
      "id": "1",
      "attributes": {
        "name": "Build 1",
        "created-at": "2017-06-13T08:15:38.607Z",
        "test-run-id": 1,
        "is-running": false,
        "closed-at": "2017-06-16T09:13:48.737Z"
      },
      "links": {
        "self": "/builds/1"
      }
    },
    {
      "type": "builds",
      "id": "2",
      "attributes": {
        "name": "Build 2",
        "created-at": "2017-06-13T08:15:38.607Z",
        "test-run-id": 1,
        "is-running": true,
        "closed-at": null
      },
      "links": {
        "self": "/builds/2"
      }
    }
  ]
}

This endpoint retrieves all builds of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project that contains the requested test run
test_run_id The ID of the test run you want to retrieve the builds from

Create a new build in a test run

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "attributes": {
      "name": "Build 1"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds" \
    -XPOST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": { "name": "Build 1"} } }'
  {
    "data": {
      "type": "builds",
      "id": "3",
      "attributes": {
        "name": "Build 3",
        "created-at": "now!",
        "test-run-id": 1,
        "is_running": true,
        "closed_at": null
      },
      "links": {
        "self": "/builds/3"
      }
    }
  }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you are executing
Parameter Description
name The name of the build. It should not be empty and uniq

Update a build

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "builds",
    "id": <build_id>,
    "attributes": {
      "name": "Build 1"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" \
    -XPOST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"type": "builds", "id": <build_id>, "attributes": { "name": "Build 1"} } }'
  {
    "data": {
      "type": "builds",
      "id": "3",
      "attributes": {
        "name": "Build 1",
        "created-at": "...",
        "test-run-id": 1,
        "is_running": true,
        "closed_at": null
      },
      "links": {
        "self": "/builds/3"
      }
    }
  }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you are executing
build_id The ID of the build you want to update
Parameter Description
name The new name of the build.

Get a specific build of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "name": "Build 1",
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    }
  },
  "included": []
}

This endpoint retrieves a specific build of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
test_run_id The ID of the test run you want to retrieve the build from

Get test execution results of a build

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>?include=test-results HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>?include=test-results" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "name": "Build 1",
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "execution-environment-id": 1,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    },
    "relationships": {
      "test-results": {
        "data": [
          {
            "type": "test-results",
            "id": "1"
          },
          {
            "type": "test-results",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "test-results",
      "id": "1",
      "attributes": {
        "status": "passed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "",
        "status-author": "Jenkins",
        "step-statuses": [
          "passed",
          "passed",
          "passed"
        ],
        "test-snapshot-id": 1,
        "execution-environment-id": 1
      },
      "links": {
        "self": "/test-results/1"
      }
    },
    {
      "type": "test-results",
      "id": "2",
      "attributes": {
        "status": "failed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "Error on line 42",
        "status-author": "Jenkins",
        "step-statuses": [],
        "test-snapshot-id": 2,
        "execution-environment-id": 1
      },
      "links": {
        "self": "/test-results/2"
      }
    }
  ]
}

Use the JSONAPI include syntax to fetch the test execution results of your build.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you want to retrieve the build from

Get the current build of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "name": "Build 1",
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "execution-environment-id": 29,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    }
  },
  "included": []
}

This endpoint retrieves the current build of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you want to retrieve the build from

Get test execution results of the current build of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current?include=test-results" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/current?include=test-results" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "name": "Build 1",
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "execution-environment-id": 29,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    },
    "relationships": {
      "test-results": {
        "data": [
          {
            "type": "test-results",
            "id": "1"
          },
          {
            "type": "test-results",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "test-results",
      "id": "1",
      "attributes": {
        "status": "passed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "",
        "status-author": "Jenkins",
        "step-statuses": [
          "passed",
          "passed",
          "passed"
        ],
        "test-snapshot-id": 1,
        "execution-environment-id": 29,
      },
      "links": {
        "self": "/test-results/1"
      }
    },
    {
      "type": "test-results",
      "id": "2",
      "attributes": {
        "status": "failed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "Error on line 42",
        "status-author": "Jenkins",
        "step-statuses": [],
        "test-snapshot-id": 2,
        "execution-environment-id": 29,
      },
      "links": {
        "self": "/test-results/2"
      }
    }
  ]
}

Use the JSONAPI include syntax to fetch the test execution results of the current build of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you want to retrieve the build from

Add a test execution result to a build

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>

{
  "data": {
    "type": "test-results",
    "attributes": {
      "status": "passed",
      "status-author": "Harry",
      "description": "All was well"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": 1
        }
      }
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/test_snapshots/<test_snapshot_id>/test_results" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{
      "data": {
        "type": "test-results",
        "attributes": {
          "status": "passed",
          "status-author": "Harry",
          "description": "All was well"
        },
        "relationships": {
          "test-snapshot": {
            "data": {
              "type": "test-snapshots",
              "id": 1
            }
          }
        }
      }
    }'

Newly created test result

{
  "data": {
    "type": "test-results",
    "id": "1",
    "attributes": {
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "",
      "status-author": "Harry"
    },
    "links": {
      "self": "/test-results/1"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": "1"
        },
      },
      "build": {
        "data": {
          "type": "builds",
          "id": "1"
        }
      }
    },
    "included": [
      {
        "type": "test-snapshots",
        "attributes": "test data"
      },

      {
        "type": "builds",
        "attributes": "build data"
      }
    ]
  }
}

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
build_id The ID of the build you want add a test result to

Mandatory fields

Field Description
status (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'.
status-author (String) The name of the author of the test execution
description (String) A comment about the test execution
test-snapshot (JSONAPI relationship) The executed test

Close a build

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>/close" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/builds/<build_id>/close" \
    -XPOST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{}'

The closed build

  {
    "data": {
      "type": "builds",
      "id": "3",
      "attributes": {
        "name": "Build 3",
        "created-at": "2017-06-13T08:15:38.607Z",
        "test-run-id": 1,
        "is-running": false,
        "closed-at": "2017-06-16T09:13:48.737Z"
      },
      "links": {
        "self": "/builds/3"
      },
      "relationships": {
        "test-results": {}
      }
    }
  }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you are executing
build_id The ID of the build you want to close

Execution environments

What's an execution environment?

An execution environment is a way to group several builds by in a CucumberStudio test run.

You can find more details on test executions and execution environments in the Test execution introduction section.

List execution environments of a test run

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "execution-environments",
      "id": "1",
      "attributes": {
        "name": "Default",
        "test-run-id": 1,
        "created-at": "2017-06-13T08:15:38.607Z",
        "updated-at": "2018-09-09T10:48:48.685Z"
      },
      "links": {
        "self": "/execution-environments/1"
      }
    },
    {
      "type": "execution-environments",
      "id": "2",
      "attributes": {
        "name": "Environment 1",
        "test-run-id": 1,
        "created-at": "2017-06-13T08:15:38.607Z",
        "updated-at": "2018-09-09T10:48:48.685Z"
      },
      "links": {
        "self": "/execution-environments/2"
      }
    }
  ]
}

This endpoint retrieves all execution environments of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project that contains the requested test run
test_run_id The ID of the test run you want to retrieve the builds from

List builds of an execution environment

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": [
    {
      "type": "builds",
      "id": "1",
      "attributes": {
        "created-at": "2017-06-13T08:15:38.607Z",
        "test-run-id": 1,
        "execution-environment-id": 1,
        "is-running": true,
        "closed-at": "2017-06-16T09:13:48.737Z"
      },
      "links": {
        "self": "/builds/1"
      }
    },
    {
      "type": "builds",
      "id": "2",
      "attributes": {
        "created-at": "2017-06-13T08:15:38.607Z",
        "test-run-id": 1,
        "execution-environment-id": 1,
        "is-running": false,
        "closed-at": null
      },
      "links": {
        "self": "/builds/2"
      }
    }
  ]
}

This endpoint retrieves all builds of a given execution environment.

URL Parameters

Parameter Description
project_id The ID of the project that contains the requested test run
test_run_id The ID of the test run that contains the requested execution environment
execution_environment_id The ID of the execution environment you want to retreive the builds from

Create a new execution environment

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "attributes": {
      "name": "Execution environment 1"
    }
  }
}
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments" \
    -XPOST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{"data": {"attributes": { "name": "Execution environment 1"} } }'

A new execution environment

  {
    "data": {
      "type": "execution-environments",
      "id": "1",
      "attributes": {
        "name": "Execution environment 1",
        "test-run-id": 29,
        "created-at": "2019-02-22T08:59:38.603Z",
        "updated-at": "2019-02-22T08:59:38.603Z"
      },
      "links": {
        "self": "/execution-environments/1"
      }
    }
  }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the folders from
test_run_id The ID of the test run you are executing

Mandatory fields

Parameter Description
name The name of the execution environment. It should not be empty and uniq

Update an execution environment name

PATCH https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environmnent_id> HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "execution-environments",
    "id": <execution_environment_id>,
    "attributes": {
      "name": "Android"
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPATCH "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environmnent_id>" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data $'{ "data": { "type": "execution-environments", "id": <execution_environment_id>, "attributes": { "name": "Android" } } }'
{
  "data":
    {
      "type": "execution-environments",
      "id": "1",
      "attributes": {
        "created-at" : "2017-02-28T11:39:08.281Z",
        "updated-at" : "2017-02-28T11:39:08.281Z",
        "name": "Android",
        "test_run_id" : 1
      },
      "links": {
        "self": "/execution-environments/1"
      }
    }
}

This endpoint updates the name of an execution environment for a test run and a given project.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the action word from
test_run_id The ID of the test_run that the execution environment belongs to
execution_environment_id The ID of the execution environment you want to update the name

Delete an execution environment

DELETE https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environments_id> HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XDELETE "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environments_id>" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'

This endpoint delete an execution environment.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the scenario from
test_run_id The ID of the test_run that the execution environment belongs to
execution_environment_id The ID of the execution environment to delete

Create a new build in a specific execution environment

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds" \
    -XPOST \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{}'

A new build

  {
    "data": {
      "type": "builds",
      "id": "3",
      "attributes": {
        "created-at": "now!",
        "test-run-id": 1,
        "execution-environment-id": 29,
        "is_running": true,
        "closed_at": null
      },
      "links": {
        "self": "/builds/3"
      }
    }
  }

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you are executing
execution_environment_id The ID of the execution environment for your new build

Get the current build of an execution environment

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "execution-environment-id": 29,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    }
  },
  "included": []
}

This endpoint retrieves the current build of a given test run.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you want to retrieve the build from
execution_environment_id The ID of the execution environment you want to retrieve the build from

Get test execution results of the current build of an execution environment

GET https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current?include=test-results" HTTP/1.1
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/builds/current?include=test-results" \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>'
{
  "data": {
    "type": "builds",
    "id": "1",
    "attributes": {
      "created-at": "2017-06-13T08:15:38.607Z",
      "test-run-id": 1,
      "execution-environment-id": 29,
      "is-running": false,
      "closed-at": "2017-06-16T09:13:48.737Z"
    },
    "links": {
      "self": "/builds/1"
    },
    "relationships": {
      "test-results": {
        "data": [
          {
            "type": "test-results",
            "id": "1"
          },
          {
            "type": "test-results",
            "id": "2"
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "test-results",
      "id": "1",
      "attributes": {
        "status": "passed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "",
        "status-author": "Jenkins",
        "step-statuses": [
          "passed",
          "passed",
          "passed"
        ],
        "test-snapshot-id": 1,
        "execution-environment-id": 29
      },
      "links": {
        "self": "/test-results/1"
      }
    },
    {
      "type": "test-results",
      "id": "2",
      "attributes": {
        "status": "failed",
        "created-at": "1980-07-01T12:00:00.350Z",
        "description": "Error on line 42",
        "status-author": "Jenkins",
        "step-statuses": [],
        "test-snapshot-id": 2,
        "execution-environment-id": 29
      },
      "links": {
        "self": "/test-results/2"
      }
    }
  ]
}

Use the JSONAPI include syntax to fetch the test execution results of the current build of a given execution environment.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the build from
test_run_id The ID of the test run you want to retrieve the build from
execution_environment_id The ID of the execution environment you want to retrieve the build from

Add a test execution result to the current build of an execution environment

POST https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/test_results HTTP/1.1
Content-Type: application/json; charset=utf-8
Accept: application/vnd.api+json; version=1
access-token: <your access token>
client: <your client id>
uid: <your uid>


{
  "data": {
    "type": "test-results",
    "attributes": {
      "status": "passed",
      "status-author": "Harry",
      "description": "All was well"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": 1
        }
      }
    }
  }
}
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
curl -XPOST "https://studio.cucumber.io/api/projects/<project_id>/test_runs/<test_run_id>/execution_environments/<execution_environment_id>/test_results" \
    -H 'Content-Type: application/json' \
    -H 'accept: application/vnd.api+json; version=1' \
    -H 'access-token: <your access token>' \
    -H 'uid: <your uid>' \
    -H 'client: <your client id>' \
    --data '{
      "data": {
        "type": "test-results",
        "attributes": {
          "status": "passed",
          "status-author": "Harry",
          "description": "All was well"
        },
        "relationships": {
          "test-snapshot": {
            "data": {
              "type": "test-snapshots",
              "id": 1
            }
          }
        }
      }
    }'

Newly created test result

{
  "data": {
    "type": "test-results",
    "id": "1",
    "attributes": {
      "status": "passed",
      "created-at": "Couple of miliseconds ago",
      "description": "",
      "status-author": "Harry"
    },
    "links": {
      "self": "/test-results/1"
    },
    "relationships": {
      "test-snapshot": {
        "data": {
          "type": "test-snapshots",
          "id": "1"
        },
      }
      "build": {
        "data": {
          "type": "builds",
          "id": "1"
        }
      }
    }
  },
  "included": [
    {
      "type": "test-snapshots",
      "attributes": "test data"
    },

    {
      "type": "builds",
      "attributes": "build data"
    }
  ]
}

This endpoint will create a test result in the current build of the specified execution environment.

URL Parameters

Parameter Description
project_id The ID of the project you want to retrieve the tests from
test_run_id The ID of the test run that contains the test you want
execution_environment_id The ID of the execution environment you want add a test result to

Mandatory fields

Field Description
status (String) The status of the test execution. Possible values are 'passed', 'failed', 'wip', 'retest', 'blocked', 'skipped', 'undefined'.
status-author (String) The name of the author of the test execution
description (String) A comment about the test execution
test-snapshot (JSONAPI relationship) The executed test

Deprecations

Test status

Thanks to the new execution environment feature, a test is now executed on an execution environment. Consequently the status attribute of a test does not mean anything without an execution environment.

To get a test execution status, please refer Get test execution results of the current build of an execution environment

Note that the status attribute will be removed on 28 february 2020.