swagger: '2.0'
info:
  description: This documentation describes the Gitea API.
  title: Gitea admin miscellaneous API
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
  version: 1.27.0+dev-89-gf52b6f3315
basePath: /api/v1
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
security:
- BasicAuth: []
- Token: []
- AccessToken: []
- AuthorizationHeaderToken: []
- SudoParam: []
- SudoHeader: []
- TOTPHeader: []
tags:
- name: miscellaneous
paths:
  /gitignore/templates:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns a list of all gitignore templates
      operationId: listGitignoresTemplates
      responses:
        '200':
          $ref: '#/responses/GitignoreTemplateList'
  /gitignore/templates/{name}:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns information about a gitignore template
      operationId: getGitignoreTemplateInfo
      parameters:
      - type: string
        description: name of the template
        name: name
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/GitignoreTemplateInfo'
        '404':
          $ref: '#/responses/notFound'
  /label/templates:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns a list of all label templates
      operationId: listLabelTemplates
      responses:
        '200':
          $ref: '#/responses/LabelTemplateList'
  /label/templates/{name}:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns all labels in a template
      operationId: getLabelTemplateInfo
      parameters:
      - type: string
        description: name of the template
        name: name
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/LabelTemplateInfo'
        '404':
          $ref: '#/responses/notFound'
  /licenses:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns a list of all license templates
      operationId: listLicenseTemplates
      responses:
        '200':
          $ref: '#/responses/LicenseTemplateList'
  /licenses/{name}:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns information about a license template
      operationId: getLicenseTemplateInfo
      parameters:
      - type: string
        description: name of the license
        name: name
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/LicenseTemplateInfo'
        '404':
          $ref: '#/responses/notFound'
  /markdown:
    post:
      consumes:
      - application/json
      produces:
      - text/html
      tags:
      - miscellaneous
      summary: Render a markdown document as HTML
      operationId: renderMarkdown
      parameters:
      - name: body
        in: body
        schema:
          $ref: '#/definitions/MarkdownOption'
      responses:
        '200':
          $ref: '#/responses/MarkdownRender'
        '422':
          $ref: '#/responses/validationError'
  /markdown/raw:
    post:
      consumes:
      - text/plain
      produces:
      - text/html
      tags:
      - miscellaneous
      summary: Render raw markdown as HTML
      operationId: renderMarkdownRaw
      parameters:
      - description: Request body to render
        name: body
        in: body
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/responses/MarkdownRender'
        '422':
          $ref: '#/responses/validationError'
  /markup:
    post:
      consumes:
      - application/json
      produces:
      - text/html
      tags:
      - miscellaneous
      summary: Render a markup document as HTML
      operationId: renderMarkup
      parameters:
      - name: body
        in: body
        schema:
          $ref: '#/definitions/MarkupOption'
      responses:
        '200':
          $ref: '#/responses/MarkupRender'
        '422':
          $ref: '#/responses/validationError'
  /signing-key.gpg:
    get:
      produces:
      - text/plain
      tags:
      - miscellaneous
      summary: Get default signing-key.gpg
      operationId: getSigningKey
      responses:
        '200':
          description: GPG armored public key
          schema:
            type: string
  /signing-key.pub:
    get:
      produces:
      - text/plain
      tags:
      - miscellaneous
      summary: Get default signing-key.pub
      operationId: getSigningKeySSH
      responses:
        '200':
          description: ssh public key
          schema:
            type: string
  /version:
    get:
      produces:
      - application/json
      tags:
      - miscellaneous
      summary: Returns the version of the Gitea application
      operationId: getVersion
      responses:
        '200':
          $ref: '#/responses/ServerVersion'
definitions:
  LicenseTemplateInfo:
    description: LicensesInfo contains information about a License
    type: object
    properties:
      body:
        description: Body contains the full text of the license
        type: string
        x-go-name: Body
      implementation:
        description: Implementation contains license implementation details
        type: string
        x-go-name: Implementation
      key:
        description: Key is the unique identifier for the license template
        type: string
        x-go-name: Key
      name:
        description: Name is the display name of the license
        type: string
        x-go-name: Name
      url:
        description: URL is the reference URL for the license
        type: string
        x-go-name: URL
    x-go-package: code.gitea.io/gitea/modules/structs
  MarkupOption:
    description: MarkupOption markup options
    type: object
    properties:
      Context:
        description: 'URL path for rendering issue, media and file links

          Expected format: /subpath/{user}/{repo}/src/{branch, commit, tag}/{identifier/path}/{file/dir}


          in: body'
        type: string
      FilePath:
        description: 'File path for detecting extension in file mode


          in: body'
        type: string
      Mode:
        description: 'Mode to render (markdown, comment, wiki, file)


          in: body'
        type: string
      Text:
        description: 'Text markup to render


          in: body'
        type: string
      Wiki:
        description: 'Is it a wiki page? (use mode=wiki instead)


          Deprecated: true

          in: body'
        type: boolean
    x-go-package: code.gitea.io/gitea/modules/structs
  LabelTemplate:
    description: LabelTemplate info of a Label template
    type: object
    properties:
      color:
        type: string
        x-go-name: Color
        example: 00aabb
      description:
        description: Description provides additional context about the label template's purpose
        type: string
        x-go-name: Description
      exclusive:
        type: boolean
        x-go-name: Exclusive
        example: false
      name:
        description: Name is the display name of the label template
        type: string
        x-go-name: Name
    x-go-package: code.gitea.io/gitea/modules/structs
  GitignoreTemplateInfo:
    description: GitignoreTemplateInfo name and text of a gitignore template
    type: object
    properties:
      name:
        description: Name is the name of the gitignore template
        type: string
        x-go-name: Name
      source:
        description: Source contains the content of the gitignore template
        type: string
        x-go-name: Source
    x-go-package: code.gitea.io/gitea/modules/structs
  LicensesTemplateListEntry:
    description: LicensesListEntry is used for the API
    type: object
    properties:
      key:
        description: Key is the unique identifier for the license template
        type: string
        x-go-name: Key
      name:
        description: Name is the display name of the license
        type: string
        x-go-name: Name
      url:
        description: URL is the reference URL for the license
        type: string
        x-go-name: URL
    x-go-package: code.gitea.io/gitea/modules/structs
  MarkdownOption:
    description: MarkdownOption markdown options
    type: object
    properties:
      Context:
        description: 'URL path for rendering issue, media and file links

          Expected format: /subpath/{user}/{repo}/src/{branch, commit, tag}/{identifier/path}/{file/dir}


          in: body'
        type: string
      Mode:
        description: 'Mode to render (markdown, comment, wiki, file)


          in: body'
        type: string
      Text:
        description: 'Text markdown to render


          in: body'
        type: string
      Wiki:
        description: 'Is it a wiki page? (use mode=wiki instead)


          Deprecated: true

          in: body'
        type: boolean
    x-go-package: code.gitea.io/gitea/modules/structs
  ServerVersion:
    description: ServerVersion wraps the version of the server
    type: object
    properties:
      version:
        description: Version is the server version string
        type: string
        x-go-name: Version
    x-go-package: code.gitea.io/gitea/modules/structs
responses:
  GitignoreTemplateList:
    description: GitignoreTemplateList
    schema:
      type: array
      items:
        type: string
  LabelTemplateList:
    description: LabelTemplateList
    schema:
      type: array
      items:
        type: string
  MarkdownRender:
    description: MarkdownRender is a rendered markdown document
    schema:
      type: string
  MarkupRender:
    description: MarkupRender is a rendered markup document
    schema:
      type: string
  validationError:
    description: APIValidationError is error format response related to input validation
    headers:
      message:
        type: string
      url:
        type: string
  ServerVersion:
    description: ServerVersion
    schema:
      $ref: '#/definitions/ServerVersion'
  LabelTemplateInfo:
    description: LabelTemplateInfo
    schema:
      type: array
      items:
        $ref: '#/definitions/LabelTemplate'
  notFound:
    description: APINotFound is a not found empty response
  LicenseTemplateInfo:
    description: LicenseTemplateInfo
    schema:
      $ref: '#/definitions/LicenseTemplateInfo'
  LicenseTemplateList:
    description: LicenseTemplateList
    schema:
      type: array
      items:
        $ref: '#/definitions/LicensesTemplateListEntry'
  GitignoreTemplateInfo:
    description: GitignoreTemplateInfo
    schema:
      $ref: '#/definitions/GitignoreTemplateInfo'
securityDefinitions:
  AccessToken:
    description: This authentication option is deprecated for removal in Gitea 1.23. Please use AuthorizationHeaderToken instead.
    type: apiKey
    name: access_token
    in: query
  AuthorizationHeaderToken:
    description: API tokens must be prepended with "token" followed by a space.
    type: apiKey
    name: Authorization
    in: header
  BasicAuth:
    type: basic
  SudoHeader:
    description: Sudo API request as the user provided as the key. Admin privileges are required.
    type: apiKey
    name: Sudo
    in: header
  SudoParam:
    description: Sudo API request as the user provided as the key. Admin privileges are required.
    type: apiKey
    name: sudo
    in: query
  TOTPHeader:
    description: Must be used in combination with BasicAuth if two-factor authentication is enabled.
    type: apiKey
    name: X-GITEA-OTP
    in: header
  Token:
    description: This authentication option is deprecated for removal in Gitea 1.23. Please use AuthorizationHeaderToken instead.
    type: apiKey
    name: token
    in: query