Forgejo miscellaneous API
The miscellaneous API from Forgejo — 14 operation(s) for miscellaneous.
OpenAPI Specification
swagger: '2.0'
info:
description: This documentation describes the Forgejo API.
title: Forgejo activitypub miscellaneous API
license:
name: This file is distributed under the MIT license for the purpose of interoperability
url: http://opensource.org/licenses/MIT
version: 16.0.0-dev-465-4b83448b7d+gitea-1.22.0
basePath: /api/v1
schemes:
- https
- http
consumes:
- application/json
- text/plain
produces:
- application/json
- text/html
security:
- BasicAuth: []
- AuthorizationHeaderToken: []
- SudoParam: []
- SudoHeader: []
- TOTPHeader: []
tags:
- name: miscellaneous
paths:
/actions/run:
get:
description: 'The automatic actions token must be used as the authentication mechanism (<code>Authorization: Bearer ${{ forgejo.token }}</code>); other types of tokens cannot be used. The token is associated with the job, which must be still running for the request to this endpoint to succeed.
'
produces:
- application/json
tags:
- miscellaneous
summary: Get a workflow run associated with a token
operationId: getActionsRun
responses:
'200':
$ref: '#/responses/ActionRun'
/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'
/nodeinfo:
get:
produces:
- application/json
tags:
- miscellaneous
summary: Returns the nodeinfo of the Forgejo application
operationId: getNodeInfo
responses:
'200':
$ref: '#/responses/NodeInfo'
/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.ssh:
get:
produces:
- text/plain
tags:
- miscellaneous
summary: Get default signing-key.ssh
operationId: getSSHSigningKey
responses:
'200':
description: SSH public key in OpenSSH authorized key format
schema:
type: string
'404':
$ref: '#/responses/notFound'
/version:
get:
produces:
- application/json
tags:
- miscellaneous
summary: Returns the version of the running application
operationId: getVersion
responses:
'200':
$ref: '#/responses/ServerVersion'
definitions:
Team:
description: Team represents a team in an organization
type: object
properties:
can_create_org_repo:
type: boolean
x-go-name: CanCreateOrgRepo
description:
type: string
x-go-name: Description
id:
type: integer
format: int64
x-go-name: ID
includes_all_repositories:
type: boolean
x-go-name: IncludesAllRepositories
name:
type: string
x-go-name: Name
organization:
$ref: '#/definitions/Organization'
permission:
type: string
enum:
- none
- read
- write
- admin
- owner
x-go-name: Permission
units:
type: array
items:
type: string
x-go-name: Units
example:
- repo.code
- repo.issues
- repo.ext_issues
- repo.wiki
- repo.pulls
- repo.releases
- repo.projects
- repo.ext_wiki
units_map:
type: object
additionalProperties:
type: string
x-go-name: UnitsMap
example:
repo.actions: none
repo.code: read
repo.ext_issues: none
repo.ext_wiki: none
repo.issues: write
repo.packages: none
repo.projects: none
repo.pulls: owner
repo.releases: none
repo.wiki: admin
x-go-package: forgejo.org/modules/structs
Organization:
description: Organization represents an organization
type: object
properties:
avatar_url:
type: string
x-go-name: AvatarURL
created:
type: string
format: date-time
x-go-name: Created
description:
type: string
x-go-name: Description
email:
type: string
x-go-name: Email
full_name:
type: string
x-go-name: FullName
id:
type: integer
format: int64
x-go-name: ID
location:
type: string
x-go-name: Location
name:
type: string
x-go-name: Name
repo_admin_change_team_access:
type: boolean
x-go-name: RepoAdminChangeTeamAccess
username:
description: deprecated
type: string
x-go-name: UserName
visibility:
type: string
x-go-name: Visibility
website:
type: string
x-go-name: Website
x-go-package: forgejo.org/modules/structs
Permission:
description: Permission represents a set of permissions
type: object
properties:
admin:
type: boolean
x-go-name: Admin
pull:
type: boolean
x-go-name: Pull
push:
type: boolean
x-go-name: Push
x-go-package: forgejo.org/modules/structs
User:
description: User represents a user
type: object
properties:
active:
description: Is user active
type: boolean
x-go-name: IsActive
avatar_url:
description: URL to the user's avatar
type: string
x-go-name: AvatarURL
created:
type: string
format: date-time
x-go-name: Created
description:
description: the user's description
type: string
x-go-name: Description
email:
type: string
format: email
x-go-name: Email
followers_count:
description: user counts
type: integer
format: int64
x-go-name: Followers
following_count:
type: integer
format: int64
x-go-name: Following
full_name:
description: the user's full name
type: string
x-go-name: FullName
html_url:
description: URL to the user's profile page
type: string
x-go-name: HTMLURL
id:
description: the user's id
type: integer
format: int64
x-go-name: ID
is_admin:
description: Is the user an administrator
type: boolean
x-go-name: IsAdmin
language:
description: User locale
type: string
x-go-name: Language
last_login:
type: string
format: date-time
x-go-name: LastLogin
location:
description: the user's location
type: string
x-go-name: Location
login:
description: the user's username
type: string
x-go-name: UserName
login_name:
description: the user's authentication sign-in name.
type: string
default: empty
x-go-name: LoginName
prohibit_login:
description: Is user login prohibited
type: boolean
x-go-name: ProhibitLogin
pronouns:
description: the user's pronouns
type: string
x-go-name: Pronouns
restricted:
description: Is user restricted
type: boolean
x-go-name: Restricted
source_id:
description: The ID of the user's Authentication Source
type: integer
format: int64
x-go-name: SourceID
starred_repos_count:
type: integer
format: int64
x-go-name: StarredRepos
visibility:
description: 'User visibility level option: public, limited, private'
type: string
x-go-name: Visibility
website:
description: the user's website
type: string
x-go-name: Website
x-go-package: forgejo.org/modules/structs
APIValidationError:
type: object
properties:
message:
type: string
x-go-name: Message
url:
type: string
x-go-name: URL
x-go-package: forgejo.org/services/context
NodeInfoServices:
description: NodeInfoServices contains the third party sites this server can connect to via their application API
type: object
properties:
inbound:
type: array
items:
type: string
x-go-name: Inbound
outbound:
type: array
items:
type: string
x-go-name: Outbound
x-go-package: forgejo.org/modules/structs
APINotFound:
type: object
properties:
errors:
type: array
items:
type: string
x-go-name: Errors
message:
type: string
x-go-name: Message
url:
type: string
x-go-name: URL
x-go-package: forgejo.org/services/context
NodeInfoSoftware:
description: NodeInfoSoftware contains Metadata about server software in use
type: object
properties:
homepage:
type: string
x-go-name: Homepage
name:
type: string
x-go-name: Name
repository:
type: string
x-go-name: Repository
version:
type: string
x-go-name: Version
x-go-package: forgejo.org/modules/structs
Duration:
description: 'A Duration represents the elapsed time between two instants
as an int64 nanosecond count. The representation limits the
largest representable duration to approximately 290 years.'
type: integer
format: int64
x-go-package: time
LicensesTemplateListEntry:
description: LicensesListEntry is used for the API
type: object
properties:
key:
type: string
x-go-name: Key
name:
type: string
x-go-name: Name
url:
type: string
x-go-name: URL
x-go-package: forgejo.org/modules/structs
ExternalWiki:
description: ExternalWiki represents setting for external wiki
type: object
properties:
external_wiki_url:
description: URL of external wiki.
type: string
x-go-name: ExternalWikiURL
x-go-package: forgejo.org/modules/structs
ActionRun:
description: ActionRun represents an action run
type: object
properties:
ScheduleID:
description: the cron id for the schedule trigger
type: integer
format: int64
approved_by:
description: who approved this action run
type: integer
format: int64
x-go-name: ApprovedBy
commit_sha:
description: the commit sha the action run ran on
type: string
x-go-name: CommitSHA
created:
description: when the action run was created
type: string
format: date-time
x-go-name: Created
duration:
$ref: '#/definitions/Duration'
event:
description: the webhook event that causes the workflow to run
type: string
x-go-name: Event
event_payload:
description: the payload of the webhook event that causes the workflow to run
type: string
x-go-name: EventPayload
html_url:
description: the url of this action run
type: string
x-go-name: HTMLURL
id:
description: the action run id
type: integer
format: int64
x-go-name: ID
index_in_repo:
description: a unique number for each run of a repository
type: integer
format: int64
x-go-name: Index
is_fork_pull_request:
description: If this is triggered by a PR from a forked repository or an untrusted user, we need to check if it is approved and limit permissions when running the workflow.
type: boolean
x-go-name: IsForkPullRequest
is_ref_deleted:
description: has the commit/tag/… the action run ran on been deleted
type: boolean
x-go-name: IsRefDeleted
need_approval:
description: may need approval if it's a fork pull request
type: boolean
x-go-name: NeedApproval
prettyref:
description: the commit/tag/… the action run ran on
type: string
x-go-name: PrettyRef
repository:
$ref: '#/definitions/Repository'
started:
description: when the action run was started
type: string
format: date-time
x-go-name: Started
status:
description: the current status of this run
type: string
x-go-name: Status
stopped:
description: when the action run was stopped
type: string
format: date-time
x-go-name: Stopped
title:
description: the action run's title
type: string
x-go-name: Title
trigger_event:
description: the trigger event defined in the `on` configuration of the triggered workflow
type: string
x-go-name: TriggerEvent
trigger_user:
$ref: '#/definitions/User'
updated:
description: when the action run was last updated
type: string
format: date-time
x-go-name: Updated
workflow_id:
description: the name of workflow file
type: string
x-go-name: WorkflowID
x-go-package: forgejo.org/modules/structs
GitignoreTemplateInfo:
description: GitignoreTemplateInfo name and text of a gitignore template
type: object
properties:
name:
type: string
x-go-name: Name
source:
type: string
x-go-name: Source
x-go-package: forgejo.org/modules/structs
InternalTracker:
description: InternalTracker represents settings for internal tracker
type: object
properties:
allow_only_contributors_to_track_time:
description: Let only contributors track time (Built-in issue tracker)
type: boolean
x-go-name: AllowOnlyContributorsToTrackTime
enable_issue_dependencies:
description: Enable dependencies for issues and pull requests (Built-in issue tracker)
type: boolean
x-go-name: EnableIssueDependencies
enable_time_tracker:
description: Enable time tracking (Built-in issue tracker)
type: boolean
x-go-name: EnableTimeTracker
x-go-package: forgejo.org/modules/structs
LabelTemplate:
description: LabelTemplate info of a Label template
type: object
properties:
color:
type: string
x-go-name: Color
example: 00aabb
description:
type: string
x-go-name: Description
exclusive:
type: boolean
x-go-name: Exclusive
example: false
name:
type: string
x-go-name: Name
x-go-package: forgejo.org/modules/structs
LicenseTemplateInfo:
description: LicensesInfo contains information about a License
type: object
properties:
body:
type: string
x-go-name: Body
implementation:
type: string
x-go-name: Implementation
key:
type: string
x-go-name: Key
name:
type: string
x-go-name: Name
url:
type: string
x-go-name: URL
x-go-package: forgejo.org/modules/structs
ServerVersion:
description: ServerVersion wraps the version of the server
type: object
properties:
version:
type: string
x-go-name: Version
x-go-package: forgejo.org/modules/structs
ExternalTracker:
description: ExternalTracker represents settings for external tracker
type: object
properties:
external_tracker_format:
description: External Issue Tracker URL Format. Use the placeholders {user}, {repo} and {index} for the username, repository name and issue index.
type: string
x-go-name: ExternalTrackerFormat
external_tracker_regexp_pattern:
description: External Issue Tracker issue regular expression
type: string
x-go-name: ExternalTrackerRegexpPattern
external_tracker_style:
description: External Issue Tracker Number Format, either `numeric`, `alphanumeric`, or `regexp`
type: string
x-go-name: ExternalTrackerStyle
external_tracker_url:
description: URL of external issue tracker.
type: string
x-go-name: ExternalTrackerURL
x-go-package: forgejo.org/modules/structs
RepoTransfer:
description: RepoTransfer represents a pending repo transfer
type: object
properties:
doer:
$ref: '#/definitions/User'
recipient:
$ref: '#/definitions/User'
teams:
type: array
items:
$ref: '#/definitions/Team'
x-go-name: Teams
x-go-package: forgejo.org/modules/structs
NodeInfoUsageUsers:
description: NodeInfoUsageUsers contains statistics about the users of this server
type: object
properties:
activeHalfyear:
type: integer
format: int64
x-go-name: ActiveHalfyear
activeMonth:
type: integer
format: int64
x-go-name: ActiveMonth
total:
type: integer
format: int64
x-go-name: Total
x-go-package: forgejo.org/modules/structs
Repository:
description: Repository represents a repository
type: object
properties:
allow_fast_forward_only_merge:
type: boolean
x-go-name: AllowFastForwardOnly
allow_merge_commits:
type: boolean
x-go-name: AllowMerge
allow_rebase:
type: boolean
x-go-name: AllowRebase
allow_rebase_explicit:
type: boolean
x-go-name: AllowRebaseMerge
allow_rebase_update:
type: boolean
x-go-name: AllowRebaseUpdate
allow_squash_merge:
type: boolean
x-go-name: AllowSquash
archived:
type: boolean
x-go-name: Archived
archived_at:
type: string
format: date-time
x-go-name: ArchivedAt
avatar_url:
type: string
x-go-name: AvatarURL
clone_url:
type: string
x-go-name: CloneURL
created_at:
type: string
format: date-time
x-go-name: Created
default_allow_maintainer_edit:
type: boolean
x-go-name: DefaultAllowMaintainerEdit
default_branch:
type: string
x-go-name: DefaultBranch
default_delete_branch_after_merge:
type: boolean
x-go-name: DefaultDeleteBranchAfterMerge
default_merge_style:
type: string
x-go-name: DefaultMergeStyle
default_update_style:
type: string
x-go-name: DefaultUpdateStyle
description:
type: string
x-go-name: Description
empty:
type: boolean
x-go-name: Empty
external_tracker:
$ref: '#/definitions/ExternalTracker'
external_wiki:
$ref: '#/definitions/ExternalWiki'
fork:
type: boolean
x-go-name: Fork
forks_count:
type: integer
format: int64
x-go-name: Forks
full_name:
type: string
x-go-name: FullName
globally_editable_wiki:
type: boolean
x-go-name: GloballyEditableWiki
has_actions:
type: boolean
x-go-name: HasActions
has_issues:
type: boolean
x-go-name: HasIssues
has_packages:
type: boolean
x-go-name: HasPackages
has_projects:
type: boolean
x-go-name: HasProjects
has_pull_requests:
type: boolean
x-go-name: HasPullRequests
has_releases:
type: boolean
x-go-name: HasReleases
has_wiki:
description: is the wiki enabled
type: boolean
x-go-name: HasWiki
has_wiki_contents:
description: have wiki pages ever been created
type: boolean
x-go-name: HasWikiContents
html_url:
type: string
x-go-name: HTMLURL
id:
type: integer
format: int64
x-go-name: ID
ignore_whitespace_conflicts:
type: boolean
x-go-name: IgnoreWhitespaceConflicts
internal:
type: boolean
x-go-name: Internal
internal_tracker:
$ref: '#/definitions/InternalTracker'
language:
type: string
x-go-name: Language
languages_url:
type: string
x-go-name: LanguagesURL
link:
type: string
x-go-name: Link
mirror:
type: boolean
x-go-name: Mirror
mirror_interval:
type: string
x-go-name: MirrorInterval
mirror_updated:
type: string
format: date-time
x-go-name: MirrorUpdated
name:
type: string
x-go-name: Name
object_format_name:
description: ObjectFormatName of the underlying git repository
type: string
enum:
- sha1
- sha256
x-go-name: ObjectFormatName
open_issues_count:
type: integer
format: int64
x-go-name: OpenIssues
open_pr_counter:
type: integer
format: int64
x-go-name: OpenPulls
original_url:
type: string
x-go-name: OriginalURL
owner:
$ref: '#/definitions/User'
parent:
$ref: '#/definitions/Repository'
permissions:
$ref: '#/definitions/Permission'
private:
type: boolean
x-go-name: Private
release_counter:
type: integer
format: int64
x-go-name: Releases
repo_transfer:
$ref: '#/definitions/RepoTransfer'
size:
type: integer
format: int64
x-go-name: Size
ssh_url:
type: string
x-go-name: SSHURL
stars_count:
type: integer
format: int64
x-go-name: Stars
template:
type: boolean
x-go-name: Template
topics:
type: array
items:
type: string
x-go-name: Topics
updated_at:
type: string
format: date-time
x-go-name: Updated
url:
type: string
x-go-name: URL
watchers_count:
type: integer
format: int64
x-go-name: Watchers
website:
type: string
x-go-name: Website
wiki_branch:
type: string
x-go-name: WikiBranch
wiki_clone_url:
type: string
x-go-name: WikiCloneURL
wiki_ssh_url:
type: string
x-go-name: WikiSSHURL
x-go-package: forgejo.org/modules/structs
NodeInfoUsage:
description: NodeInfoUsage contains usage statistics for this server
type: object
properties:
localComments:
type: integer
format: int64
x-go-name: LocalComments
localPosts:
type: integer
format: int64
x-go-name: LocalPosts
users:
$ref: '#/definitions/NodeInfoUsageUsers'
x-go-package: forgejo.org/modules/structs
MarkdownOption:
description: MarkdownOption markdown options
type: object
properties:
Context:
description: Context to render
type: string
Mode:
description: Mode to render (comment, gfm, markdown)
type: string
Text:
description: Text markdown to render
type: string
Wiki:
description: Is it a wiki page ?
type: boolean
x-go-package: forgejo.org/modules/structs
NodeInfo:
description: NodeInfo contains standardized way of exposing metadata about a server running one of the distributed social networks
type: object
properties:
metadata:
type: object
x-go-name: Metadata
openRegistrations:
type: boolean
x-go-name: OpenRegistrations
protocols:
type: array
items:
type: string
x-go-name: Protocols
services:
$ref: '#/definitions/NodeInfoServices'
software:
$ref: '#/definitions/NodeInfoSoftware'
usage:
$ref: '#/definitions/NodeInfoUsage'
version:
type: string
x-go-name: Version
x-go-package: forgejo.org/modules/structs
MarkupOption:
description: MarkupOption markup options
type: object
properties:
BranchPath:
description: The current branch path where the form gets posted
type: string
Context:
description: Context to render
type: string
FilePath:
description: File path for detecting extension in file mode
type: string
Mode:
description: Mode to render (comment, gfm, markdown, file)
type: string
Text:
description: Text markup to render
type: string
Wiki:
description: Is it a wiki page ?
type: boolean
x-go-package: forgejo.org/modules/structs
responses:
ServerVersion:
description: ServerVersion
schema:
$ref: '#/definitions/ServerVersion'
LabelTemplateList:
description: LabelTemplateList
schema:
type: array
items:
type: string
NodeInfo:
description: NodeInfo
schema:
$ref: '#/definitions/NodeInfo'
MarkdownRender:
description: MarkdownRender is a rendered markdown document
schema:
type: string
ActionRun:
description: ActionRun
schema:
$ref: '#/definitions/ActionRun'
validationError:
description: APIValidationError is error format response related to input validation
schema:
$ref: '#/definitions/APIValidationError'
GitignoreTemplateList:
description: GitignoreTemplateList
schema:
type: array
items:
type: string
MarkupRender:
description: MarkupRender is a rendered markup document
schema:
type: string
notFound:
description: APINotFound is a not found error response
schema:
$ref: '#/definitions/APINotFound'
GitignoreTemplateInfo:
description: GitignoreTemplateInfo
schema:
$ref: '#/definitions/GitignoreTemplateInfo'
LicenseTemplateList:
description: LicenseTemplateList
schema:
type: array
items:
$ref: '#/definitions/LicensesTemplateListEntry'
LicenseTemplateInfo:
description: LicenseTemplateInfo
schema:
$ref: '#/definitions/LicenseTemplateInfo'
LabelTemplateInfo:
description: LabelTemplateInfo
schema:
type: array
items:
$ref: '#/definitions/LabelTemplate'
securityDefinitions:
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-FORGEJO-OTP
in: header