Showcase your public APIs with Postman Notebooks

With Postman Notebooks, you showcase your public APIs with interactive articles. Notebooks combine your documentation, code, and APIs in one place, where you guide your API consumers to their first 200 OK response.

For example, document the steps to get an API key. Then, ask your readers to add the API key to your notebook and invite them to send their first request. Postman will return a response to the same notebook. You can do something similar for real-world use cases and showcase your API's capabilities to your API consumers.

Your notebooks are linked to your public profile. Before you get started, make your profile public. Then, you can view your notebooks and create new ones.

View your notebooks

To view your notebooks, do the following:

1. If you haven't already, make your profile public.
2. From the Postman header, click your profile picture. Then, click View Profile.
3. Click View public profile.
4. Open the Notebooks tab.

From the Notebooks tab, you can create a new notebook or open an existing one.

Create a notebook

Open your notebooks and click New draft.

Draft your notebook

Start by naming your notebook and adding text to it. Postman saves as you type. You can format text by selecting it or using the slash command, and also use the slash command to add input blocks and add interactive blocks.

You can preview your draft at any time. To preview, click Preview. To return to the editor, click Edit Notebook.

Important: Postman scans your notebooks for sensitive data. If it detects any, it replaces them with placeholders. To learn more, see Postman Secret Scanner.

Format your notebook

You can format your notebook with text and block styles. Use text styles to bold, italicize, and strike through text. Use block styles to format headings, lists, quotes, and code blocks.

To format text, select it. Postman displays a text menu. Then, select one of the options, such as Bold.

To format a block of text, place your cursor at the start of the block and type a forward slash ("/"). Postman displays a block menu. Then, select one of the options, such as Quote.

You can also format your notebook with Markdown and keyboard shortcuts. For example, to use Markdown to bold the word "Postman", type "**Postman**". To use a keyboard shortcut to bold the word "Postman API Network", select the text and press Command + B or Ctrl + B.

Add an input block to your notebook

You can add variables and reference them elsewhere in your notebook to create an interactive experience. For example, you can add an input block for your API consumer's email address and use a request block to send them a welcome message.

To add an input block to your notebook, do the following:

1. Open your notebook or create a new one.

2. Place your cursor where you want to add the input block. Then, type a forward slash ("/"). Postman displays a block menu.

3. Choose an input block type:

   • Text - Choose for strings, such as names or email addresses.
   • Number - Choose for numbers, such as integers or floats.
   • Secret - Choose for sensitive values, such as API keys or tokens.

4. Name your input block.

5. (Optional) Define a default value.

You can reference your input block by name. For example, if you name your input block "email", you can reference it in another input block or a request block with the syntax {{email}}. Or you can reference it in a code runner block with the syntax $email.

Add interactive blocks to your notebook

With interactive blocks, API consumers can send requests and run code, all within your notebook. For example, add an input block for your API consumer's API key. Then, add a request block and connect it to one of your API requests. Someone reading your notebook can use these blocks and your documentation to send their first 200 OK response.

Add a request block to your notebook

To add a request block to your notebook, do the following:

1. Open your notebook or create a new one.
2. Place your cursor where you want to add the request block. Then, type a forward slash ("/"). Postman displays a block menu.
3. Choose Request Block.
4. Name your request block.
5. Search for your public request or paste its URL or UUID. Then, select it. Postman displays the request, a button to send the request, and any other inputs you or your API consumer may need to define.
6. If necessary, define the input values.
7. (Optional) Define an override.
8. Click Send.

You can reference your request block by name. For example, if you name your request block "user", you can reference its response in another request block with the syntax {{user}}. Or you can reference it in a code runner block with the syntax $user.

You can also use dot notation to reference data within the response. For example, in another request block, you can reference the user's first email with the syntax {{user.emails.0}}. Or in a code runner block, you can reference the same value with the syntax $user.emails[0].

Add a code runner block to your notebook

To add a code runner block to your notebook, do the following:

1. Open your notebook or create a new one.
2. Place your cursor where you want to add the code runner block. Then, type a forward slash ("/"). Postman displays a block menu.
3. Choose Code Runner Block.
4. Name your code runner block.
5. Write your code.
6. Click Run.

Publish your notebook

Before you publish your notebook, open your draft and click Preview. Walk yourself through the steps you outlined in your notebook. Then, invite others on your team to do the same.

When you're ready to publish your notebook, open your draft and click Publish.