canonical: https://jentic.com/apis/scalar.com/scalar

# Scalar Core

The Scalar Core API runs the Scalar platform for API documentation, registries, and SDKs: it stores and versions OpenAPI and AsyncAPI documents, JSON schemas, and lint rulesets in team namespaces, and publishes hosted docs projects. It lints documents with Vacuum, builds multi-language SDKs in languages such as typescript, python, go, and rust, and turns linked API documents into hosted agent tool servers. Registry resources can be synced with GitHub or Bitbucket repositories, docs projects report page views, referrers, and consumer types such as human, bot, and LLM readers, and the team side covers members, roles, SSO identity providers, access groups, secrets, and webhooks.

## For AI agents

Version API documents in the Scalar registry, lint them, publish docs, build multi-language SDKs, and read docs analytics for a Scalar team.

## Scope

Does not call or proxy the APIs it documents, host your application code, or replace a CI system. Use for managing Scalar API documents, SDKs, docs projects, and team settings only.

## Capabilities

- Create and version OpenAPI or AsyncAPI documents in a team namespace, and roll a version tag back to an earlier content instance
- Lint an unsaved OpenAPI or AsyncAPI document with Vacuum before saving it
- Create an SDK with language targets such as typescript, python, go, or rust and trigger a manual multi-language build
- Roll out docs changes by publishing, redeploying, or cancelling an in-flight publish, and stream its build log
- Link a GitHub repository as the source of truth for a registry resource, propose edits as pull requests, and publish from a commit
- Read docs project analytics: KPI totals, top pages, top referrers, reader feedback, and a consumer breakdown such as human, bot, or llm
- Subscribe webhooks to platform events, rotate their signing secret, and list recent delivery attempts

## Use cases

### AI agent maintaining an API registry

An agent asked to ship a spec change searches Jentic for 'create a Scalar API document version', lints the new document with postManagedDocLint, and, if it is clean, creates the version under the team namespace and slug. If the release goes wrong it lists the registry versions and rolls the version tag back to an earlier content instance, with the Scalar token injected at call time.

Example prompt: POST `/managed-doc/lint` with the document, then POST `/managed-doc/{namespace}/{slug}/version` for namespace acme and slug payments with the new content

### Generating SDKs from an API document

Teams that publish client libraries create an SDK from an API document with one or more language targets, link each target to a GitHub repository, and trigger builds. The API can resolve a complete SDK config, check whether a package name is free on a language registry, toggle publish-on-merge, and fetch the release PR open on a target's repository.

Example prompt: POST `/v1/sdks` with apiUid api_123 and languages ['typescript','python'], then POST `/v1/sdks/build` to start the build

### Reading who uses your docs

Docs owners want to know which pages matter and who reads them, including AI agents. The analytics operations return KPI totals and a timeseries, top pages by views, top referrers, reader feedback per page, and a consumer breakdown that separates human, bot, and llm traffic for a docs project.

Example prompt: Call GET `/analytics/projects/{projectUid}/consumers` and GET `/analytics/projects/{projectUid}/pages` for project prj_123 and report the share of llm readers on the top pages

### Shipping docs from a git repository

Hosted docs projects are backed by a Forgejo, GitHub, or Bitbucket repository. The API reads and commits the scalar config directly on the provider without cloning, switches a project to a different repository, and handles publishing: redeploy a previous publish, cancel one in flight, stream its build log, or check that a custom domain points at Scalar.

Example prompt: Call GET `/docs-projects/{projectUid}/config` for project prj_123, then PUT `/docs-projects/{projectUid}/config` with the updated config and GET `/publish/logs/{publishUid}` to follow the resulting publish

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/managed-doc` | List all API documents for a team |
| POST | `/managed-doc/lint` | Lint an OpenAPI or AsyncAPI document |
| POST | `/managed-doc/{namespace}/{slug}/version` | Create an API document version |
| POST | `/registry/{asset}/{namespace}/{slug}/versions/{version}/active` | Roll a version tag back |
| POST | `/v1/sdks` | Create an SDK with language targets |
| POST | `/v1/sdks/build` | Trigger a multi-language SDK build |
| GET | `/docs-projects/{projectUid}/config` | Read a docs project's scalar config |
| GET | `/analytics/projects/{projectUid}/overview` | Get docs project KPIs |

## Key resources

- **Managed documents** — OpenAPI and AsyncAPI documents with versions in a namespace
- **Schemas and rulesets** — Managed JSON schemas and lint rulesets
- **SDKs** — Multi-language SDK builds linked to repositories
- **Publishes** — Docs deploys with build logs, redeploys, and custom domains
- **Docs projects** — Hosted docs backed by Forgejo, GitHub, or Bitbucket, with publishes and analytics
- **Teams** — Members, roles, identity providers, access groups, secrets, and webhooks

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 88 / 100
- **Maturity:** AI-Ready
- **Dimensions:**
  - Foundational Compliance: 72 / 100
  - Developer Experience & Jentic Compatibility: 100 / 100
  - AI-Readiness & Agent Experience: 100 / 100
  - Agent Usability: 94 / 100
  - Security: 100 / 100
  - AI Discoverability: 61 / 100
- **View full report:** https://jentic.com/apis/scalar.com/scalar/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring the Scalar Core API by hand means obtaining a bearer JWT or personal token, finding the right operation among hundreds of team, registry, SDK, and docs routes, and getting namespace and slug paths right. Through Jentic you install once, import Scalar from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Scalar puts the namespace and document slug in the URL path (`/managed-doc/{namespace}/{slug}/...`), so a rule can pin your agent to one API document in one namespace. You choose the operations it may call, so destructive ones like deleteTeam or deleteManagedDocNamespaceSlug are not included unless you add them.
- **Credential handling:** Your Scalar token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'lint an OpenAPI document' or 'build an SDK', and Jentic returns the matching Scalar operation, such as postManagedDocLint or postV1SdksBuild, with its input schema.

## Related APIs

- **Stoplight API** — API design and documentation platform
- **ReadMe API** — Hosted developer documentation and API reference
- **Postman API** — Collections, workspaces, and API definitions
- **GitHub API** — Repositories and pull requests that registry resources and SDKs sync with

## FAQ

### What authentication does the Scalar Core API use?

Per its OpenAPI spec, the Scalar Core API uses a bearer JWT in the Authorization header for most operations, and the generate-personal-token operation issues a named personal token. A handful of operations need no credential, including email signup, email OTP request and verification, the team slug availability check, and the GitHub and Bitbucket OAuth callbacks. Through Jentic the token is stored by your own instance and attached at call time.

### Can the Scalar Core API lint OpenAPI documents?

Yes. The postManagedDocLint operation lints an unsaved OpenAPI or AsyncAPI document with Vacuum, taking the document as a string. Managed rulesets can be created per namespace for the rules you want to apply.

### Which SDK languages does Scalar support?

The SDK create operation accepts language targets including typescript, python, cli, csharp, java, ruby, php, go, rust, kotlin, swift, cpp, and dart.

### What are the rate limits for the Scalar Core API?

The OpenAPI spec does not specify rate limits. Check the Scalar documentation at https://scalar.com for current limits.

### Is there a Scalar MCP server?

You don't need an MCP server to give your agent the Scalar Core API. Jentic connects it directly from the API Directory: import it, store your Scalar token once, and your agent calls the registry, SDK, and docs operations it needs without loading a separate server's tool definitions.

### How do I publish a new API document version through Jentic?

Search Jentic for 'create a Scalar API document version', load the postManagedDocNamespaceSlugVersion operation, and execute POST `/managed-doc/{namespace}/{slug}/version` with your namespace, slug, and document content. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Scalar Core API?

Yes. Allow only GET and POST under `/managed-doc/acme/payments` plus POST `/managed-doc/lint`, and the agent can lint and version the payments document in the acme namespace while team settings, billing, secrets, and deletes stay off its list. Every call it makes is logged.
