openapi: 3.2.0 info: title: Gogs Repositories API version: v1 description: RESTful API for interacting with your Gogs instance. Follows a format similar to the GitHub REST API v3. servers: - url: https://gogs.example.com/api/v1 security: - AccessToken: [] tags: - name: Repositories description: Create, search, and manage repositories, branches, commits, and contents paths: /repos/search: get: operationId: searchRepos summary: Search repositories tags: - Repositories responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Repository' ok: type: boolean parameters: - name: q in: query required: true schema: type: string description: Search keyword - name: uid in: query required: false schema: type: integer description: User ID to filter by - name: limit in: query required: false schema: type: integer default: 10 description: Max results - name: page in: query required: false schema: type: integer default: 1 description: Page number /user/repos: get: operationId: listYourRepos summary: List your repositories tags: - Repositories responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Repository' post: operationId: createRepo summary: Create a repository tags: - Repositories responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Repository' '422': description: Validation error. requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string private: type: boolean default: false auto_init: type: boolean default: false gitignores: type: string license: type: string readme: type: string default: Default required: - name /users/{username}/repos: get: operationId: listUserRepos summary: List user repositories tags: - Repositories responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Repository' '404': description: Resource not found. parameters: - name: username in: path required: true schema: type: string description: Username /orgs/{orgname}/repos: get: operationId: listOrgRepos summary: List organization repositories tags: - Repositories responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Repository' '404': description: Resource not found. parameters: - name: orgname in: path required: true schema: type: string description: Organization name /org/{org}/repos: post: operationId: createOrgRepo summary: Create a repository in an organization tags: - Repositories responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Repository' '404': description: Resource not found. '422': description: Validation error. parameters: - name: org in: path required: true schema: type: string description: Organization name requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string private: type: boolean default: false auto_init: type: boolean default: false gitignores: type: string license: type: string readme: type: string default: Default required: - name description: The authenticated user must be an owner of the specified organization. /repos/migrate: post: operationId: migrateRepo summary: Migrate a repository tags: - Repositories responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/Repository' '422': description: Validation error. requestBody: required: true content: application/json: schema: type: object properties: clone_addr: type: string auth_username: type: string auth_password: type: string uid: type: integer repo_name: type: string mirror: type: boolean default: false private: type: boolean default: false description: type: string required: - clone_addr - uid - repo_name /repos/{owner}/{repo}: get: operationId: getRepo summary: Get a repository tags: - Repositories responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Repository' '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name delete: operationId: deleteRepo summary: Delete a repository tags: - Repositories responses: '204': description: The resource has been successfully deleted. '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name description: Requires owner access to the repository. /repos/{owner}/{repo}/issue-tracker: patch: operationId: editIssueTracker summary: Edit issue tracker settings tags: - Repositories responses: '204': description: Settings updated successfully. '404': description: Resource not found. '422': description: Validation error. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name requestBody: required: true content: application/json: schema: type: object properties: enable_issues: type: boolean enable_external_tracker: type: boolean external_tracker_url: type: string tracker_url_format: type: string tracker_issue_style: type: string enum: - numeric - alphanumeric /repos/{owner}/{repo}/mirror-sync: post: operationId: mirrorSync summary: Mirror sync tags: - Repositories responses: '202': description: Mirror sync has been queued. '404': description: Resource not found. '422': description: Validation error. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name description: Add a mirror repository to the sync queue. Returns 404 if the repository is not a mirror. /repos/{owner}/{repo}/branches: get: operationId: listBranches summary: List branches tags: - Repositories responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Branch' '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name /repos/{owner}/{repo}/branches/{branch}: get: operationId: getBranch summary: Get a branch tags: - Repositories responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Branch' '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name - name: branch in: path required: true schema: type: string description: Branch name /repos/{owner}/{repo}/commits/{sha}: get: operationId: getCommit summary: Get a single commit tags: - Repositories responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Commit' '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name - name: sha in: path required: true schema: type: string description: Commit SHA description: Get details for a single commit. Set Accept header to application/vnd.gogs.sha to return only the SHA-1 hash of a commit reference. /repos/{owner}/{repo}/raw/{ref}/{filepath}: get: operationId: getRawContent summary: Download raw content tags: - Repositories responses: '200': description: Raw file content content: text/plain: schema: type: string '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name - name: ref in: path required: true schema: type: string description: Branch, tag, or commit - name: filepath in: path required: true schema: type: string description: File path /repos/{owner}/{repo}/archive/{archive}: get: operationId: downloadArchive summary: Download archive tags: - Repositories responses: '200': description: Archive file content: application/octet-stream: schema: type: string format: binary '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name - name: archive in: path required: true schema: type: string description: Ref and format, e.g. master.zip or master.tar.gz /repos/{owner}/{repo}/contents/{path}: get: operationId: getContents summary: Get contents tags: - Repositories responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/Content' '404': description: Resource not found. parameters: - name: owner in: path required: true schema: type: string description: Repository owner - name: repo in: path required: true schema: type: string description: Repository name - name: path in: path required: true schema: type: string description: File or directory path - name: ref in: query required: false schema: type: string description: Branch, tag, or commit. Defaults to the default branch. description: Get the contents of a file, directory, symlink, or submodule in a repository. put: operationId: putContents summary: Create or update a file description: Creates or updates a file in the repository. The content must be base64 encoded. tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository - name: path in: path required: true schema: type: string description: Path of the file to create or update requestBody: required: true content: application/json: schema: type: object properties: message: type: string description: Commit message content: type: string description: Base64-encoded file content branch: type: string description: Branch to commit to. Defaults to the repository's default branch. required: - message - content responses: '201': description: File created or updated successfully. content: application/json: schema: type: object properties: content: $ref: '#/components/schemas/Content' commit: $ref: '#/components/schemas/Commit' '404': description: Repository not found. '422': description: Validation error. /repos/{owner}/{repo}/forks: get: operationId: listForks summary: List forks tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Repository' '404': description: Repository not found. /repos/{owner}/{repo}/tags: get: operationId: listTags summary: List tags tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Tag' '404': description: Repository not found. /repos/{owner}/{repo}/commits: get: operationId: getAllCommits summary: List all commits description: Returns commits from the HEAD of the default branch. tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository - name: pageSize in: query required: false schema: type: integer default: 30 description: Number of commits to return responses: '200': description: Success content: application/json: schema: type: array items: $ref: '#/components/schemas/Commit' '404': description: Repository not found. /repos/{owner}/{repo}/wiki: patch: operationId: editWiki summary: Edit wiki settings tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository requestBody: required: true content: application/json: schema: type: object properties: enable_wiki: type: boolean description: Whether to enable the wiki allow_public_wiki: type: boolean description: Whether the wiki is publicly accessible enable_external_wiki: type: boolean description: Whether to use an external wiki external_wiki_url: type: string description: URL of the external wiki responses: '204': description: Wiki settings updated successfully. '404': description: Repository not found. '422': description: Validation error. /repos/{owner}/{repo}/editorconfig/{filename}: get: operationId: getEditorconfig summary: Get editorconfig definition description: Returns the editorconfig definition for the given filename in the repository. tags: - Repositories parameters: - name: owner in: path required: true schema: type: string description: Owner of the repository - name: repo in: path required: true schema: type: string description: Name of the repository - name: filename in: path required: true schema: type: string description: Filename to get the editorconfig definition for responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/EditorConfigDefinition' '404': description: No editorconfig file exists or no matching definition for the filename. components: schemas: EditorConfigDefinition: type: object properties: charset: type: string indent_style: type: string indent_size: type: string end_of_line: type: string Repository: type: object properties: id: type: integer owner: $ref: '#/components/schemas/User' name: type: string full_name: type: string description: type: string private: type: boolean fork: type: boolean parent: $ref: '#/components/schemas/Repository' description: Present when fork is true empty: type: boolean mirror: type: boolean size: type: integer html_url: type: string ssh_url: type: string clone_url: type: string website: type: string stars_count: type: integer forks_count: type: integer watchers_count: type: integer open_issues_count: type: integer default_branch: type: string created_at: type: string format: date-time updated_at: type: string format: date-time permissions: type: object properties: admin: type: boolean push: type: boolean pull: type: boolean Tag: type: object properties: name: type: string commit: type: object properties: id: type: string message: type: string url: type: string author: type: object properties: name: type: string email: type: string format: email username: type: string committer: type: object properties: name: type: string email: type: string format: email username: type: string timestamp: type: string format: date-time User: type: object properties: id: type: integer username: type: string login: type: string description: Alias of username for GitHub API compatibility full_name: type: string email: type: string format: email avatar_url: type: string Content: type: object properties: type: type: string enum: - file - dir - symlink - submodule encoding: type: string size: type: integer name: type: string path: type: string content: type: string sha: type: string url: type: string git_url: type: string html_url: type: string download_url: type: string _links: type: object properties: git: type: string self: type: string html: type: string Commit: type: object properties: url: type: string sha: type: string html_url: type: string commit: type: object properties: url: type: string message: type: string author: type: object properties: name: type: string email: type: string date: type: string committer: type: object properties: name: type: string email: type: string date: type: string tree: type: object properties: url: type: string sha: type: string author: $ref: '#/components/schemas/User' committer: $ref: '#/components/schemas/User' parents: type: array items: type: object properties: url: type: string sha: type: string Branch: type: object properties: name: type: string commit: type: object properties: id: type: string message: type: string url: type: string author: type: object properties: name: type: string email: type: string username: type: string committer: type: object properties: name: type: string email: type: string username: type: string timestamp: type: string format: date-time securitySchemes: BasicAuth: type: http scheme: basic AccessToken: type: apiKey in: header name: Authorization description: 'Personal access token. Use format: token {YOUR_ACCESS_TOKEN}'