Scalar Docs Projects API
The Docs Projects API from Scalar — 9 operation(s) for docs projects.
OpenAPI Specification
openapi: 3.1.1
info:
title: Core access-groups Docs Projects API
description: Core services for Scalar
version: 1.0.1
contact:
name: Marc from Scalar
url: https://scalar.com
email: support@scalar.com
security:
- BearerAuth: []
tags:
- name: Docs Projects
paths:
/docs-projects/create:
post:
description: Create a unified DocsProject backed by the chosen VCS provider (forgejo, github, or bitbucket)
operationId: postdocsProjectsCreate
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/docs-project'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 255
slug:
$ref: '#/components/schemas/slug'
isPrivate:
default: false
type: boolean
provider:
type: string
enum:
- forgejo
- github
- bitbucket
githubRepository:
type: object
properties:
installationId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
repoId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- installationId
- repoId
additionalProperties: false
bitbucketRepository:
type: object
properties:
workspaceUuid:
type: string
repoUuid:
type: string
required:
- workspaceUuid
- repoUuid
additionalProperties: false
required:
- name
- isPrivate
- provider
additionalProperties: false
required: true
tags:
- Docs Projects
/docs-projects/delete:
delete:
description: Delete a unified DocsProject. Tears down deploys + publish records + cached builds, repoints user activeProjectUid, deletes the Forgejo repo (if any), and notifies subscribers. User-owned GitHub repos are left untouched.
operationId: deletedocsProjectsDelete
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: 'null'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
type: object
properties:
projectUid:
$ref: '#/components/schemas/nanoid'
required:
- projectUid
additionalProperties: false
required: true
tags:
- Docs Projects
/docs-projects/{slug}:
get:
description: Get a unified DocsProject by slug for the current team
operationId: getdocsProjectsSlug
responses:
'200':
description: Default Response
content:
application/json:
schema:
$ref: '#/components/schemas/docs-project'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
parameters:
- schema:
$ref: '#/components/schemas/slug'
in: path
name: slug
required: true
tags:
- Docs Projects
/docs-projects/update-repo-settings:
post:
description: Update editable repository settings (tracked branch, config path) on a unified DocsProject. Publish flags live in scalar.config.json.
operationId: postdocsProjectsUpdateRepoSettings
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: 'null'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
type: object
properties:
projectUid:
$ref: '#/components/schemas/nanoid'
branch:
type: string
minLength: 1
configPath:
type: string
required:
- projectUid
additionalProperties: false
required: true
tags:
- Docs Projects
/docs-projects/{projectUid}/link-github:
post:
description: Convert a Forgejo-backed DocsProject into a GitHub-backed one. Reads every file from the Forgejo repo and opens a single PR on the chosen GitHub repo putting the content under scalar-docs/.
operationId: postdocsProjectsProjectUidLinkGithub
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
pullRequest:
type: object
properties:
url:
type: string
number:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
branch:
type: string
required:
- url
- number
- branch
additionalProperties: false
project:
$ref: '#/components/schemas/docs-project'
required:
- pullRequest
- project
additionalProperties: false
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
type: object
properties:
installationId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
repoId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- installationId
- repoId
additionalProperties: false
required: true
parameters:
- schema:
$ref: '#/components/schemas/nanoid'
in: path
name: projectUid
required: true
tags:
- Docs Projects
/docs-projects/{projectUid}/unlink-github:
post:
description: Convert a GitHub-backed DocsProject back to a Forgejo-backed one. Migrates the GitHub repository contents into a fresh Forgejo repo and flips the project provider.
operationId: postdocsProjectsProjectUidUnlinkGithub
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/docs-project'
required:
- project
additionalProperties: false
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
parameters:
- schema:
$ref: '#/components/schemas/nanoid'
in: path
name: projectUid
required: true
tags:
- Docs Projects
/docs-projects/{projectUid}/link-bitbucket:
post:
description: Convert a Forgejo-backed DocsProject into a Bitbucket-backed one. Reads every file from the Forgejo repo and opens a single PR on the chosen Bitbucket repo putting the content under scalar-docs/.
operationId: postdocsProjectsProjectUidLinkBitbucket
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
pullRequest:
type: object
properties:
url:
type: string
number:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
branch:
type: string
required:
- url
- number
- branch
additionalProperties: false
project:
$ref: '#/components/schemas/docs-project'
required:
- pullRequest
- project
additionalProperties: false
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
type: object
properties:
workspaceUuid:
type: string
repoUuid:
type: string
required:
- workspaceUuid
- repoUuid
additionalProperties: false
required: true
parameters:
- schema:
$ref: '#/components/schemas/nanoid'
in: path
name: projectUid
required: true
tags:
- Docs Projects
/docs-projects/{projectUid}/unlink-bitbucket:
post:
description: Convert a Bitbucket-backed DocsProject back to a Forgejo-backed one. Migrates the Bitbucket repository contents into a fresh Forgejo repo and flips the project provider.
operationId: postdocsProjectsProjectUidUnlinkBitbucket
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/docs-project'
required:
- project
additionalProperties: false
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
parameters:
- schema:
$ref: '#/components/schemas/nanoid'
in: path
name: projectUid
required: true
tags:
- Docs Projects
/docs-projects/{projectUid}/bitbucket/refresh-webhook:
post:
description: Re-register the Bitbucket webhook on a Bitbucket-backed DocsProject. Used to recover from a failed initial registration after the linker user is granted repo admin.
operationId: postdocsProjectsProjectUidBitbucketRefreshWebhook
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
project:
$ref: '#/components/schemas/docs-project'
required:
- project
additionalProperties: false
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: No auth
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/404'
'422':
description: Invalid payload
content:
application/json:
schema:
$ref: '#/components/schemas/422'
'500':
description: Uncaught error
content:
application/json:
schema:
$ref: '#/components/schemas/500'
parameters:
- schema:
$ref: '#/components/schemas/nanoid'
in: path
name: projectUid
required: true
tags:
- Docs Projects
components:
schemas:
docs-project-repository-github:
type: object
properties:
provider:
type: string
const: github
linkedBy:
type: string
installationId:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
id:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
name:
type: string
minLength: 2
branch:
default: main
type: string
configPath:
default: scalar.config.json
type: string
publishOnMerge:
default: true
type: boolean
publishPreviews:
default: false
type: boolean
prComments:
default: false
type: boolean
expired:
default: false
type: boolean
required:
- provider
- linkedBy
- installationId
- id
- name
- branch
- configPath
- publishOnMerge
- publishPreviews
- prComments
- expired
additionalProperties: false
docs-project-repository-forgejo:
type: object
properties:
provider:
type: string
const: forgejo
forgejoOwner:
type: string
forgejoRepo:
type: string
branch:
default: main
type: string
configPath:
default: scalar.config.json
type: string
required:
- provider
- forgejoOwner
- forgejoRepo
- branch
- configPath
additionalProperties: false
nanoid:
type: string
minLength: 5
'404':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
'401':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
slug:
type: string
minLength: 3
maxLength: 60
pattern: ^[a-z](?:[a-z0-9-]*[a-z0-9])?$
docs-project:
type: object
properties:
uid:
default: nanoid()
$ref: '#/components/schemas/nanoid'
createdAt:
default: unixTimestamp()
$ref: '#/components/schemas/timestamp'
updatedAt:
default: unixTimestamp()
$ref: '#/components/schemas/timestamp'
name:
type: string
activeDeployment:
default: null
anyOf:
- $ref: '#/components/schemas/active-deployment'
- type: 'null'
lastPublished:
default: null
anyOf:
- $ref: '#/components/schemas/timestamp'
- type: 'null'
lastPublishedUid:
default: null
anyOf:
- type: string
- type: 'null'
loginPortalUid:
default: ''
type: string
activeThemeId:
default: ''
type: string
typesenseId:
type: number
isPrivate:
default: false
type: boolean
agentEnabled:
default: false
type: boolean
analyticsEnabled:
default: true
type: boolean
accessGroups:
default: []
slug:
$ref: '#/components/schemas/slug'
publishStatus:
default: ''
type: string
publishMessage:
default: ''
type: string
repository:
oneOf:
- $ref: '#/components/schemas/docs-project-repository-forgejo'
- $ref: '#/components/schemas/docs-project-repository-github'
- $ref: '#/components/schemas/docs-project-repository-bitbucket'
required:
- uid
- createdAt
- updatedAt
- name
- activeDeployment
- lastPublished
- lastPublishedUid
- loginPortalUid
- activeThemeId
- isPrivate
- agentEnabled
- analyticsEnabled
- accessGroups
- slug
- publishStatus
- publishMessage
- repository
additionalProperties: false
'500':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
active-deployment:
type: object
properties:
uid:
type: string
domain:
type: string
publishedAt:
$ref: '#/components/schemas/timestamp'
required:
- uid
- domain
- publishedAt
additionalProperties: false
'400':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
'403':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
timestamp:
type: integer
minimum: 0
maximum: 9007199254740991
'422':
type: object
properties:
message:
type: string
code:
type: string
required:
- message
- code
docs-project-repository-bitbucket:
type: object
properties:
provider:
type: string
const: bitbucket
linkedBy:
type: string
workspaceUuid:
type: string
workspaceSlug:
type: string
repoUuid:
type: string
repoSlug:
type: string
name:
type: string
minLength: 2
branch:
default: main
type: string
configPath:
default: scalar.config.json
type: string
publishOnMerge:
default: true
type: boolean
publishPreviews:
default: false
type: boolean
prComments:
default: false
type: boolean
expired:
default: false
type: boolean
webhookUuid:
default: ''
type: string
required:
- provider
- linkedBy
- workspaceUuid
- workspaceSlug
- repoUuid
- repoSlug
- name
- branch
- configPath
- publishOnMerge
- publishPreviews
- prComments
- expired
- webhookUuid
additionalProperties: false
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT