api.md

Scalar Python API

Complete reference of every operation, grouped by resource. See the README for usage and configuration.

Contents

• Registry
  • List all API Documents
  • List API Documents in a namespace
  • Create API Document
  • Update API Document metadata
  • Delete API Document
  • Get API Document
  • Update API Document version
  • Delete API Document version
  • Get API Document version metadata
  • Create API Document version
  • Add access group
  • Remove access group
• Schemas
  • List all shared components
  • Create a shared component
  • Update shared component metadata
  • Delete a shared component
  • Schemas Version
    • Get a shared component document
    • Delete a shared component version
    • Create a shared component version
  • Schemas AccessGroup
    • Add shared component access group
    • Remove shared component access group
• LoginPortals
  • Get a login portal
  • Update portal metadata
  • Delete a login portal
  • Create a portal
  • List all portals
• Rules
  • List all rules
  • Create a rule
  • Update rule metadata
  • Delete a rule
  • Get a rule
  • Add rule access group
  • Remove rule access group
• Themes
  • List all themes
  • Create a theme
  • Update theme metadata
  • Update theme document
  • Delete a theme
  • Get a theme
• Teams
  • List teams
• ScalarDocs
  • List all projects
  • Create a project
  • Publish a project
• Namespaces
  • List namespaces
• Authentication
  • Exchange token
  • Get current user

Setup

import os

from scalar_sdk import Scalar

client = Scalar(
    bearer_auth=os.environ.get("BEARER_AUTH"),
)

Registry

List all API Documents

List all API documents across every namespace the caller can access.

Direction	Type
Response	RegistryListAllAPIDocumentsResponse

registry = client.registry.list_all_api_documents()

List API Documents in a namespace

List API documents in a namespace.

Direction	Type
Response	RegistryListAPIDocumentsResponse

registry = client.registry.list_api_documents(
    namespace="namespace",
)

Create API Document

Create an API document.

Direction	Type
Request	RegistryCreateAPIDocumentParams
Response	RegistryCreateAPIDocumentResponse

registry = client.registry.create_api_document(
    namespace="namespace",
    title="",
    version="x",
    slug="",
    document="",
)

Update API Document metadata

Update metadata for an API document.

Direction	Type
Request	RegistryUpdateAPIDocumentParams
Response	RegistryUpdateAPIDocumentResponse

registry = client.registry.update_api_document(
    namespace="namespace",
    slug="slug",
)

Delete API Document

Delete an API document and all versions.

Direction	Type
Response	RegistryDeleteAPIDocumentResponse

registry = client.registry.delete_api_document(
    namespace="namespace",
    slug="slug",
)

Get API Document

Get a specific API document version.

Direction	Type
Response	RegistryRetrieveAPIDocumentVersionResponse

registry = client.registry.retrieve_api_document_version(
    namespace="namespace",
    slug="slug",
    semver="semver",
)

Update API Document version

Update the registry file content for an API document version.

Direction	Type
Request	RegistryUpdateAPIDocumentVersionParams
Response	RegistryUpdateAPIDocumentVersionResponse

registry = client.registry.update_api_document_version(
    namespace="namespace",
    slug="slug",
    semver="semver",
    document="",
)

Delete API Document version

Delete a specific API document version.

Direction	Type
Response	RegistryDeleteAPIDocumentVersionResponse

registry = client.registry.delete_api_document_version(
    namespace="namespace",
    slug="slug",
    semver="semver",
)

Get API Document version metadata

Get metadata (uid, content shas, version sha, tags) for a specific API document version.

Direction	Type
Response	RegistryListAPIDocumentVersionMetadataResponse

registry = client.registry.list_api_document_version_metadata(
    namespace="namespace",
    slug="slug",
    semver="semver",
)

Create API Document version

Create a new API document version.

Direction	Type
Request	RegistryCreateAPIDocumentVersionParams
Response	RegistryCreateAPIDocumentVersionResponse

registry = client.registry.create_api_document_version(
    namespace="namespace",
    slug="slug",
    version="x",
    document="",
)

Add access group

Add an access group to an API document.

Direction	Type
Request	RegistryCreateAPIDocumentAccessGroupParams
Response	RegistryCreateAPIDocumentAccessGroupResponse

registry = client.registry.create_api_document_access_group(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

Remove access group

Remove an access group from an API document.

Direction	Type
Request	RegistryDeleteAPIDocumentAccessGroupParams
Response	RegistryDeleteAPIDocumentAccessGroupResponse

registry = client.registry.delete_api_document_access_group(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

Schemas

List all shared components

List schemas in a namespace.

Direction	Type
Response	SchemaListResponse

schema = client.schemas.list(
    namespace="namespace",
)

Create a shared component

Create a schema in a namespace.

Direction	Type
Request	SchemaCreateParams
Response	SchemaCreateResponse

schema = client.schemas.create(
    namespace="namespace",
    title="",
    version="x",
    slug="",
    document="",
)

Update shared component metadata

Update schema metadata.

Direction	Type
Request	SchemaUpdateParams
Response	SchemaUpdateResponse

schema = client.schemas.update(
    namespace="namespace",
    slug="slug",
)

Delete a shared component

Delete a schema and all related versions.

Direction	Type
Response	SchemaDeleteResponse

schema = client.schemas.delete(
    namespace="namespace",
    slug="slug",
)

Schemas Version

Get a shared component document

Get a specific schema version document.

Direction	Type
Response	VersionRetrieveSchemaResponse

version = client.schemas.version.retrieve_schema(
    namespace="namespace",
    slug="slug",
    semver="semver",
)

Delete a shared component version

Delete a schema version.

Direction	Type
Response	VersionDeleteSchemaResponse

version = client.schemas.version.delete_schema(
    namespace="namespace",
    slug="slug",
    semver="semver",
)

Create a shared component version

Create a schema version.

Direction	Type
Request	VersionCreateSchemaParams
Response	VersionCreateSchemaResponse

version = client.schemas.version.create_schema(
    namespace="namespace",
    slug="slug",
    version="x",
    document="",
)

Schemas AccessGroup

Add shared component access group

Add an access group to a schema.

Direction	Type
Request	AccessGroupCreateSchemaParams
Response	AccessGroupCreateSchemaResponse

access_group = client.schemas.access_group.create_schema(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

Remove shared component access group

Remove an access group from a schema.

Direction	Type
Request	AccessGroupDeleteSchemaParams
Response	AccessGroupDeleteSchemaResponse

access_group = client.schemas.access_group.delete_schema(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

LoginPortals

Get a login portal

Get a login portal by slug.

Direction	Type
Response	LoginPortalRetrieveResponse

login_portal = client.login_portals.retrieve(
    slug="slug",
)

Update portal metadata

Update metadata for a login portal.

Direction	Type
Request	LoginPortalUpdateParams
Response	LoginPortalUpdateResponse

login_portal = client.login_portals.update(
    slug="slug",
)

Delete a login portal

Delete a login portal.

Direction	Type
Response	LoginPortalDeleteResponse

login_portal = client.login_portals.delete(
    slug="slug",
)

Create a portal

Create a login portal for the current team.

Direction	Type
Request	LoginPortalCreateParams
Response	LoginPortalCreateResponse

login_portal = client.login_portals.create(
    title="",
    slug="",
    email={"logo": "", "logo_size": "100", "button_text": "Login", "message": "Click to access private documentation hosted by scalar.com", "title": "Private Docs", "main_color": "#2a2f45", "main_background": "#f6f6f6", "card_color": "2a2f45", "card_background": "#fff", "button_color": "#fff", "button_background": "#0f0f0f"},
    page={"title": "Scalar Private Docs", "description": "Login to access your documentation", "head": "", "script": "", "theme": "", "company_name": "", "logo": "", "logo_url": "", "favicon": "", "terms_link": "", "privacy_link": "", "form_title": "Scalar Private Docs", "form_description": "Login to access your documentation", "form_image": ""},
)

List all portals

List all login portals for the current team.

Direction	Type
Response	LoginPortalListResponse

login_portal = client.login_portals.list()

Rules

List all rules

List all rulesets in a namespace.

Direction	Type
Response	RuleListRulesetsResponse

rule = client.rules.list_rulesets(
    namespace="namespace",
)

Create a rule

Create a rule in a namespace.

Direction	Type
Request	RuleCreateRulesetParams
Response	RuleCreateRulesetResponse

rule = client.rules.create_ruleset(
    namespace="namespace",
    title="",
    slug="",
    document="",
)

Update rule metadata

Update rule metadata by slug.

Direction	Type
Request	RuleUpdateRulesetParams
Response	RuleUpdateRulesetResponse

rule = client.rules.update_ruleset(
    path_namespace="namespace",
    path_slug="slug",
)

Delete a rule

Delete a rule by slug.

Direction	Type
Response	RuleDeleteRulesetResponse

rule = client.rules.delete_ruleset(
    namespace="namespace",
    slug="slug",
)

Get a rule

Get a rule document by slug.

Direction	Type
Response	RuleRetrieveRulesetDocumentResponse

rule = client.rules.retrieve_ruleset_document(
    namespace="namespace",
    slug="slug",
)

Add rule access group

Grant an access group to a rule.

Direction	Type
Request	RuleCreateRulesetAccessGroupParams
Response	RuleCreateRulesetAccessGroupResponse

rule = client.rules.create_ruleset_access_group(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

Remove rule access group

Remove an access group from a rule.

Direction	Type
Request	RuleDeleteRulesetAccessGroupParams
Response	RuleDeleteRulesetAccessGroupResponse

rule = client.rules.delete_ruleset_access_group(
    namespace="namespace",
    slug="slug",
    access_group_slug="xxx",
)

Themes

List all themes

List all team themes.

Direction	Type
Response	ThemeListResponse

theme = client.themes.list()

Create a theme

Create a team theme.

Direction	Type
Request	ThemeCreateParams
Response	ThemeCreateResponse

theme = client.themes.create(
    name="",
    slug="",
    document="",
)

Update theme metadata

Update theme metadata.

Direction	Type
Request	ThemeUpdateParams
Response	ThemeUpdateResponse

theme = client.themes.update(
    slug="slug",
)

Update theme document

Replace the theme document.

Direction	Type
Request	ThemeReplaceDocumentParams
Response	ThemeReplaceDocumentResponse

theme = client.themes.replace_document(
    slug="slug",
    document="",
)

Delete a theme

Delete a theme by slug.

Direction	Type
Response	ThemeDeleteResponse

theme = client.themes.delete(
    slug="slug",
)

Get a theme

Get the theme document by slug.

Direction	Type
Response	ThemeRetrieveResponse

theme = client.themes.retrieve(
    slug="slug",
)

Teams

List teams

List all available teams

Direction	Type
Response	TeamListResponse

team = client.teams.list()

ScalarDocs

List all projects

List all guide projects.

Direction	Type
Response	ScalarDocListGuidesResponse

scalar_doc = client.scalar_docs.list_guides()

Create a project

Create a guide project.

Direction	Type
Request	ScalarDocCreateGuideParams
Response	ScalarDocCreateGuideResponse

scalar_doc = client.scalar_docs.create_guide(
    name="",
    is_private=False,
    allowed_users=[],
    allowed_domains=[],
)

Publish a project

Start a new publish process.

Direction	Type
Response	ScalarDocPublishGuideResponse

scalar_doc = client.scalar_docs.publish_guide(
    slug="slug",
)

Namespaces

List namespaces

Get all namespaces for the current team

Direction	Type
Response	NamespaceListResponse

namespace = client.namespaces.list()

Authentication

Exchange token

Exchange an API key for an access token.

Direction	Type
Request	AuthenticationExchangePersonalTokenParams
Response	AuthenticationExchangePersonalTokenResponse

authentication = client.authentication.exchange_personal_token(
    personal_token="",
)

Get current user

Get the authenticated user, including their available teams and theme.

Direction	Type
Response	AuthenticationListCurrentUserResponse

authentication = client.authentication.list_current_user()