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 (Authorization: Bearer ${{ forgejo.token }}); 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