Build and send a single request

Set the method, URL, headers, body and variables, send it and save it.

In short

A single request is one call to an API, built from a method, a URL, headers, a body and sign-in. Send it and read the answer. Signed in, you can save it into a project so your team can run it again.

Before you start

• Who: anyone can send a single request, even without an account. Saving into a project needs you to be signed in and to hold Edit on that project.
• Plan: Every request {{brand}} sends for you counts toward your plan's request allowance (see /help/settings/plan-limits). Everyone can start at most 30 sends a minute.
• First: nothing. For a saved request, make sure the environment is the one you mean before you send a write method.

Steps

1. Choose the method the API expects.
2. Enter the URL. Query values such as ?page=2 go at the end; the "Params" tab lists them one per row, and editing either updates the other.
3. Add "Headers" such as Content-Type or Accept.
4. Open "Auth" if the API needs a token, user name or API key.
5. For POST, PUT or PATCH, open "Body" and enter the content.
6. Press "Send".
7. Signed in, save it into a project with a clear name, a test group and a description.

Result: the answer shows below; a saved request appears in the project, and every send is listed under your recent sends.

Check the environment A request can create, change or delete real data. Check the URL before you send a write method to a production system.

Headers and body

• A header name may appear more than once, and a row with an empty name is ignored.
• An explicit Authorization header always wins over the Auth tab.
• Host, Content-Length, Connection and other connection headers are left out when you send, because a wrong Content-Length makes the call hang.
• Uploaded files belong to the project and stay with the saved request. In the Single request scratchpad the body is plain text.

Variables

Write {{name}} in the URL, headers, body or authentication and it is replaced when you send. In the scratchpad a Variables row appears for each name so you can type a value for this send. A saved request takes values from the active environment first, then from its own setup variables. A secret value is hidden in results and exports. See /help/api-testing/variables.

Good to know

• Name a saved request the way your team says it (Create Invoice, not POST /v2/inv). Leave the group empty and it goes into General.
• Click a row under your recent sends to load it back.
• Your plan limits how many requests you send an hour and a day, and everyone can start at most 30 sends a minute. See /help/settings/plan-limits.
• What happens next: a saved request appears in the project's board; a quick request does not. Any send is listed under your recent sends.

Keep tokens out of saved headers A token typed into a quick request stays in this browser tab and is not saved. A token typed into a saved request's header becomes project content that members may see. Use an authentication profile instead.

If something goes wrong

• The call hangs: check for a wrong Content-Length or a server that does not answer; {{brand}} drops connection headers for you.
• "Not sent": the address is local or private. See /help/api-testing/send-to-localhost.
• A plan limit message: you sent your plan's requests for the hour or day. Wait for the reset, or change the plan.

Related

• /help/api-testing/request-editor-and-checks
• /help/api-testing/variables
• /help/api-testing/authentication-profiles