From 5e9d8ffd648a1723cadeac24db1a61b8996e800b Mon Sep 17 00:00:00 2001 From: Jack Dolgin Date: Wed, 8 Jul 2026 21:00:43 -0400 Subject: [PATCH] Fixed some inconsistencies and unclear wording --- accessing-session-data.mdx | 7 +- api-reference/events-data.mdx | 2 +- api-reference/openapi.json | 2 +- api-reference/session-data.mdx | 2 +- api-reference/tag-data.mdx | 2 +- api-reference/user-data.mdx | 2 +- best-practices.mdx | 4 +- essentials/code.mdx | 37 ---- essentials/images.mdx | 59 ------ essentials/markdown.mdx | 88 --------- essentials/navigation.mdx | 66 ------- essentials/settings.mdx | 318 --------------------------------- how-it-works.mdx | 2 +- integration.mdx | 11 +- introduction.mdx | 2 +- status.mdx | 2 +- using-the-badge.mdx | 8 +- using-the-dashboard.mdx | 7 +- 18 files changed, 31 insertions(+), 590 deletions(-) delete mode 100644 essentials/code.mdx delete mode 100644 essentials/images.mdx delete mode 100644 essentials/markdown.mdx delete mode 100644 essentials/navigation.mdx delete mode 100644 essentials/settings.mdx diff --git a/accessing-session-data.mdx b/accessing-session-data.mdx index 8395cb8..d9551f7 100644 --- a/accessing-session-data.mdx +++ b/accessing-session-data.mdx @@ -1,3 +1,8 @@ +--- +title: 'Accessing session data' +sidebarTitle: 'Accessing session data' +--- + This guide explains how to retrieve session data from the Roundtable Proof-of-Human API. There are three primary methods to access your data: by specific session ID, by user ID, or by tag. A separate endpoint is available to retrieve the full event log for a given session. For more detailed information on the API specification, see the [API Reference](api-reference). ## Authentication @@ -106,4 +111,4 @@ This returns the full event log for the specified session, including the total e ## Next steps - Visit the [Dashboard](https://accounts.roundtable.ai/account) to generate a secret key. -- Review our [API Reference](api-reference) for detailed endpoint specifications. +- Review our [API Reference](api-reference/session-data) for detailed endpoint specifications. diff --git a/api-reference/events-data.mdx b/api-reference/events-data.mdx index 36ab016..13e1a82 100644 --- a/api-reference/events-data.mdx +++ b/api-reference/events-data.mdx @@ -1,4 +1,4 @@ --- -title: 'Getting Session Events' +title: 'Getting session events' openapi: 'GET /v1/sessions/{sessionId}/events' --- diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 9feaf0e..74fe16f 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -66,7 +66,7 @@ "risk_explanation": { "type": "string", "description": "Short explanation of the factors contributing to the risk score", - "example": "User was flagged for multiple likely bot behavior, indicating a medium to high risk of fraud." + "example": "User was flagged for multiple likely bot behaviors, indicating a medium to high risk of fraud." }, "recommended_action": { "type": "string", diff --git a/api-reference/session-data.mdx b/api-reference/session-data.mdx index 130577b..09ce582 100644 --- a/api-reference/session-data.mdx +++ b/api-reference/session-data.mdx @@ -1,4 +1,4 @@ --- -title: 'Getting Session Data' +title: 'Getting session data' openapi: 'GET /v1/sessions/{sessionId}/report' --- \ No newline at end of file diff --git a/api-reference/tag-data.mdx b/api-reference/tag-data.mdx index c59deb2..f3f6099 100644 --- a/api-reference/tag-data.mdx +++ b/api-reference/tag-data.mdx @@ -1,4 +1,4 @@ --- -title: 'Getting Tag Data' +title: 'Getting tag data' openapi: 'GET /v1/tags/{tag}/sessions' --- diff --git a/api-reference/user-data.mdx b/api-reference/user-data.mdx index de08362..a63ac76 100644 --- a/api-reference/user-data.mdx +++ b/api-reference/user-data.mdx @@ -1,4 +1,4 @@ --- -title: 'Getting User Data' +title: 'Getting user data' openapi: 'GET /v1/users/{userId}/sessions' --- \ No newline at end of file diff --git a/best-practices.mdx b/best-practices.mdx index 2eeaefe..6c882c6 100644 --- a/best-practices.mdx +++ b/best-practices.mdx @@ -1,6 +1,6 @@ --- -title: 'Best Practices' -sidebarTitle: 'Best Practices' +title: 'Best practices' +sidebarTitle: 'Best practices' --- This page contains recommendations for getting the most out of Roundtable Proof-of-Human. This will help you deploy Proof-of-Human effectively, calibrate your risk thresholds, and maintain your detection pipeline over time. diff --git a/essentials/code.mdx b/essentials/code.mdx deleted file mode 100644 index d2a462a..0000000 --- a/essentials/code.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: 'Code Blocks' -description: 'Display inline code and code blocks' -icon: 'code' ---- - -## Basic - -### Inline Code - -To denote a `word` or `phrase` as code, enclose it in backticks (`). - -``` -To denote a `word` or `phrase` as code, enclose it in backticks (`). -``` - -### Code Block - -Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language. - -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` - -````md -```java HelloWorld.java -class HelloWorld { - public static void main(String[] args) { - System.out.println("Hello, World!"); - } -} -``` -```` diff --git a/essentials/images.mdx b/essentials/images.mdx deleted file mode 100644 index 60ad42d..0000000 --- a/essentials/images.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 'Images and Embeds' -description: 'Add image, video, and other HTML elements' -icon: 'image' ---- - - - -## Image - -### Using Markdown - -The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code - -```md -![title](/path/image.jpg) -``` - -Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed. - -### Using Embeds - -To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images - -```html - -``` - -## Embeds and HTML elements - - - -
- - - -Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility. - - - -### iFrames - -Loads another HTML page within the document. Most commonly used for embedding videos. - -```html - -``` diff --git a/essentials/markdown.mdx b/essentials/markdown.mdx deleted file mode 100644 index c8ad9c1..0000000 --- a/essentials/markdown.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: 'Markdown Syntax' -description: 'Text, title, and styling in standard markdown' -icon: 'text-size' ---- - -## Titles - -Best used for section headers. - -```md -## Titles -``` - -### Subtitles - -Best use to subsection headers. - -```md -### Subtitles -``` - - - -Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right. - - - -## Text Formatting - -We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it. - -| Style | How to write it | Result | -| ------------- | ----------------- | --------------- | -| Bold | `**bold**` | **bold** | -| Italic | `_italic_` | _italic_ | -| Strikethrough | `~strikethrough~` | ~strikethrough~ | - -You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text. - -You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text. - -| Text Size | How to write it | Result | -| ----------- | ------------------------ | ---------------------- | -| Superscript | `superscript` | superscript | -| Subscript | `subscript` | subscript | - -## Linking to Pages - -You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com). - -Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section. - -Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily. - -## Blockquotes - -### Singleline - -To create a blockquote, add a `>` in front of a paragraph. - -> Dorothy followed her through many of the beautiful rooms in her castle. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -``` - -### Multiline - -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. - -```md -> Dorothy followed her through many of the beautiful rooms in her castle. -> -> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood. -``` - -### LaTeX - -Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component. - -8 x (vk x H1 - H2) = (0,1) - -```md -8 x (vk x H1 - H2) = (0,1) -``` diff --git a/essentials/navigation.mdx b/essentials/navigation.mdx deleted file mode 100644 index ca44bb6..0000000 --- a/essentials/navigation.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: 'Navigation' -description: 'The navigation field in mint.json defines the pages that go in the navigation menu' -icon: 'map' ---- - -The navigation menu is the list of links on every website. - -You will likely update `mint.json` every time you add a new page. Pages do not show up automatically. - -## Navigation syntax - -Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names. - - - -```json Regular Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": ["quickstart"] - } -] -``` - -```json Nested Navigation -"navigation": [ - { - "group": "Getting Started", - "pages": [ - "quickstart", - { - "group": "Nested Reference Pages", - "pages": ["nested-reference-page"] - } - ] - } -] -``` - - - -## Folders - -Simply put your MDX files in folders and update the paths in `mint.json`. - -For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`. - - - -You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted. - - - -```json Navigation With Folder -"navigation": [ - { - "group": "Group Name", - "pages": ["your-folder/your-page"] - } -] -``` - -## Hidden Pages - -MDX files not included in `mint.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them. diff --git a/essentials/settings.mdx b/essentials/settings.mdx deleted file mode 100644 index ae6e7d6..0000000 --- a/essentials/settings.mdx +++ /dev/null @@ -1,318 +0,0 @@ ---- -title: 'Global Settings' -description: 'Mintlify gives you complete control over the look and feel of your documentation using the mint.json file' -icon: 'gear' ---- - -Every Mintlify site needs a `mint.json` file with the core configuration settings. Learn more about the [properties](#properties) below. - -## Properties - - -Name of your project. Used for the global title. - -Example: `mintlify` - - - - - An array of groups with all the pages within that group - - - The name of the group. - - Example: `Settings` - - - - The relative paths to the markdown files that will serve as pages. - - Example: `["customization", "page"]` - - - - - - - - Path to logo image or object with path to "light" and "dark" mode logo images - - - Path to the logo in light mode - - - Path to the logo in dark mode - - - Where clicking on the logo links you to - - - - - - Path to the favicon image - - - - Hex color codes for your global theme - - - The primary color. Used for most often for highlighted content, section - headers, accents, in light mode - - - The primary color for dark mode. Used for most often for highlighted - content, section headers, accents, in dark mode - - - The primary color for important buttons - - - The color of the background in both light and dark mode - - - The hex color code of the background in light mode - - - The hex color code of the background in dark mode - - - - - - - - Array of `name`s and `url`s of links you want to include in the topbar - - - The name of the button. - - Example: `Contact us` - - - The url once you click on the button. Example: `https://mintlify.com/contact` - - - - - - - - - Link shows a button. GitHub shows the repo information at the url provided including the number of GitHub stars. - - - If `link`: What the button links to. - - If `github`: Link to the repository to load GitHub information from. - - - Text inside the button. Only required if `type` is a `link`. - - - - - - - Array of version names. Only use this if you want to show different versions - of docs with a dropdown in the navigation bar. - - - - An array of the anchors, includes the `icon`, `color`, and `url`. - - - The [Font Awesome](https://fontawesome.com/search?s=brands%2Cduotone) icon used to feature the anchor. - - Example: `comments` - - - The name of the anchor label. - - Example: `Community` - - - The start of the URL that marks what pages go in the anchor. Generally, this is the name of the folder you put your pages in. - - - The hex color of the anchor icon background. Can also be a gradient if you pass an object with the properties `from` and `to` that are each a hex color. - - - Used if you want to hide an anchor until the correct docs version is selected. - - - Pass `true` if you want to hide the anchor until you directly link someone to docs inside it. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - - Override the default configurations for the top-most anchor. - - - The name of the top-most anchor - - - Font Awesome icon. - - - One of: "brands", "duotone", "light", "sharp-solid", "solid", or "thin" - - - - - - An array of navigational tabs. - - - The name of the tab label. - - - The start of the URL that marks what pages go in the tab. Generally, this - is the name of the folder you put your pages in. - - - - - - Configuration for API settings. Learn more about API pages at [API Components](/api-playground/demo). - - - The base url for all API endpoints. If `baseUrl` is an array, it will enable for multiple base url - options that the user can toggle. - - - - - - The authentication strategy used for all API endpoints. - - - The name of the authentication parameter used in the API playground. - - If method is `basic`, the format should be `[usernameName]:[passwordName]` - - - The default value that's designed to be a prefix for the authentication input field. - - E.g. If an `inputPrefix` of `AuthKey` would inherit the default input result of the authentication field as `AuthKey`. - - - - - - Configurations for the API playground - - - - Whether the playground is showing, hidden, or only displaying the endpoint with no added user interactivity `simple` - - Learn more at the [playground guides](/api-playground/demo) - - - - - - Enabling this flag ensures that key ordering in OpenAPI pages matches the key ordering defined in the OpenAPI file. - - This behavior will soon be enabled by default, at which point this field will be deprecated. - - - - - - - A string or an array of strings of URL(s) or relative path(s) pointing to your - OpenAPI file. - - Examples: - - ```json Absolute - "openapi": "https://example.com/openapi.json" - ``` - ```json Relative - "openapi": "/openapi.json" - ``` - ```json Multiple - "openapi": ["https://example.com/openapi1.json", "/openapi2.json", "/openapi3.json"] - ``` - - - - - - An object of social media accounts where the key:property pair represents the social media platform and the account url. - - Example: - ```json - { - "twitter": "https://twitter.com/mintlify", - "website": "https://mintlify.com" - } - ``` - - - One of the following values `website`, `facebook`, `twitter`, `discord`, `slack`, `github`, `linkedin`, `instagram`, `hacker-news` - - Example: `twitter` - - - The URL to the social platform. - - Example: `https://twitter.com/mintlify` - - - - - - Configurations to enable feedback buttons - - - - Enables a button to allow users to suggest edits via pull requests - - - Enables a button to allow users to raise an issue about the documentation - - - - - - Customize the dark mode toggle. - - - Set if you always want to show light or dark mode for new users. When not - set, we default to the same mode as the user's operating system. - - - Set to true to hide the dark/light mode toggle. You can combine `isHidden` with `default` to force your docs to only use light or dark mode. For example: - - - ```json Only Dark Mode - "modeToggle": { - "default": "dark", - "isHidden": true - } - ``` - - ```json Only Light Mode - "modeToggle": { - "default": "light", - "isHidden": true - } - ``` - - - - - - - - - A background image to be displayed behind every page. See example with - [Infisical](https://infisical.com/docs) and [FRPC](https://frpc.io). - diff --git a/how-it-works.mdx b/how-it-works.mdx index 8d0e6b1..edb3e17 100644 --- a/how-it-works.mdx +++ b/how-it-works.mdx @@ -32,7 +32,7 @@ Beyond SPAs, add the tracker to any pages where you see fraud, spam, or abuse, a ### Automatic session stitching -As long as the user remains in the same tab, Roundtable Proof-of-Human keeps a stable session ID, even across route changes in an SPA or full navigations to separate pages. We use this ID to continuously stich the session data together and give you an up-to-date risk score at any point during the session. +As long as the user remains in the same tab, Roundtable Proof-of-Human keeps a stable session ID, even across route changes in an SPA or full navigations to separate pages. We use this ID to continuously stitch the session data together and give you an up-to-date risk score at any point during the session. --- diff --git a/integration.mdx b/integration.mdx index e9030c4..4b0b966 100644 --- a/integration.mdx +++ b/integration.mdx @@ -20,15 +20,14 @@ This guide shows how to integrate Roundtable Proof-of-Human’s bot detection su ``` - -The Roundtable Proof-of-Human tracker dispatches a **`roundtable:ready`** event on `window` as soon as it is done loading. Block 2 listens for that event so you can safely call `window.setRoundtableUserId` once the script is loaded. +The Roundtable Proof-of-Human tracker dispatches a **`roundtable:ready`** event on `window` as soon as it is done loading. Block 2 listens for that completion event so you can safely call `window.setRoundtableUserId` once the tracker is loaded. ### Script‑tag attributes -The tracker recognizes three data‑attributes that let you tailor its behavior: +The tracker recognizes three data‑attributes that let you tailor the tracker's behavior: - `data-site-key` (required) – Your workspace’s site key (find it in the [Dashboard](https://accounts.roundtable.ai)). - `data-user-id` (optional) – A stable identifier for a logged‑in user to track them over multiple sessions (a hashed value is fine). @@ -99,6 +98,6 @@ Because the session ID is stored in *sessionStorage*, the value is scoped to the ### Next steps -- Visit your [Account](https://accounts.roundtable.ai/account) to access your public API key. +- Visit your [Account](https://accounts.roundtable.ai/account) to access your data site key. - Learn about [Accessing Session Data](accessing-session-data) to retrieve risk scores and session data. -- Learn how to [Integrate the Roundtable badge](badge) on your site +- Learn how to [Integrate the Roundtable badge](using-the-badge) on your site diff --git a/introduction.mdx b/introduction.mdx index 5cb2793..0cf54f2 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -35,6 +35,6 @@ The Roundtable badge is a small, drop-in widget that indicates whether Proof of 1. [Book a demo](https://roundtable.ai/book-a-demo) with our sales team to get started with an account. 2. Explore our [Integration Guide](integration) for detailed implementation instructions. -3. Review the [API Reference](api-reference) for more details on risk scores, sessions logs, biometric checks, and device checks. +3. Review the [API Reference](api-reference/session-data) for more details on risk scores, sessions logs, biometric checks, and device checks. If you have any questions or need assistance, contact us at support@roundtable.ai. diff --git a/status.mdx b/status.mdx index 63e0141..de21b88 100644 --- a/status.mdx +++ b/status.mdx @@ -1,4 +1,4 @@ --- title: 'Status' -url: "https://status.roundtable.ai" +url: "https://.roundtable.ai" --- \ No newline at end of file diff --git a/using-the-badge.mdx b/using-the-badge.mdx index 3de6e06..969c58c 100644 --- a/using-the-badge.mdx +++ b/using-the-badge.mdx @@ -1,6 +1,6 @@ --- title: 'Using the Roundtable badge' -sidebarTitle: 'Using the Roundtable Badge' +sidebarTitle: 'Using the Roundtable badge' --- Roundtable's verification badge is a small, drop-in widget that shows whether Proof of Human is running or not. It auto-renders wherever you place `
`, listens to your tracker’s events, and gracefully handles SPAs and back-navigation. @@ -35,7 +35,7 @@ After importing the badge script, the badge can be added anywhere by adding a di The badge renders inside a Shadow DOM, so your site’s CSS won’t break it (and vice-versa). -By default, the badge's width is `231px`. We recommend never setting the width less than this value. However, uou can control the badge width via a `width` attribute: +By default, the badge's width is `231px`. We recommend never setting the width less than this value. However, you can control the badge width via a `width` attribute: ```html
@@ -47,10 +47,10 @@ By default, the badge's width is `231px`. We recommend never setting the width l At any given time, the badge is in one of three states: -- **Loading:** shows a spinner and an animating progress bar while the tracker initializes verifies Roundtable is running. +- **Loading:** shows a spinner and an animating progress bar while the tracker initializes and verifies Roundtable is running. - **Pass:** displays a check icon in black. This indicates that Roundtable is running and gathering user data. - **Fail:** displays an X icon in red. This indicates that Roundtable is not running. See also: -- [Integrating Roundtable](integrating-roundtable) for adding the tracker +- [Integrating Roundtable](integration) for adding the tracker - [Accessing Session Data](accessing-session-data) for using the session ID and scores \ No newline at end of file diff --git a/using-the-dashboard.mdx b/using-the-dashboard.mdx index 97189cc..9ba6789 100644 --- a/using-the-dashboard.mdx +++ b/using-the-dashboard.mdx @@ -1,3 +1,8 @@ +--- +title: 'Using the dashboard' +sidebarTitle: 'Using the dashboard' +--- + The [Dashboard](https://accounts.roundtable.ai) provides a central location to view all session data, investigate individual user sessions, and manage your Roundtable account settings. ## Viewing session data @@ -7,7 +12,7 @@ Click on `Sessions` in the left-hand navigation bar to see a table of all record - **Session ID** – The unique identifier automatically generated by Roundtable Proof-of-Human - **User ID** – The user identifier you provided (if any) - **Risk Score** – The numerical risk score (0-100) generated by Roundtable Proof-of-Human -- **Risk Explanation** – A brief description of why the risk score assigned to the session +- **Risk Explanation** – A brief description of why the risk score was assigned to the session - **Session Duration** – How long the session lasted - **City** – The user's city (inferred from their IP address) - **Country** – The user’s country (inferred from their IP address)