feat: split API reference into per-product pages for AgentKit and SaaSKit#706
Open
saif-at-scalekit wants to merge 28 commits into
Open
Conversation
- Add Redocly CLI workflow: split monolithic spec into multi-file structure, then selectively bundle per-product specs with --remove-unused-components - Create openapi/agentkit.yaml and openapi/saaskit.yaml as custom root files that into the shared split structure - Add pnpm split-api script chaining split + bundle for both products - Add Scalar API reference pages at /agentkit/apis/ and /saaskit/apis/ - AgentKit page includes quickstart with auth, connected accounts, and tool execution - Update secondary nav: AgentKit links to /agentkit/apis/, SaaSKit to /saaskit/apis/ - Update path fallbacks in secondary-nav-utils for new routes - Existing /apis/ route with full combined spec remains unchanged
… methods
Tag names like 'Connected Accounts' were lowercased but not slugified,
producing 'connected%20accounts' instead of 'connected-accounts'. HTTP
methods were lowercased ('get') but Scalar uses uppercase ('GET').
- java-spring-boot-jwt-timeout: #tag/authentication does not exist, changed to #tag/sessions - check-sso-domain: lowercase get -> GET to match Scalar anchors - create-roles-permissions: lowercase get -> GET - custom-user-attributes: lowercase get -> GET
- Extend openapi-to-markdown integration to generate markdown for all three specs: combined (apis.md), agentkit (agentkit/apis.md), saaskit (saaskit/apis.md) - Write to both dist/ and public/ so files are always served as static assets, fixing intermittent 404s caused by SSR shadowing dist/ files - Add Netlify cache headers for per-product markdown files - Update llms.config.ts with per-product API markdown and OpenAPI spec links - Update generate-llms-index.js with per-product entries in Optional section - Add generated markdown files to .gitignore (build artifacts)
Each product API reference now shows links to switch to the other product's API reference or the combined reference.
Remove .gitignore entries — these must be committed so Netlify's CDN serves them as static assets without hitting SSR.
Instead of generic 'Other API references', each link now describes what the user would be looking for when switching.
Contributor
|
Caution Review failedFailed to post review comments WalkthroughAdds AgentKit OpenAPI spec, many new component schemas, and extensive multi-language SDK code samples; updates Netlify headers, .gitignore, and CODEOWNERS. ChangesAgentKit API and Samples
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
|
✅ Deploy Preview for scalekit-starlight ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…ail create/update) (#707)
* add Atlassian Rovo MCP connector docs * add Atlassian Rovo MCP setup guide with domain configuration steps and screenshots * fix: simplify Atlassian Rovo MCP setup guide for DCR flow, update screenshots * resolve CodeRabbit comments: fix wrong-context param descriptions, capabilities bullet, category slug; update redirect URI screenshot with arrow * resolve CodeRabbit: fix cross-contaminated param descriptions, clarify fetch capability, add cloudId workflow section * sync connector docs: add new HubSpot engagement tools, re-apply atlassianmcp fixes post-sync * Revert "sync connector docs: add new HubSpot engagement tools, re-apply atlassianmcp fixes post-sync" This reverts commit 587d6f0. * resolve CodeRabbit: fix compass/confluence param descriptions, inject common-workflows section, fix tool name prefix
* add LeadIQ connector docs: capabilities, setup guide, common workflows * resolve CodeRabbit comments: fix company_domain→domain, frontmatter, add API keys screenshot * fix: move LeadIQ API keys screenshot to correct assets path
* add ClickHouse connector docs with capabilities and common workflows Add ClickHouse agent connector documentation including setup guides, common workflow templates, and capability definitions to help developers integrate ClickHouse data sources with Scalekit agents. * fix ClickHouse connector docs: correct parameter names, capitalization, and descriptions
* add Zapier MCP connector docs with capability bullets and common workflows - Added Zapier MCP connector documentation page - Added 6 capability bullets to capabilities.json - Created common workflows template with 5 collapsible examples - Updated connector catalog to include Zapier * fix Zapier connector docs: correct skillDefinition param name and API Key casing
* add Adobe Marketing Agent MCP connector docs
* fix: use API display_name for connector auth types (OAuth 2.1/DCR for MCP connectors)
resolveAuthType was hardcoding 'OAuth 2.0' for all OAUTH providers.
The API already provides display_name ('OAuth 2.1/DCR' vs 'OAuth 2.0')
and is_mcp flag — now used directly.
Also updates generateAuthSection prose for MCP connectors to mention
DCR and PKCE instead of generic OAuth 2.0 redirect description.
Re-synced all connector pages to pick up the fix.
* fix: escape single quotes in connectorAuthType frontmatter value
* add connector docs for adzvisermcp, commonroommcp, customeriomcp, fellowaimcp, firecrawlmcp, grainmcp, supermetricsmcp
* add firecrawl dashboard screenshot to setup docs
---------
Co-authored-by: Saif Ali Shaik <saif.shaik@scalekit.com>
#714) * docs: add template redirect URIs and organization logo branding guides * fix: escape curly braces in org logo branding MDX table * docs: rename to organization branding and add pages to sidebar nav * docs: rename organization-logo-branding to organization-branding * docs: simplify template redirect and org branding docs * code snippet changes * docs: restructure org branding and template redirect URL pages - Rename "Template redirect URIs" to "Template redirect URLs" throughout - Separate dashboard and SDK instructions into distinct subsections - Use createOrganization snippets consistently across all 4 SDKs - Replace template variable resolution note with actionable org_id guidance - Remove em-dashes, clean up surface table (remove internal paths) - Update Java SDK version to v2.1.1+ - Add screenshot assets for org slug/logo and branding configuration * docs: bump Java SDK version to 2.1.1 in install snippet * docs: bump Java SDK version to 2.1.3 * chore: update auto-generated d2 diagram SVGs * docs: address CodeRabbit review comments - Add next: frontmatter to both pages for sidebar journey continuity - Add tags to template-redirect-uris frontmatter - Add title attribute to all Aside components - Change TabItem value from 'nodejs' to canonical 'node' for tech-stack syncKey consistency * docs: improve organization branding page structure and content * docs: add section on passing organization_id to show org logo on login page * docs: regenerate D2 diagram SVGs * docs: rename template redirect URLs to org-specific redirect URLs with SDK examples - Rename feature from "Template redirect URLs" to "Organization-specific redirect URLs" across template-redirect-uris.mdx - Normalize URI → URL terminology in body prose - Add SDK code examples (Node.js, Python, Go, Java) showing resolved redirectUri with organizationId - Add worked example section with 4-step numbered list explaining the feature - Add prev nav link in template-redirect-uris.mdx pointing to redirects.mdx - Update next link in redirects.mdx to point to template-redirect-uris.mdx - Add "Different redirect URL per organization" section in redirects.mdx - Add logo file requirements in organization-branding.mdx (URL, formats, height) * docs: add template redirect URIs asset and update SCIM quickstart diagram * docs: improve template redirect URI guide with prose refinement and SDK examples - Strengthen prose: add clarity that setting just one redirect URI is sufficient - Add 'Set slug, metadata, or both' comments across all SDK language tabs - Fix Go example with proper Metadata field and error handling - Add screenshot assets documenting the redirect URI configuration * docs: rename template-redirect-uris to org-redirect-urls with updated links - Rename guides/dashboard/template-redirect-uris.mdx to org-redirect-urls.mdx - Update sidebar config slug to org-redirect-urls - Add URL redirect from old to new path - Update redirects.mdx next link and cross-references - Rename dashboard guide title to 'Configure redirect URLs' * docs: remove unreferenced create-organization-slug-logo image * docs: remove backward-compat redirect for template-redirect-uris (never released) --------- Co-authored-by: amitash1912 <amit.ashish@scalekit.com> Co-authored-by: Amit Ashish <amitashish@Amits-MacBook-Air.local>
- New guide: /authenticate/manage-organizations/organization-session-policy - Cross-link from manage-session via consolidated Step 3 Aside - Update hosted-widgets to surface session policy widget - Sidebar entry under Manage users & orgs
…sync (#718) * add Adobe Marketing Agent MCP connector docs * fix: use API display_name for connector auth types (OAuth 2.1/DCR for MCP connectors) resolveAuthType was hardcoding 'OAuth 2.0' for all OAUTH providers. The API already provides display_name ('OAuth 2.1/DCR' vs 'OAuth 2.0') and is_mcp flag — now used directly. Also updates generateAuthSection prose for MCP connectors to mention DCR and PKCE instead of generic OAuth 2.0 redirect description. Re-synced all connector pages to pick up the fix. * fix: escape single quotes in connectorAuthType frontmatter value * docs(hubspot): add optional scopes, app type guidance, and legacy app notes * chore(docs): sync MCP connectors from prod catalog and fix duplicate clickhouse template * revert: restore svg files unchanged from main * fix: resolve coderabbit comments — fix duplicate googledwd heading, authType quoting, and broken anchor * revert: restore svg files and org-redirect-urls.mdx to match main * revert: restore sync-agent-connectors.js to match main * chore(docs): re-sync agent connectors from prod catalog --------- Co-authored-by: Saif Ali Shaik <saif.shaik@scalekit.com>
* Add AkshayParihar33 as code owner for MDX files * Update CODEOWNERS comments to reflect current owner list
* Add xmcp quickstart guide for Scalekit MCP auth * Add pre-generated D2 diagram for xmcp quickstart * Add xmcp quickstart to MCP Auth sidebar * Update xmcp quickstart page title
* Add Mastra AgentKit cookbook: build a Mastra agent with Scalekit tools * Use second-person phrasing consistently in instructional text
#727) - Adds descriptionHtml frontmatter field and schema entry for connectors needing hyperlinks - Connector page header and index cards render descriptionHtml via set:html when present - Link styling inherits text color with underline for native appearance - description-html.json stores overrides that survive connector regeneration - sync-agent-connectors.js emits descriptionHtml when slug entry exists - First implementation: Apify MCP connector links to https://mcp.apify.com
* docs(cookbook): add FastRouter + Scalekit AgentKit tool-calling guide * docs(cookbook): address CodeRabbit review feedback on FastRouter + AgentKit tool calling * docs(cookbook): fix unused variables in Go example (fastrouter + AgentKit)
) * docs(domain-verification): add Organization domains page and cross-links Adds a new "Organization domains" page covering DNS-based domain verification for SSO Home Realm Discovery and SCIM. Documents all four ways to add a domain (Admin Portal, Hosted Widgets, Dashboard, API), four new webhook events, and links the feature into existing SSO, JIT, SCIM, and Hosted Widgets pages. Also fixes a pre-existing broken anchor in org-redirect-urls.mdx. * docs(domain-verification): review feedback — reorder hosted widgets, update links and webhook payloads, remove check-sso-domain aside * docs(domain-verification): add organization-domains screenshot assets * docs(domain-verification): add SDK tabs for enable feature and portal link; reorganize onboard-enterprise-customers domain verification * docs(domain-verification): complete SDK tabs expansion for enable feature and portal link endpoints * chore: revert unrelated d2 svg regeneration from domain-verification PR * Coderabbit comment fixes * chore: remove orphan d2 svg for organization-domains (no diagram in source) * Improvements
- Refresh OpenAPI split from latest backend scalar (after PR 2191 / sk-422) - Curate openapi/agentkit.yaml with real $ref entries for Connectors + full MCP surfaces (MCP, MCP Configurations, MCP Instances) - Add production bundle scripts: bundle:agentkit, bundle:saaskit, bundle:apis - Update tagsSorter in both AgentKit and unified All APIs Scalar pages to include new clean tags - Replace unified scalar files (yaml + json) with fresh backend versions and remove temporary .new file - Include new MCP and custom provider path files + schemas from fresh split - Document deferred code samples for new surfaces (follow-up via scalekit-code-doctor per Option B) - Production readiness pass: addressed review findings, verified bundles and separation This closes the gaps between direct backend render and the docs pipeline for the new AgentKit surfaces.
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
4 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
Splits the monolithic API reference into dedicated per-product pages while preserving the combined view.
Closes SK-399
What changed
Redocly multi-file split
redocly splitto decomposescalekit.scalar.yamlinto a multi-file structure (openapi/paths/,openapi/webhooks/,openapi/components/)openapi/agentkit.yamlandopenapi/saaskit.yamlthat$refonly the relevant paths, webhooks, and tagsredocly bundle --remove-unused-componentsproduces clean per-product specspnpm run split-apicommand chains the full workflowPer-product Astro pages
/agentkit/apis/— AgentKit API reference (Connected Accounts, tool execution)/saaskit/apis/— SaaSKit API reference (SSO, SCIM, directories, sessions, roles, users, etc.)/apis/— Combined reference (unchanged)AgentKit quickstart
agentkit.yamlinfo.description with auth steps, tool execution example, and SDK install for Node.js, Python, JavaNavigation updates
/agentkit/apis//saaskit/apis/Cross-links
Per-product LLM markdown
public/apis.md— combined (777KB)public/agentkit/apis.md— AgentKit only (74.5KB)public/saaskit/apis.md— SaaSKit only (705KB)llms.config.tsandgenerate-llms-index.jswith per-product referencesBug fixes
#tag/anchor links across docsapis.mdintermittent 404 by writing topublic/(static asset) instead of onlydist/Routes
/apis/scalekit.scalar.yaml/agentkit/apis/agentkit.scalar.yaml/saaskit/apis/saaskit.scalar.yamlSummary by CodeRabbit
New Features
Documentation
Configuration