Build a request and its checks

Fill a request in, say what a pass means with checks, and keep values for the next request.

In short

A saved request opens in an editor where you set the address, method, params, headers, body and sign-in. Checks say what a pass means - a status, a header, a value in the body, a time, a schema - so a 200 with the wrong body still fails. "Keep a value" passes a value on to the next request.

Before you start

• Who: changing a saved request or its checks needs Edit on the project. At Run you can send a saved request only as saved. View reads.
• Plan: every plan. Every request {{brand}} sends for you counts toward your plan's request allowance (see /help/settings/plan-limits).
• First: save the request in a project, then send it once so you can build checks from a real answer.

Steps

1. Open a saved request. The editor opens beside the list.
2. Type the address, pick the method, then use the tabs for params, headers, body and sign-in. Type {{ to pick a variable.
3. Press "Send", or Ctrl or Cmd with Enter. "Save" keeps your changes.

1. Open "Checks" on the request and press "Add check".
2. Choose what it looks at (see the table) and what you expect.
3. Read pass or fail against the last answer as you fill it in, and save.

1. Under "Keep for the next request", press "Keep a value".
2. Name the variable and say where to read it: the body (a JSONPath) or a header.

Result: after the request runs, its checks pass or fail, and later requests and suite steps can use the kept value as {{name}}.

Start from an answer Send the request once, then click a value in the answer. You can turn it into a check or keep it as a variable without writing anything by hand.

Checks: what a pass means

Every check runs even after one fails, so a request with five checks says which of the five broke. An expected value can use a variable: "$.id equals {{orderId}}" compares the id with the value {{orderId}} has when the request runs.

Every item or any item

A path with [*] or a filter reaches many items - for example $.items[*].price. Which items must pass is your choice:

If you leave it alone, a path with [*] or a filter means every item, and any other path checks its one value. A path that reaches nothing fails, except when the check is "does not exist".

Check the shape with a JSON Schema

Choose "Matches a JSON schema" to check that the body has the right fields and types, not just one value. Paste a JSON Schema, or press "Start from the last answer" to write one from the answer's shape and then tighten it. A failed schema check lists the first places that do not match, each with its path and the reason. A request imported from OpenAPI that documents a response gets a schema check for free.

Redirects, certificates and cookies

• "Follow redirects" goes on to where a 3xx answer points, one hop at a time, and shows each hop. Credentials stay with their own site. It is off until you turn it on.
• "Accept certificates that cannot be verified" is a setting of an environment, for a test server with a self-signed certificate. Never turn it on for Production.
• In a suite run the cookies one step receives are sent with the steps after it, and are gone when the run ends.
• "Order in a project run" decides which request runs first when you run a whole project: lower numbers run first.

GraphQL

Choose GraphQL as the body. Write the query, add variables as a JSON object such as {"id": 1}, and give an operation name only when the query holds more than one. Press "Load schema" to browse queries, mutations and subscriptions; it counts as one request. Then suggestions name only the fields or arguments that fit where you type, and the query is checked as you write it: each problem a server would refuse - a field or argument that does not exist, a required argument or variable value left out, braces missing after an object - is listed with its line, and a click goes to it. Under "Build", tick the fields you want and press "Use this query": the query is written for you, with a variable for each required argument. If the server says nothing, introspection may be turned off.

Copy a request as code

Open the request's "Code" tab, or "Code snippets" in its menu, and pick a language: cURL, JavaScript (fetch or axios), Python, C#, Go, Java or PHP. Variables stay as placeholders, so a secret is never written out - fill them in before you run it.

Good to know

• Under the address, {{brand}} shows where the request will really go, with each variable filled in. A secret is shown by its name only, and a variable nothing defines yet is marked before you send.
• A body can be JSON, text, a form, a file upload or GraphQL.
• A variable whose name looks like a secret, such as token, is shown hidden.
• A schema can be up to 32,000 characters. A schema that refers to another address is not downloaded - that check fails instead.
• A saved request opens in a sheet with the tabs "Request", "Used in suites", "Notes" (saved examples and comments), "History" and "Related". Any tab past the fourth waits behind "More".
• A link from a failed-monitor email, a board card or Home opens a single run. It shows what was sent and what came back, with secrets and personal data masked. It also shows the checks that failed, how it differs from the last pass, and how long its evidence is kept.
• What happens next: checks run every time the request runs, in a suite, a monitor or a project run, and their verdict decides pass or fail.

If something goes wrong

• A request with status 200 is red: a check failed. Open the run to see expected beside seen.
• A path check fails with "reaches nothing": the path does not match the body. Click the value in the answer to write the path for you.
• A schema check fails on a reference: schemas never fetch other addresses. Paste the referenced part in.
• "Load schema" returns nothing: the server has introspection turned off.

Related

• /help/api-testing/variables
• /help/api-testing/suite-checks
• /help/api-testing/time-bands