Threat Intelligence Beta: OpenAPI spec, interactive reference, Postman#22
Merged
Conversation
…ference Removes the per-endpoint tables, request bodies, field reference, and response shapes from beta.md now that they're generated from the OpenAPI spec. Keeps the narrative that belongs on a prose page: auth, platforms, pagination strategy, error codes, testing recipes, and v2 migration notes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tag landing pages (e.g. /operations/tags/vulnerabilities/) and the overview were rendering only the one-line blurb for each tag. Expand the info, tags[].description, and the thinner operation descriptions so each generated page has usable content: auth, platforms, pagination strategies, errors, related pages, and per-tag endpoint guides with deep links. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Pins starlight-openapi ^0.22.1 (latest version compatible with Starlight 0.34 / Astro 5.9; 0.23+ requires Starlight ≥0.38). Renders the Threat Intelligence Beta YAML under /api-reference/threat-intelligence-beta/ and adds an "API reference" sidebar group populated by openAPISidebarGroups. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Move schemas/threat-intel-beta.yaml into public/ so it's served at https://docs.patchstack.com/schemas/threat-intel-beta.yaml. - Add a small Astro integration that runs openapi-to-postmanv2 at config:setup, writing public/schemas/threat-intel-beta.postman_collection.json on every build. The generated collection is gitignored — the OpenAPI YAML stays the single source of truth. - Expand beta.md with a "Use with Postman / Insomnia / Bruno / Hoppscotch" section including a Run in Postman button, a Claude Code / LLM assistants section, and openapi-generator snippets for SDK generation. Only the Threat Intelligence Beta API is wired up for now. Additional APIs can drop a YAML into public/schemas/ and add an entry to the postmanCollections array and starlightOpenAPI config. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Merge the standalone "API reference" top-level sidebar group into "API solutions" → "Threat Intelligence API", immediately below the Beta narrative. Users now have a single entry point to find anything API-related; the narrative and interactive reference sit side-by-side under the same parent. - Convert "API solutions" from autogenerate to a manual items list so the generated OpenAPI pages (openAPISidebarGroups) can be interleaved with the .md files. - Pin Beta to the top of the Threat Intelligence group via sidebar.order: 0 and add a "New" tip badge so it's discoverable. - Rename the OpenAPI reference label from "Threat Intelligence API (Beta)" to "Interactive reference (Beta)" to avoid redundancy with the parent group name. Trade-off: new pages dropped into API solutions subfolders no longer auto-appear in the sidebar — astro.config.mjs needs a manual entry. Acceptable for the current 6 pages across 2 APIs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The manual items list dropped the index.mdx entry that autogenerate was
picking up. Add { slug: 'api-solutions' } at the top so the Introduction
page appears before App API and Threat Intelligence API, preserving the
original order.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move the Beta entries to the bottom of the Threat Intelligence API group and nest them under a single expandable "Beta tier API" group (with the "New" badge on the group itself). The narrative is now labelled "Guide" and the OpenAPI-generated pages are labelled "Reference" — both together inside the Beta parent, so everything Beta is one click and one glance. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for deluxe-meerkat-8daf24 ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Strip `id` and `_postman_id` UUIDs from the generated collection (both optional in Collection v2.1 — Postman assigns new ones on import) and add example values to schemas where openapi-to-postmanv2 was otherwise synthesising random data (OffsetPagination, CursorPagination, ProductType/Name/Version path params). Two consecutive builds now produce byte-identical output. Commit the collection so it's reachable via GitHub raw URL the moment this PR merges, instead of waiting on a docs.patchstack.com deploy. Build-time regeneration stays in place so the JSON can never drift from the YAML. Update the Run in Postman button to use the GitHub raw URL on main and add a direct-download fallback link for testing locally and on deploy previews — Postman's cloud cannot fetch a localhost: URL, which was producing the "blank Run in Postman modal" symptom. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "Run in Postman" button relied on the deprecated `app.getpostman.com/run-collection/?collection=<url>` endpoint, which no longer accepts raw collection URLs — it only works with collections published to Postman's Public API Network and referenced by UID. The button silently did nothing when clicked. Replacing it with a plain download link plus a `File → Import → Link` instruction is honest about the flow and actually works today. Can be re-added later if/when the collection is published to Postman. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This reverts commit fe4d16c.
mariojgt
reviewed
Apr 22, 2026
mariojgt
approved these changes
Apr 22, 2026
Per Mario's review on PR #22: the app.getpostman.com/run-collection/?collection=<url> endpoint was deprecated. Postman now only accepts published collections referenced by UID through the Public API Network — raw JSON URLs fail silently, which is what produced the blank-modal symptom. Replace the button with the honest flow: download + File → Import → Link. Can be re-added later without a breaking change if someone publishes the collection to Postman. Co-Authored-By: Mario Tarosso <mariojgt2@gmail.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Rename the sidebar group and page title from "Beta tier API" to "Beta API" — Beta isn't an access tier alongside Standard / Extended, it's a new generation of the API. The "tier" naming invited the wrong mental model. Add a "Which API should I use?" comparison table to Overview and clearly flag Beta as available to selected partners working directly with Patchstack only. Update the Beta guide intro and Overview's Beta blurb to match. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Starlight applies .large (heavier weight + larger size) to sidebar group labels. In a sub-group where Beta API sits next to leaf items (Standard tier API, Extended tier API, API properties) the bold treatment made Beta look visually promoted, even though its "New" badge already carries the emphasis. Scope the override via :has() so it only fires on group labels that carry a badge — today that's Beta API, and any future badged group will get the same treatment automatically without affecting plain groups like App API or Threat Intelligence API. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
starlight-openapiand served at/schemas/threat-intel-beta.yamlfor import into Postman/Insomnia/Bruno/Hoppscotch, SDK generation, and LLM assistants.public/schemas/threat-intel-beta.postman_collection.json, gitignored) and adds a Run in Postman button + tooling guide to the Beta narrative page.Newbadge.What changed
public/schemas/threat-intel-beta.yaml(OpenAPI 3.1) — single source of truthopenapi-to-postmanv2generates the Postman collection at build-time via a small Astro integration inastro.config.mjsstarlight-openapi@^0.22.1renders operation pages at/api-reference/threat-intelligence-beta/...beta.mdslimmed from 440 → 150 lines (endpoint tables/shapes now come from the spec); new sections for Postman/Insomnia/Bruno/Hoppscotch import, Claude Code usage, and SDK generationitemsso the OpenAPI-generated sidebar groups can sit inline with the Markdown pages. Beta narrative + reference grouped under a single expandable "Beta tier API [New]" itemTradeoffs the reviewer should weigh
starlight-openapi@0.22.1is the latest version compatible with the repo's Starlight 0.34.3 / Astro 5.9. Upgrading to 0.23+ requires bumping Starlight to ≥0.38 and Astro to ≥6 — out of scope for this PR.astro.config.mjs. Reasonable for the current 6 pages / 2 APIs; we can revisit if more APIs land.beta.mdtells integrators to pin a commit if they need stability.Test plan
npm run buildcompletes cleanly; 177 pages built/api-solutions/threat-intelligence-api/beta/renders the Run in Postman button and tooling guide/api-reference/threat-intelligence-beta/and its operation pages render with full descriptions (auth, pagination, errors, per-tag guides)https://docs.patchstack.com/schemas/threat-intel-beta.yamland…/schemas/threat-intel-beta.postman_collection.jsonreturn 200🤖 Generated with Claude Code