# Participation Requests

Participation requests allow you to add or remove probes from an existing measurement. Its structure is similar to the probes object that is used in the creation request for a measurement. The main difference is that a participation-request object holds an action field, which can have a value remove or add.

The probes object included in the creation of the measurement is also present in the Measurement API response as a participation-request object with an action value of add.

The participation requests for a measurement can be obtained in two different ways: by querying the measurements resource with a query parameter to include the participation requests and by querying the participation requests resource directly.

Creating a new participation request for an existing measurement can only be done by making a POST request to the measurements resource directly.

# Getting information about participation requests

You can include the participation-requests array in a Measurement API request:

Note that you will have to replace the key search parameter in the URI with the UUID of a key that has been appointed the right permissions for this operation.

GET /api/v2/measurements/2000000/?optional_fields=participation_requests

As you can see the participation-request has its own ID. You can also use that to query the Participation-requests API directly:

GET /api/v2/participation-requests/2340391/?optional_fields=participation_requests

# Creating a participation change request

Here's a simple example that adds one probe from Russia to a running measurement:

curl \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-H "Authorization: Key YOUR-KEY-HERE" \
	-X POST \
	-d '[{"action": "add", "requested" :1, "type": "country", "value": "RU"}]' \
	https://atlas.ripe.net/api/v2/measurements/10000076/participation-requests/

If you added a key with the right permissions you will get the following response:

{
  "request_ids": [35878]
}

CAUTION

Please note that the request is actually made by making a POST request to the URI of the measurement involved and then appending /participation-requests/, e.g. https://atlas.ripe.net/api/v2/measurements/1000076/participation-requests/

On success it returns the data structure with the list of IDs of change requests created.

It is possible to create multiple changes in a single request

[
        {
            "action": "add",
            "requested": 1,
            "type": "country",
            "value": "CA"
        },
        {
            "action": "remove",
            "requested": 1,
            "type": "probes",
            "value": "4,103"
        },
        ....
    ]

Please note that removal requests are only possible with type="probes". The field "value" has to be assigned a list of probes that are supposed to be removed.

Like the probes section of the measurement creation request you can also specify a tags_include or tags_exclude field to further constrain the probes by tag. Read more about it in the probes section of the measurement creation part of this manual.

Last Updated: Tuesday 21 May 2024