How to update or clear the testing reports filter via API

The PUT /api/v1/tests/reports/filter endpoint updates or clears the saved testing reports filter. The request body can include active, a date range, groupByName, testIds, departments and jobTitles; if {} or a body with only null values or empty collections is sent, the server clears the filter. Access requires a Bearer token with the tests.write scope.

Which endpoint is used?

Use PUT /api/v1/tests/reports/filter. The endpoint changes the saved testing reports filter for the user context from the Bearer token.

What is this API endpoint used for?

This endpoint is used to manage the filter applied to testing report search and export. It is used before retrieving a report list or creating an Excel export.

What prerequisites are required before sending the request?

• A Bearer token is required.

• The token must include the tests.write scope.

Which parameters must be sent in the request?

Headers

Path parameters

Path parameters are absent.

Query parameters

Query parameters are absent.

Request body

curl example

Example request to update the filter:

curl -X PUT 'https://smartway.pro/api/v1/tests/reports/filter' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "active": true,
    "startDate": "2026-03-01",
    "endDate": "2026-03-10",
    "groupByName": true,
    "testIds": [5, 200001],
    "departments": ["Sales"],
    "jobTitles": ["Manager"]
  }'

Example request to clear the filter:

curl -X PUT 'https://smartway.pro/api/v1/tests/reports/filter' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

What response does the API return?

A successful request returns 200 OK and a PublicTestReportFilterResponse object with the current filter state.

{
  "active": true,
  "startDate": "2026-03-01",
  "endDate": "2026-03-10",
  "groupByName": true,
  "testIds": [5, 200001],
  "departments": ["Sales"],
  "jobTitles": ["Manager"]
}

What do the API response fields mean?

What happens under the hood?

• The filter is bound to userKey, which is taken from the Bearer token subject.

• For a company API key, userKey has the format company-api-key:{companyId}.

• Filter updates are not bound to a specific active key ID.

• The external client does not send idUser.

• If an empty object {} or a body with only null values or empty collections is sent, the server clears the filter.

• If endDate < startDate, the API returns 400 Bad Request.

• Access requires the tests.write scope.

Which edge cases should be considered?

Which errors can the API return?

How to use the result in subsequent API requests?

After the filter is updated or cleared, subsequent testing report search and export requests are executed with the current filter applied.

Example report search after updating the filter:

curl -X POST 'https://smartway.pro/api/v1/tests/reports/search' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Which mistakes should integrators avoid?

• Sending idUser in the request body or query string.

• Sending endDate earlier than startDate.

• Expecting the filter to be bound to a specific active key ID.

• Forgetting that an empty {} clears the filter.

• Calling the endpoint without the tests.write scope.

FAQ

How do I clear the filter?

Send an empty JSON object {} or a body with only null values or empty collections.

What happens if endDate < startDate?

The API returns 400 Bad Request.

Do I need to send idUser?

No. The external client does not send idUser.

Which scope is required?

The tests.write scope is required.

What is the filter bound to?

The filter is bound to userKey, which is taken from the Bearer token subject.