docs: apply Snyk writing-style skill to Snyk API & Web pages by TashaTBaker · Pull Request #1357 · snyk/user-docs

TashaTBaker · 2026-06-17T11:47:30Z

Apply the Snyk documentation writing-style rules across the snyk-api-web page and all child pages (114 files updated).

Consistent changes:

Passive to active voice, naming the actor
Remove weakening modals (may/should/might) and filler
Fix capability phrasing ("allows you to" -> "you can"/"lets you")
Terminology: after/navigate to/visit/log in/check box/Select vs Click; vulnerability (security) vs issue (licensing)
Sentence-case headings; bold UI labels and status values; unbold list lead-ins and emphasis; remove contractions and semicolons
Product name "Snyk API & Web" on first reference, then "Snyk"

Frontmatter, GitBook components, links, and technical literals unchanged.

Apply the Snyk documentation writing-style rules across the snyk-api-web page and all child pages (114 files updated). Consistent changes: - Passive to active voice, naming the actor - Remove weakening modals (may/should/might) and filler - Fix capability phrasing ("allows you to" -> "you can"/"lets you") - Terminology: after/navigate to/visit/log in/check box/Select vs Click; vulnerability (security) vs issue (licensing) - Sentence-case headings; bold UI labels and status values; unbold list lead-ins and emphasis; remove contractions and semicolons - Product name "Snyk API & Web" on first reference, then "Snyk" Frontmatter, GitBook components, links, and technical literals unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

snyk-io · 2026-06-17T11:47:58Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

# Conflicts: # scan-fix-and-prevent/scan-with-snyk/snyk-api-web/review-and-fix/review-pending-findings.md

TashaTBaker · 2026-06-17T12:15:36Z

 If your target requires requests to be encrypted, configure message level encryption in the Encryption tab.

-1. In Snyk API & Web, navigate to the **Targets** page.
+1. In Snyk, navigate to the **Targets** page.


I would either remove "In Snyk" or specify where in the UI you are e.g. Homepage

TashaTBaker · 2026-06-17T12:19:29Z

 3. Click **Add**.

-Snyk API & Web performs all necessary conversions, creates the target, and you can scan your RAML API.
+Snyk performs all necessary conversions and creates the target, and you can then scan your RAML API.


This sentence is a bit of a mouthful. I would amend to "Snyk performs all necessary conversions, creates the target, then enables you to scan your RAML API."

TashaTBaker · 2026-06-17T12:29:55Z

+Configure alternative OTP two-factor authentication for your target before proceeding. Visit [Configure two-factor authentication (2FA)](configure-two-factor-authentication.md) for setup instructions.

-You will need the **UNIQUE 2FA CONFIGURATION URL** from your target's Authentication settings.
+You need the **UNIQUE 2FA CONFIGURATION URL** from the Authentication settings of your target.


Is there meant to be a URL here?

It would be nice if you could provide an example of a UNIQUE 2FA CONFIGURATION URL, and more specific instructions on where to find it. I see that field in the screenshots in the Configure alternative OTP , but not in the TOTP section. Does it only apply when using alternative OTPs? If so it would be good to note that here.

TashaTBaker · 2026-06-17T14:03:11Z

 ### Configure OTP with Login Sequence

-To use the OTP code in a login sequence, record a new login sequence with 2FA and update the target login sequence. Visit [Configure login sequence authentication](configure-login-sequence.md) for instructions. During the recording, take note of the OTP code that you used because you will need it for the configuration.
+To use the OTP code in a login sequence, record a new login sequence with 2FA and update the target login sequence. Visit [Configure login sequence authentication](configure-login-sequence.md) for instructions. During the recording, take note of the OTP code that you used because you need it for the configuration.


The convention is "For instructions, visit..."

TashaTBaker · 2026-06-17T14:07:04Z

 * **Action** - Select **Allow**.
-* **Zone** - From the available options, select **This website** if you want to apply the rule only to the current zone. Alternatively, select **All websites in account** if you want the rule to be created in all zones of your Cloudflare account.
-* **Notes** - This is optional, but you can provide text identifying the rule. For example, "Snyk API & Web IP".
+* **Zone** - To apply the rule only to the current zone, select **This website**. To create the rule in all zones of your Cloudflare account, select **All websites in account**.


: instead of - in lists

mikeromard · 2026-06-17T14:36:04Z

+2. Navigate to the request that gets the user details and add the `user_id` variable as a parameter.

-The request to get the user details, should be looking like the following example:
+The request to get the user details looks like the following example:


Suggested change

The request to get the user details looks like the following example:

The following image shows an example of a request to get user details.

mikeromard · 2026-06-17T14:43:40Z

+Configure alternative OTP two-factor authentication for your target before proceeding. Visit [Configure two-factor authentication (2FA)](configure-two-factor-authentication.md) for setup instructions.

-You will need the **UNIQUE 2FA CONFIGURATION URL** from your target's Authentication settings.
+You need the **UNIQUE 2FA CONFIGURATION URL** from the Authentication settings of your target.


It would be nice if you could provide an example of a UNIQUE 2FA CONFIGURATION URL, and more specific instructions on where to find it. I see that field in the screenshots in the Configure alternative OTP , but not in the TOTP section. Does it only apply when using alternative OTPs? If so it would be good to note that here.

mikeromard · 2026-06-17T14:47:41Z

 <figure><img src="../../../../.gitbook/assets/configure-two-factor-authentication-otp-gmail-create.png" alt="Create Apps Script in Google Script"><figcaption></figcaption></figure>

-3. Click on the project name "Untitled Project" at the top and enter a meaningful name (for example, "Extract OTPs from Email").
+3. Click the project name "Untitled Project" at the top and enter a meaningful name (for example, "Extract OTPs from Email").


Suggested change

3. Click the project name "Untitled Project" at the top and enter a meaningful name (for example, "Extract OTPs from Email").

3. Click **Untitled Project** and enter a meaningful name (for example, "Extract OTPs from Email").

mikeromard · 2026-06-17T14:51:37Z

 * Access to Power Automate (Premium license required for HTTP POST calls)
 * An email account configured in Power Automate that receives OTP emails
-* The **UNIQUE 2FA CONFIGURATION URL** from your target's Authentication settings (see [Configure two-factor authentication (2FA)](configure-two-factor-authentication.md))
+* The **UNIQUE 2FA CONFIGURATION URL** from the Authentication settings of your target. Visit [Configure two-factor authentication (2FA)](configure-two-factor-authentication.md).


This is a better phrasing than we have for the Gmail section.

mikeromard · 2026-06-17T14:52:45Z

@@ -250,7 +248,7 @@ Configure an HTTP action to send the extracted OTP to Snyk API & Web:
 3. Configure the HTTP action:

 * **Method**: Select **POST**


For both Method and URI, the text after the : is a complete sentence and should end with a period.

mikeromard · 2026-06-17T16:48:04Z

-* **Secure infrastructure:** we use a combination of proprietary models and secure third-party LLMs. For third-party models, your data is never used for model training and is retained for no more than eight hours.
+* **What is sent:** Snyk sends specific components of web communications, such as portions of HTTP requests and responses, to the AI model for real-time analysis.
+* **No training on your data:** Snyk does **not** use your proprietary code or sensitive request data to train, optimize, or fine-tune its AI models.
+* **Secure infrastructure:** Snyk uses a combination of proprietary models and secure third-party LLMs. For third-party models, Snyk never uses your data for model training and retains it for no more than eight hours.


Suggested change

* **Secure infrastructure:** Snyk uses a combination of proprietary models and secure third-party LLMs. For third-party models, Snyk never uses your data for model training and retains it for no more than eight hours.

* **Secure infrastructure**: Snyk uses a combination of proprietary models and secure third-party LLMs. For third-party models, Snyk never uses your data for model training and retains it for no more than eight hours.

mikeromard · 2026-06-17T16:50:32Z

 Note:

-* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the "Log in with Snyk" button:
+* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the **Log in with Snyk** button:


Suggested change

* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the **Log in with Snyk** button:

* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the **Log in with Snyk** button.

mikeromard · 2026-06-17T16:51:23Z

 * **Assertion Consumer Service** - The Snyk API & Web endpoint to do the SAML authentication and authorization: `https://sso.plus.probely.app/sso/<organization-id>/complete/`

-In the endpoint, replace `<organization-id>` with a string that identifies your organization (with lowercase letters and hyphens only). For example, the company name, but if you need any help, we can suggest it for you.
+In the endpoint, replace `<organization-id>` with a string that identifies your organization, using lowercase letters and hyphens only. For example, use the company name. If you need help, Snyk can suggest it for you.


How does the user request that Snyk suggest this for them?

mikeromard · 2026-06-17T16:54:57Z

 #### Connect your Snyk accounts

-1. In Snyk API & Web, navigate to **Settings > Integrations**.
+1. In Snyk, navigate to **Settings > Integrations**.


Suggested change

1. In Snyk, navigate to **Settings > Integrations**.

1. In Snyk, navigate to **Settings** > **Integrations**.

mikeromard · 2026-06-17T16:57:45Z

-    * In the first dropdown, choose the week of the month (First, Second, Third, Fourth, or Last).
-    * In the second dropdown, choose the day of the week (Monday, Tuesday, and so on).
+  * **Monthly/Quarterly** - The scan runs every month or quarter on the day (number) defined in the **Start date**. In this case, Snyk displays a **Repeat scans every** check box to configure a different day:
+    * In the first dropdown, select the week of the month (**First**, **Second**, **Third**, **Fourth**, or **Last**).


Are these dropdowns named in the UI? If so, use their names here instead of first and second.

TashaTBaker requested a review from a team as a code owner June 17, 2026 11:47

Merge remote-tracking branch 'origin/main' into api-and-web-style-review

6f29370

# Conflicts: # scan-fix-and-prevent/scan-with-snyk/snyk-api-web/review-and-fix/review-pending-findings.md

TashaTBaker commented Jun 17, 2026

View reviewed changes

mikeromard suggested changes Jun 17, 2026

View reviewed changes

	The request to get the user details looks like the following example:
	The following image shows an example of a request to get user details.

	3. Click the project name "Untitled Project" at the top and enter a meaningful name (for example, "Extract OTPs from Email").
	3. Click Untitled Project and enter a meaningful name (for example, "Extract OTPs from Email").

		@@ -250,7 +248,7 @@ Configure an HTTP action to send the extracted OTP to Snyk API & Web:
		3. Configure the HTTP action:

		* Method: Select POST

	* Secure infrastructure: Snyk uses a combination of proprietary models and secure third-party LLMs. For third-party models, Snyk never uses your data for model training and retains it for no more than eight hours.
	* Secure infrastructure: Snyk uses a combination of proprietary models and secure third-party LLMs. For third-party models, Snyk never uses your data for model training and retains it for no more than eight hours.

	* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the Log in with Snyk button:
	* If you already use SSO to log in to Snyk, you can log in to Snyk API & Web with your existing Snyk account, using the Log in with Snyk button.

	1. In Snyk, navigate to Settings > Integrations.
	1. In Snyk, navigate to Settings > Integrations.

Uh oh!

Conversation

TashaTBaker commented Jun 17, 2026

Uh oh!

snyk-io Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Snyk checks have passed. No issues have been found so far.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

snyk-io Bot commented Jun 17, 2026 •

edited

Loading