spec.yaml

# OpenAPI documentation for DagsHub
openapi: 3.0.3
info:
  title: DagsHub API
  version: 1.0.3
  description: |
    This API provides a way to retrive & interact with data about DagsHub repositories, users, issues, webhooks and more.
    The API is also used by the [DagsHub Direct Data Access streaming client](https://github.com/DagsHub/client) to stream content from a repository for easier and faster training.
   
servers:
  - url: https://dagshub.com/api/v1
security:
  - basicAuth: []
  - tokenAuth: []
paths:
  /repos/{owner}/{repo}/content/{branch}/{path}:
    get:
      tags:
      - Content
      summary: List data in a repository folder
      description: |
        List files, commit sha1, and versioning type for a folder in repository.
        
        To get sizes add to the query param `include_size=true`. May result in a slower response.
      operationId: getContent
      parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/Branch.yaml'
      - $ref: './components/parameters/Path.yaml'
      - $ref: './components/parameters/IncludeSize.yaml'
      responses:
        '200': 
          description: Successfully retrieved the data
          content:
            application/json:
              schema:
                $ref: './components/schemas/Files.yaml'
              example:
                  [
                    {
                      "path": "images/000.png",
                      "type": "file",
                      "size": 0,
                      "hash": "79fb7f8632d7e15b3b46a7411d08bcdd",
                      "versioning": "dvc",
                      "download_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/raw/master/images/000.png",
                      "content_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/content/master/images/000.png"
                    },
                    {
                      "path": "images/001.png",
                      "type": "file",
                      "size": 0,
                      "hash": "7dd5befce39375036da253b435e1db98",
                      "versioning": "dvc",
                      "download_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/raw/master/images/001.png",
                      "content_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/content/master/images/001.png"
                    },
                    {
                      "path": "images/002.png",
                      "type": "file",
                      "size": 0,
                      "hash": "a58f181cd982a1e21c77949588737c8b",
                      "versioning": "dvc",
                      "download_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/raw/master/images/002.png",
                      "content_url": "https://dagshub.com/api/v1/repos/Simon/baby-yoda-segmentation-dataset/content/master/images/002.png"
                    },
                  ]
        '404':
          description: Non existing path
    put:
      tags:
        - Content
      summary: Upload data to a repository
      operationId: uploadContent
      parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/Branch.yaml'
      - $ref: './components/parameters/Path.yaml'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: './components/schemas/PutFile.yaml'
      responses:
        '200':
          description: Successfully uploaded content
  /repos/{owner}/{repo}/storage:
    get:
      tags:
        - Storage Integrations
      summary: List integrated storages in the repository
      operationId: getBuckets
      parameters:
      - $ref: './components/parameters/storage/Owner.yaml'
      - $ref: './components/parameters/storage/Repository.yaml'
      responses:
        '200':
          description: Successfully listed integrated storages
          content:
            application/json:
              schema:
                $ref: './components/schemas/storage/Integration.yaml'
              example:
                [
                  {
                    "name": "spacenet-dataset",
                    "protocol": "s3",
                    "list_path": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset"
                  }
                ]
  /repos/{owner}/{repo}/storage/content/{protocol}/{bucket}/{path}: 
    get:
      tags:
        - Storage Integrations
      summary: List contents in the path
      operationId: getBucketContent
      parameters:
      - $ref: './components/parameters/storage/Owner.yaml'
      - $ref: './components/parameters/storage/Repository.yaml'
      - $ref: './components/parameters/storage/Protocol.yaml'
      - $ref: './components/parameters/storage/Bucket.yaml'
      - $ref: './components/parameters/storage/Path.yaml'
      - $ref: './components/parameters/IncludeSize.yaml'
      - $ref: './components/parameters/storage/Limit.yaml'
      - $ref: './components/parameters/storage/Paging.yaml'
      - $ref: './components/parameters/storage/FromToken.yaml'
      responses:
        '200':
          description: Successfully listed a directory
          content:
            application/json:
              schema:
                $ref: './components/schemas/storage/Files.yaml'
              example:
                {
                  "entries": [
                    {
                      "path": "s3/spacenet-dataset",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset"
                    },
                    {
                      "path": "s3/spacenet-dataset/AOIs",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/AOIs"
                    },
                    {
                      "path": "s3/spacenet-dataset/Hosted-Datasets",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/Hosted-Datasets"
                    },
                    {
                      "path": "s3/spacenet-dataset/SpaceNet_Off-Nadir_Dataset",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/SpaceNet_Off-Nadir_Dataset"
                    },
                    {
                      "path": "s3/spacenet-dataset/spacenet-model-weights",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/spacenet-model-weights"
                    },
                    {
                      "path": "s3/spacenet-dataset/spacenet-stac",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/spacenet-stac"
                    },
                    {
                      "path": "s3/spacenet-dataset/spacenet",
                      "type": "dir",
                      "size": 0,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/spacenet"
                    },
                    {
                      "path": "s3/spacenet-dataset/LICENSE.md",
                      "type": "file",
                      "size": 299,
                      "hash": "",
                      "versioning": "bucket",
                      "download_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/raw/s3/spacenet-dataset/LICENSE.md",
                      "content_url": "https://dagshub.com/api/v1/repos/DagsHub-Datasets/spacenet-dataset/storage/content/s3/spacenet-dataset/LICENSE.md"
                    }
                  ],
                  "next_token": "next-token"
                }
        '404':
          description: Folder or file not found
    delete:
      tags:
        - Storage Integrations
      summary: Delete storage entries
      description: Delete files or directories from integrated storage. Requires repo admin permissions.
      operationId: deleteStorageContent
      parameters:
      - $ref: './components/parameters/storage/Owner.yaml'
      - $ref: './components/parameters/storage/Repository.yaml'
      - $ref: './components/parameters/storage/Protocol.yaml'
      - $ref: './components/parameters/storage/Bucket.yaml'
      - name: path
        in: path
        required: true
        description: The path to delete
        schema:
          type: string
      responses:
        '204':
          description: Deleted successfully
        '403':
          description: Forbidden — requires repo admin role
        '404':
          description: Path not found

  /repos/{owner}/{repo}/storage/raw/{protocol}/{bucket}/{path}:
    get:
      tags:
        - Storage Integrations
      summary: Get file in the bucket
      operationId: getBucketFile
      parameters:
      - $ref: './components/parameters/storage/Owner.yaml'
      - $ref: './components/parameters/storage/Repository.yaml'
      - $ref: './components/parameters/storage/Protocol.yaml'
      - $ref: './components/parameters/storage/Bucket.yaml'
      - name: path
        in: path
        required: true
        description: The content path
        schema: 
          type: string
      responses:
        '200':
          description: File downloaded
        '404':
          description: File not found

  /user:
    get:
      tags:
        - User
      operationId: GetAuthenticatedUser
      summary: Get authenticated user information
      responses:
        '200':
          description: successfully retrieved user information
          content:
            application/json:
              schema:
                $ref: './components/schemas/User.yaml'
  /users/{username}:
    get:
      tags:
        - User
      operationId: getUser
      summary: Get information about a user
      parameters:
        - $ref: './components/parameters/Username.yaml'
      responses:
        '200':
          description: successfully retrieved user information
          content:
            application/json:
              schema:
                $ref: './components/schemas/User.yaml'
  /repos/{owner}/{repo}/issues:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Issues
      summary: List issues for a repository
      description: This endpoint may also return pull requests in the response. If an issue is a pull request, the object will include a pull_request key.
      operationId: listRepoIssues
      responses:
        '200':
          description: Successfully retrived the data
          content:
            application/json:
              schema: 
                $ref: './components/schemas/Issues.yaml'
    post:
      tags:
        - Issues
      summary: Create an issue
      description: Any user with read access to a repository can create an issue.
      operationId: createIssue
      requestBody: 
        content:
          application/json:
            schema: 
              $ref: './components/schemas/PostIssue.yaml'
      responses:
        '201':
          description: Successfully created an issue
          content:
            application/json:
              schema: 
                $ref: './components/schemas/Issue.yaml'
    patch:
      tags:
        - Issues
      summary: Edit an issue
      operationId: editIssue
      requestBody: 
        content:
          application/json:
            schema:
              $ref: './components/schemas/PatchIssue.yaml'
      responses:
        '201':
          description: Successfully created an issue
          content:
            application/json:
              schema: 
                $ref: './components/schemas/Issue.yaml'
  /repos/{owner}/{repo}/issues/{index}:
    get:
      tags:
        - Issues
      summary: Get a single issue
      description: This endpoint may also return pull requests in the response. If an issue is a pull request, the object will include a pull_request key.
      operationId: getIssue
      parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/Index.yaml'
      responses:
        '200':
          description: Successfully retrived the data
          content:
            application/json:
              schema: 
                $ref: './components/schemas/Issue.yaml'
  /repos/{owner}/{repo}/experiments:
    get:
      tags:
        - Experiments
      summary: List Experiments
      description: Get a list of experiments in the given repository
      operationId: getExperiments
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
      responses:
        '200':
          description: retrieved experiments successfully
          content:
            application/json:
              schema:
                $ref: './components/schemas/ExperimentsResponse.yaml'
  /repos/{owner}/{repo}/experiments/metricsForExperiments:
    post:
      tags:
        - Experiments
      summary: Get experiment metrics for experiment
      operationId: getExperimentMetrics
      parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      requestBody:
        content:
          application/json:
            schema:
              $ref: './components/schemas/ExperimentKeys.yaml'
      responses:
        '200':
          description: Retrieved experiments metrics
          content:
            application/json:
              schema:
                $ref: './components/schemas/ExperimentMetricsResponse.yaml'
  /repos/{owner}/{repo}/experiments/experiment/{experimentKey}:
    post:
      tags:
        - Experiments
      summary: Edit experiment info
      description: Edit experiment info, currently supports just changing experiment name.
      operationId: editExperiment
      parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/ExperimentKey.yaml'
      requestBody:
        content:
          application/json:
            schema:
              $ref: './components/schemas/EditExperimentPost.yaml'
      responses:
        '200':
          description: Edit experiment info successfully
          content:
            application/json:
              schema:
                type: string
                description: The new experiment name
    delete: 
      tags:
        - Experiments
      summary: Delete experiment
      description: Support both git and MLflow experiments
      operationId: deleteExperiment
      parameters: 
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/ExperimentKey.yaml'
      responses: 
        '200':
          description: Deleted experiment successfully
        '404':
          description: Experiment not found

  /repos/{owner}/{repo}/experiments/experiment/{experimentKey}/labels/{experimentLabel}:
    post:
      tags:
        - Experiments
      summary: Add label to experiment
      operationId: addExperimentLabel
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/ExperimentKey.yaml'
        - $ref: './components/parameters/ExperimentLabel.yaml'
      responses:
        '404':
          description: Experiment not found
        '400':
          description: "Bad request"
        '200':
          description: Experiment label was added
          content:
            application/json:
              schema:
                type: string
                description: The added label name
    delete:
      tags:
        - Experiments
      summary: Delete experiment label
      operationId: deleteExperimentLabel
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/ExperimentKey.yaml'
        - $ref: './components/parameters/ExperimentLabel.yaml'
      responses:
        '404':
          description: Label/experiment not found
        '400':
          description: "Bad request: experiment label name can be up to 128 characters long."
        '200':
          description: Experiment label was deleted
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: Remaining labels after deletion

  /repos/search:
    get:
      summary: Search repositories
      tags:
        - Repository
      operationId: search
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
        - name: uid
          in: query
          description: User ID to specify search whose repositories. Default is 0 and search all repositories
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum number of repositories in search results.
          schema:
            type: integer
            default: 10
        - name: page
          in: query
          description: Page number. Default is 1.
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: './components/schemas/RepositorySearchResponse.yaml'
  /repos/{owner}/{repo}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: Get repository information
      operationId: getRepo
      responses:
        '200':
          description: Repository information
          content:
            application/json:
              schema:
                $ref: './components/schemas/Repository.yaml'
        '404':
          description: Repository not found
    delete:
      tags:
        - Repositories
      summary: Delete a repository
      description: Permanently deletes a repository. Requires owner permissions.
      operationId: deleteRepo
      responses:
        '204':
          description: Repository deleted
        '403':
          description: Not authorized
        '404':
          description: Repository not found
  /user/repos:  
    get:
      summary: List your repositories
      description: |
        List repositories that are accessible to the authenticated user.

        This includes repositories owned by the authenticated user, repositories where the authenticated user is a collaborator, and repositories that the authenticated user has access to through an organization membership.
      operationId: listMyRepos
      tags:
        - Repository
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Repository.yaml'
    post:
      tags:
        - Repository
      summary: Create
      description: Create a new repository for the authenticated user.
      operationId: createRepo
      requestBody:
        content:
          application/json:
            schema:
              $ref: './components/schemas/CreateRepo.yaml'
      responses:
        '201':
          description: Created
  /users/{username}/repos:
    get:
      summary: List user repositories
      description: List public repositories for the specified user.
      operationId: listUserRepos
      tags:
        - Repository
      parameters:
        - $ref: './components/parameters/Username.yaml'
      responses:
        '200':
          description: Success
  /orgs/{orgname}/repos:
    get:
      tags:
      - Repository
      operationId: listOrgRepos
      summary: List organization repositories
      description: List repositories that are accessible to the authenticated user.
      parameters:
        - $ref: './components/parameters/Orgname.yaml'
      responses:
        '200':
          description: Success
  /org/{orgname}/repos:
    post:
      tags:
        - Repository
      operationId: createOrgRepo
      summary: Create in organization
      description: Create a new repository in this organization. The authenticated user must be an **owner** of the specified organization.
      requestBody:
        content:
          application/json:
            schema:
              $ref: './components/schemas/CreateRepo.yaml'
      parameters:
        - $ref: './components/parameters/Orgname.yaml'
      responses:
        '201':
          description: Created
  /repos/migrate:
    post:
      tags:
        - Repository
      summary: Migrate repository 
      description: |
        Migrate a repository from other Git hosting sources for the authenticated user.

        To migrate a repository for a organization, the authenticated user must be a **owner** of the specified organization.
      operationId: migrateRepo
      requestBody:
        content:
          application/json:
            schema:
              $ref: './components/schemas/MigrateRepo.yaml'
      responses:
        '201': 
          description: Created
  /repos/{owner}/{repo}/raw/{ref}/{path}:
    get:
      tags:
        - Content
      summary: Download raw content
      description: This method returns the raw content of a file.
      operationId: getRaw
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Ref.yaml'
        - name: path
          in: path
          required: true
          description: The content path
          schema: 
            type: string
      responses:
        '200':
          description: OK
  /repos/{owner}/{repo}/archive/{ref}{format}:
    get:
      tags:
        - Content
      summary: Download archive
      description: This method returns archive by given format.
      operationId: getArchive
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Ref.yaml'
        - name: format
          in: path
          required: true
          description: The format of archive, either .zip or .tar.gz
          schema:
            type: string
            enum: [.zip, .tar.gz]
      responses:
        '200':
          description: OK
  /repos/{owner}/{repo}/branches:
    get:
      tags:
        - Branches
      operationId: listBranches
      summary: List Branches
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Branch.yaml'
  /repos/{owner}/{repo}/branches/{branch}:
    get:
      tags:
        - Branches
      summary: Get Branch
      operationId: getBranch
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Branch.yaml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: './components/schemas/Branch.yaml'
  /repos/{owner}/{repo}/collaborators/{collaborator}:
    put:
      tags:
        - Collaborators
      summary: Add user as a collaborator
      operationId: addCollaborator
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Collaborator.yaml'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                permission:
                  type: string
                  description: The permission to grant the collaborator. Can be one of **read**, **write** and **admin**.
                  default: write
      responses:
        '200':
          description: Success
    delete:
      tags:
        - Collaborators
      summary: Delete collaborator
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Collaborator.yaml'
      operationId: removeCollaborator
      responses:
        '204':
          description: No Content, deleted successfully
        '422':
          description: User does not exist
        '500':
          description: Internal error
  /repos/{owner}/{repo}/collaborators:
    get:
      tags:
        - Collaborators
      summary: Get collaborators
      operationId: getCollaborators
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Collaborator.yaml'
  /repos/{owner}/{repo}/annotations/access/users:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Annotations
      summary: List user access entries for annotation projects
      description: Get a list of users with access to Label Studio annotation projects in the repository
      operationId: listLabelStudioUserAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '200':
          description: Successfully retrieved user access entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/annotations/LabelStudioProjectAccess.yaml'
  /repos/{owner}/{repo}/annotations/access/users/{userid}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/annotations/UserId.yaml'
    get:
      tags:
        - Annotations
      summary: Get user access level for annotation projects
      description: Get the access level for a specific user and project (or all projects)
      operationId: getLabelStudioUserAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '200':
          description: Successfully retrieved user access level
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                    format: int64
                  project_id:
                    type: integer
                    format: int64
                  access_level:
                    type: string
                    enum: [none, annotator]
    put:
      tags:
        - Annotations
      summary: Grant user access to annotation projects
      description: Grant a user access to specific Label Studio annotation projects. User must be an organization member if the repo is owned by an organization.
      operationId: grantLabelStudioUserAccess
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: './components/schemas/annotations/GrantLabelStudioAccess.yaml'
      responses:
        '204':
          description: Access granted successfully
        '400':
          description: User must be a member of the organization which owns the repo
        '404':
          description: User not found
    delete:
      tags:
        - Annotations
      summary: Revoke user access to annotation projects
      description: Revoke a user's access to Label Studio annotation projects
      operationId: revokeLabelStudioUserAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '204':
          description: Access revoked successfully
        '404':
          description: User not found
  /repos/{owner}/{repo}/annotations/access/teams:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Annotations
      summary: List team access entries for annotation projects
      description: Get a list of teams with access to Label Studio annotation projects in the repository (organization repositories only)
      operationId: listLabelStudioTeamAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '200':
          description: Successfully retrieved team access entries
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/annotations/LabelStudioProjectAccess.yaml'
  /repos/{owner}/{repo}/annotations/access/teams/{teamid}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - $ref: './components/parameters/annotations/TeamId.yaml'
    get:
      tags:
        - Annotations
      summary: Get team access level for annotation projects
      description: Get the access level for a specific team and project (or all projects)
      operationId: getLabelStudioTeamAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '200':
          description: Successfully retrieved team access level
          content:
            application/json:
              schema:
                $ref: './components/schemas/annotations/LabelStudioProjectAccess.yaml'
    put:
      tags:
        - Annotations
      summary: Grant team access to annotation projects
      description: Grant a team access to specific Label Studio annotation projects (organization repositories only)
      operationId: grantLabelStudioTeamAccess
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: './components/schemas/annotations/GrantLabelStudioAccess.yaml'
      responses:
        '204':
          description: Access granted successfully
        '404':
          description: Team not found
    delete:
      tags:
        - Annotations
      summary: Revoke team access to annotation projects
      description: Revoke a team's access to Label Studio annotation projects
      operationId: revokeLabelStudioTeamAccess
      parameters:
        - $ref: './components/parameters/annotations/ProjectId.yaml'
      responses:
        '204':
          description: Access revoked successfully
        '404':
          description: Team not found
  /repos/{owner}/{repo}/commits/{sha}:
    get:
      tags:
        - Commits
      operationId: getCommit
      summary: Get a single commit
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - $ref: './components/parameters/Sha.yaml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: './components/schemas/Commit.yaml'
  /repos/{owner}/{repo}/hooks:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Webhooks
      summary: List hooks
      operationId: listHooks
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Webhook.yaml'
    post:
      tags:
        - Webhooks
      summary: Create a hook
      operationId: createHook
      requestBody:
        content:
          application/json: 
            schema:
              type: object
              properties:
                type:
                  type: string
                  description: The type of webhook
                  enum: 
                    - dagshub
                    - slack
                    - discord
                    - dingtalk
                  example: discord
                config: 
                  $ref: './components/schemas/WebhookConfig.yaml'
                events:
                  $ref: './components/schemas/WebhookEvents.yaml'
              required:
                - type
                - config
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: './components/schemas/Webhook.yaml'
  /repos/{owner}/{repo}/hooks/{id}:
    parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - name: id
          in: path
          schema:
            type: integer
          required: true
    patch:
      tags:
        - Webhooks
      summary: Edit a hook
      operationId: editHook
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                config:
                  $ref: './components/schemas/WebhookConfig.yaml'
                events:
                  $ref: './components/schemas/WebhookEvents.yaml'
                active:
                  type: boolean
                  description: Weather the hook is actually triggered on pushes or not. Ignore this field to leave it unchanged.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: './components/schemas/Webhook.yaml'
    delete:
      summary: Delete a hook
      operationId: deleteHook
      tags:
        - Webhooks
      responses:
        '204':
          description: No Content, deleted successfully
  /repos/{owner}/{repo}/data-engine/blob-preview/{value}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: value
        in: path
        required: true
        schema:
          type: string
        description: |
          Blob identifier to fetch a preprocessed video preview.
          Can be a 64-char metadata blob hash, or a pointer blob value (`pointer://datasourcepath/...`) URL-encoded for path safety.
    get:
      tags:
        - Data Engine
      summary: Get Data Engine blob preview clip
      operationId: getDataEngineBlobPreview
      responses:
        '200':
          description: Preprocessed video preview clip
          content:
            video/mp4:
              schema:
                type: string
                format: binary
        '404':
          description: Preview clip not found

  /repos/{owner}/{repo}/data-engine/blob/{sha}:
    get:
      tags:
        - Data Engine
      summary: Download a metadata blob by SHA
      description: |
        Download a raw metadata blob by its 64-character SHA hash.
        > **Note:** This endpoint is part of the Data Engine feature and may not be stable.
      operationId: getDataEngineBlob
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - name: sha
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{64}$'
          description: 64-character SHA hash of the blob
      responses:
        '200':
          description: Blob content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          description: Blob not found

  /repos/{owner}/{repo}/data-engine/create-dataset:
    post:
      tags:
        - Data Engine
      summary: Create a new dataset (datasource)
      description: |
        Creates a new dataset (datasource) in the repository's Data Engine.
        > **Note:** This endpoint is part of the Data Engine feature and may not be stable.
      operationId: createDataset
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Dataset name
                datasource_type:
                  type: string
                  description: Type of datasource
      responses:
        '201':
          description: Dataset created
        '403':
          description: Forbidden — requires write access

  /repos/{owner}/{repo}/data-engine/import/metadata:
    post:
      tags:
        - Data Engine
      summary: Import metadata from file
      description: |
        Upload a CSV/JSON file to import metadata into the Data Engine.
        Returns a task ID to poll for completion.
        > **Note:** This endpoint is part of the Data Engine feature and may not be stable.
      operationId: importDataEngineMetadata
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '202':
          description: Import task started
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
        '403':
          description: Forbidden — requires write access

  /repos/{owner}/{repo}/data-engine/import/metadata/{taskid}:
    get:
      tags:
        - Data Engine
      summary: Get metadata import task status
      description: |
        Poll the status of a metadata import task.
        > **Note:** This endpoint is part of the Data Engine feature and may not be stable.
      operationId: getDataEngineImportTaskStatus
      parameters:
        - $ref: './components/parameters/Owner.yaml'
        - $ref: './components/parameters/Repository.yaml'
        - name: taskid
          in: path
          required: true
          schema:
            type: string
          description: Task ID returned from the import endpoint
      responses:
        '200':
          description: Task status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: [pending, running, completed, failed]
                  message:
                    type: string

  # ── Users (public) ───────────────────────────────────────────────────────────

  /users/search:
    get:
      tags:
        - Users
      summary: Search users
      operationId: searchUsers
      parameters:
        - name: q
          in: query
          description: Search keyword
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Matching users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: './components/schemas/User.yaml'
                  ok:
                    type: boolean

  /users/{username}/keys:
    parameters:
      - $ref: './components/parameters/Username.yaml'
    get:
      tags:
        - Users
      summary: List a user's public keys
      operationId: listUserPublicKeys
      responses:
        '200':
          description: User's public keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    key:
                      type: string
                    url:
                      type: string
                    title:
                      type: string
                    created_at:
                      type: string
                      format: date-time

  /users/{username}/followers:
    parameters:
      - $ref: './components/parameters/Username.yaml'
    get:
      tags:
        - Users
      summary: List a user's followers
      operationId: listUserFollowers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of followers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/User.yaml'

  /users/{username}/following:
    parameters:
      - $ref: './components/parameters/Username.yaml'
    get:
      tags:
        - Users
      summary: List who a user is following
      operationId: listUserFollowing
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of followed users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/User.yaml'

  /users/{username}/following/{target}:
    parameters:
      - $ref: './components/parameters/Username.yaml'
      - name: target
        in: path
        required: true
        schema:
          type: string
        description: Username of the user to check
    get:
      tags:
        - Users
      summary: Check if a user is following another user
      operationId: checkUserFollowing
      responses:
        '204':
          description: User is following target
        '404':
          description: User is not following target

  /users/{username}/orgs:
    parameters:
      - $ref: './components/parameters/Username.yaml'
    get:
      tags:
        - Organizations
      summary: List a user's organizations
      operationId: listUserOrgs
      responses:
        '200':
          description: Organizations the user belongs to
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    username:
                      type: string
                    full_name:
                      type: string
                    avatar_url:
                      type: string
                    description:
                      type: string
                    website:
                      type: string
                    location:
                      type: string

  # ── User (authenticated) ──────────────────────────────────────────────────────

  /user/tokens:
    get:
      tags:
        - User
      summary: List access tokens for the authenticated user
      operationId: listAccessTokens
      security:
        - basicAuth: []
      responses:
        '200':
          description: List of access tokens
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    sha1:
                      type: string
                      description: Token value (only shown on creation)
    post:
      tags:
        - User
      summary: Create an access token
      operationId: createAccessToken
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
      responses:
        '201':
          description: Token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  sha1:
                    type: string

  /user/tokens/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    delete:
      tags:
        - User
      summary: Delete an access token
      operationId: deleteAccessToken
      responses:
        '204':
          description: Token deleted
        '404':
          description: Token not found

  /user/emails:
    get:
      tags:
        - User
      summary: List the authenticated user's email addresses
      operationId: listEmails
      responses:
        '200':
          description: Email addresses
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    email:
                      type: string
                      format: email
                    verified:
                      type: boolean
                    primary:
                      type: boolean
    post:
      tags:
        - User
      summary: Add an email address
      operationId: addEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
      responses:
        '201':
          description: Emails added
    delete:
      tags:
        - User
      summary: Delete email addresses
      operationId: deleteEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
      responses:
        '204':
          description: Emails deleted

  /user/followers:
    get:
      tags:
        - User
      summary: List the authenticated user's followers
      operationId: listMyFollowers
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Followers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/User.yaml'

  /user/following:
    get:
      tags:
        - User
      summary: List who the authenticated user is following
      operationId: listMyFollowing
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Followed users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/User.yaml'

  /user/following/{username}:
    parameters:
      - $ref: './components/parameters/Username.yaml'
    get:
      tags:
        - User
      summary: Check if the authenticated user follows a user
      operationId: checkMyFollowing
      responses:
        '204':
          description: Currently following
        '404':
          description: Not following
    put:
      tags:
        - User
      summary: Follow a user
      operationId: followUser
      responses:
        '204':
          description: Now following
    delete:
      tags:
        - User
      summary: Unfollow a user
      operationId: unfollowUser
      responses:
        '204':
          description: Unfollowed

  /user/keys:
    get:
      tags:
        - User
      summary: List the authenticated user's public keys
      operationId: listMyPublicKeys
      responses:
        '200':
          description: Public keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    key:
                      type: string
                    url:
                      type: string
                    title:
                      type: string
                    created_at:
                      type: string
                      format: date-time
    post:
      tags:
        - User
      summary: Add a public key for the authenticated user
      operationId: createPublicKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, key]
              properties:
                title:
                  type: string
                key:
                  type: string
      responses:
        '201':
          description: Key added
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  key:
                    type: string
                  url:
                    type: string
                  title:
                    type: string
                  created_at:
                    type: string
                    format: date-time

  /user/keys/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - User
      summary: Get a specific public key
      operationId: getPublicKey
      responses:
        '200':
          description: Public key
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  key:
                    type: string
                  url:
                    type: string
                  title:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '404':
          description: Key not found
    delete:
      tags:
        - User
      summary: Delete a public key
      operationId: deletePublicKey
      responses:
        '204':
          description: Key deleted
        '404':
          description: Key not found

  /user/issues:
    get:
      tags:
        - Issues
      summary: List issues across repositories for the authenticated user
      operationId: listUserIssues
      parameters:
        - name: state
          in: query
          description: Filter by state
          schema:
            type: string
            enum: [open, closed]
            default: open
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Issues across repositories
          content:
            application/json:
              schema:
                $ref: './components/schemas/Issues.yaml'

  /user/orgs:
    get:
      tags:
        - Organizations
      summary: List the authenticated user's organizations
      operationId: listMyOrgs
      responses:
        '200':
          description: Organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    username:
                      type: string
                    full_name:
                      type: string
                    avatar_url:
                      type: string
                    description:
                      type: string
                    website:
                      type: string
                    location:
                      type: string
    post:
      tags:
        - Organizations
      summary: Create an organization for the authenticated user
      operationId: createMyOrg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username]
              properties:
                username:
                  type: string
                full_name:
                  type: string
                description:
                  type: string
                website:
                  type: string
                location:
                  type: string
      responses:
        '201':
          description: Organization created

  # ── Repositories ─────────────────────────────────────────────────────────────

  /repos/topics/search:
    get:
      tags:
        - Repositories
      summary: Search repository topics
      operationId: searchTopics
      parameters:
        - name: q
          in: query
          description: Topic search query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching topics
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: string
                    description: Matching topic names
                  success:
                    type: boolean

  /repos/arxiv/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: ArXiv paper ID (e.g., `2301.00001`)
        schema:
          type: string
    get:
      tags:
        - Repositories
      summary: Get ArXiv paper metadata
      description: Returns metadata for an ArXiv paper that can be used to pre-populate a repository description.
      operationId: getArxivInfo
      responses:
        '200':
          description: ArXiv paper metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                  abstract:
                    type: string
                  authors:
                    type: array
                    items:
                      type: string

  /repos/{owner}/{repo}/stars:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: Get star count for a repository
      operationId: getRepoStars
      responses:
        '200':
          description: Number of stars
          content:
            application/json:
              schema:
                type: integer

  /repos/{owner}/{repo}/readme:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: Get the README file for a repository
      operationId: getReadme
      responses:
        '200':
          description: README file content and metadata
          content:
            application/json:
              schema:
                $ref: './components/schemas/File.yaml'
        '404':
          description: README not found

  /repos/{owner}/{repo}/file-access-jwt:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    post:
      tags:
        - Repositories
      summary: Generate a file access JWT
      description: |
        Generates a short-lived RS256 JWT for unauthenticated access to a specific file or path prefix.
        Useful for sharing files with external services like Google Colab or Run:ai JupyterLab
        where authentication headers cannot be provided.

        The returned `raw_url` can be opened directly in a browser or passed to an external service.
      operationId: generateFileAccessJWT
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [path]
              properties:
                path:
                  type: string
                  description: |
                    Path to the file or path prefix.
                    Use `path/to/file.ipynb` for exact file access.
                    Use `path/to/folder/*` for folder prefix access.
                gitRef:
                  type: string
                  description: Git ref (branch, tag, commit SHA). Defaults to the default branch.
      responses:
        '200':
          description: JWT and pre-built raw URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  jwt:
                    type: string
                    description: RS256 JWT token
                  expires_in_seconds:
                    type: integer
                    format: int64
                  raw_url:
                    type: string
                    description: Full URL to access the file with the embedded JWT
        '503':
          description: JWT signing not configured on this server

  /repos/{owner}/{repo}/forks:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: List forks of a repository
      operationId: listForks
      responses:
        '200':
          description: List of forks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Repository.yaml'

  /repos/{owner}/{repo}/mirror-sync:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    post:
      tags:
        - Repositories
      summary: Trigger a mirror sync
      description: Forces an immediate sync of a mirrored repository from its upstream. Requires write access.
      operationId: mirrorSync
      responses:
        '200':
          description: Sync triggered

  /repos/{owner}/{repo}/editorconfig/{filename}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: filename
        in: path
        required: true
        description: File path to look up EditorConfig rules for
        schema:
          type: string
    get:
      tags:
        - Repositories
      summary: Get EditorConfig settings for a file
      description: Returns the effective EditorConfig rules that apply to a given file path in the repository.
      operationId: getEditorconfig
      responses:
        '200':
          description: EditorConfig settings as a key-value object
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '404':
          description: No .editorconfig found

  # ── Commits ───────────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/commits:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Commits
      summary: List commits for a repository
      operationId: listCommits
      parameters:
        - name: sha
          in: query
          description: Branch, tag, or commit SHA to start listing from
          schema:
            type: string
        - name: path
          in: query
          description: Only return commits that modified this file path
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: List of commits
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Commit summary (PayloadCommit — flat, no files/stats wrapper)
                  properties:
                    id:
                      type: string
                      description: Full commit SHA
                    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
                    added:
                      type: array
                      items:
                        type: string
                      nullable: true
                    removed:
                      type: array
                      items:
                        type: string
                      nullable: true
                    modified:
                      type: array
                      items:
                        type: string
                      nullable: true
                    timestamp:
                      type: string
                      format: date-time

  # ── Tags ─────────────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/tags:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: List tags for a repository
      operationId: listTags
      responses:
        '200':
          description: List of tags
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    commit:
                      $ref: './components/schemas/Commit.yaml'

  /repos/{owner}/{repo}/tags/{tag}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: tag
        in: path
        required: true
        schema:
          type: string
    get:
      tags:
        - Repositories
      summary: Get a single tag
      operationId: getTag
      responses:
        '200':
          description: Tag details
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  commit:
                    $ref: './components/schemas/Commit.yaml'
        '404':
          description: Tag not found

  # ── Deploy Keys ───────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/keys:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Repositories
      summary: List deploy keys for a repository
      operationId: listDeployKeys
      responses:
        '200':
          description: Deploy keys
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    key:
                      type: string
                    url:
                      type: string
                    title:
                      type: string
                    created_at:
                      type: string
                      format: date-time
                    read_only:
                      type: boolean
    post:
      tags:
        - Repositories
      summary: Add a deploy key
      operationId: createDeployKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title, key]
              properties:
                title:
                  type: string
                key:
                  type: string
      responses:
        '201':
          description: Deploy key added
        '422':
          description: Key already in use

  /repos/{owner}/{repo}/keys/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Repositories
      summary: Get a deploy key
      operationId: getDeployKey
      responses:
        '200':
          description: Deploy key
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  key:
                    type: string
                  url:
                    type: string
                  title:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  read_only:
                    type: boolean
        '404':
          description: Key not found
    delete:
      tags:
        - Repositories
      summary: Delete a deploy key
      operationId: deleteDeployKey
      responses:
        '204':
          description: Key deleted
        '404':
          description: Key not found

  # ── Pull Requests ─────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/pulls:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Issues
      summary: List pull requests for a repository
      operationId: listPulls
      parameters:
        - name: state
          in: query
          schema:
            type: string
            enum: [open, closed]
            default: open
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Pull requests
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Issue.yaml'

  /repos/{owner}/{repo}/pulls/{index}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: index
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Issues
      summary: Get a pull request
      operationId: getPull
      responses:
        '200':
          description: Pull request details
          content:
            application/json:
              schema:
                $ref: './components/schemas/Issue.yaml'
        '404':
          description: Pull request not found

  # ── Issue Comments ────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/issues/comments:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Issues
      summary: List all issue comments in a repository
      operationId: listRepoIssueComments
      responses:
        '200':
          description: All comments in the repository
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    html_url:
                      type: string
                    user:
                      $ref: './components/schemas/User.yaml'
                    body:
                      type: string
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time

  /repos/{owner}/{repo}/issues/comments/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    patch:
      tags:
        - Issues
      summary: Edit an issue comment
      operationId: editIssueComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
      responses:
        '200':
          description: Updated comment
        '404':
          description: Comment not found

  /repos/{owner}/{repo}/issues/{index}/comments:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: index
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Issues
      summary: List comments on an issue
      operationId: listIssueComments
      responses:
        '200':
          description: Comments on the issue
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    html_url:
                      type: string
                    user:
                      $ref: './components/schemas/User.yaml'
                    body:
                      type: string
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
    post:
      tags:
        - Issues
      summary: Add a comment to an issue
      operationId: createIssueComment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
      responses:
        '201':
          description: Comment created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  html_url:
                    type: string
                  user:
                    $ref: './components/schemas/User.yaml'
                  body:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  updated_at:
                    type: string
                    format: date-time

  /repos/{owner}/{repo}/issues/{index}/comments/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: index
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    patch:
      tags:
        - Issues
      summary: Edit a comment on an issue
      operationId: editIssueCommentOnIssue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
      responses:
        '200':
          description: Updated comment
        '404':
          description: Comment not found
    delete:
      tags:
        - Issues
      summary: Delete a comment on an issue
      operationId: deleteIssueComment
      responses:
        '204':
          description: Comment deleted
        '404':
          description: Comment not found

  # ── Issue Labels ──────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/issues/{index}/labels:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: index
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Issues
      summary: List labels on an issue
      operationId: listIssueLabels
      responses:
        '200':
          description: Labels on the issue
          content:
            application/json:
              schema:
                $ref: './components/schemas/Labels.yaml'
    post:
      tags:
        - Issues
      summary: Add labels to an issue
      operationId: addIssueLabels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                labels:
                  type: array
                  items:
                    type: integer
                    format: int64
                  description: Array of label IDs to add
      responses:
        '200':
          description: Updated labels list
          content:
            application/json:
              schema:
                $ref: './components/schemas/Labels.yaml'
    put:
      tags:
        - Issues
      summary: Replace all labels on an issue
      operationId: replaceIssueLabels
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                labels:
                  type: array
                  items:
                    type: integer
                    format: int64
                  description: Array of label IDs to set (replaces all existing labels)
      responses:
        '200':
          description: New labels list
          content:
            application/json:
              schema:
                $ref: './components/schemas/Labels.yaml'
    delete:
      tags:
        - Issues
      summary: Remove all labels from an issue
      operationId: clearIssueLabels
      responses:
        '204':
          description: All labels removed

  /repos/{owner}/{repo}/issues/{index}/labels/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: index
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    delete:
      tags:
        - Issues
      summary: Remove a specific label from an issue
      operationId: removeIssueLabel
      responses:
        '204':
          description: Label removed
        '404':
          description: Label not found on this issue

  # ── Repo Labels ───────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/labels:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Issues
      summary: List labels for a repository
      operationId: listLabels
      responses:
        '200':
          description: Repository labels
          content:
            application/json:
              schema:
                $ref: './components/schemas/Labels.yaml'
    post:
      tags:
        - Issues
      summary: Create a label
      operationId: createLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, color]
              properties:
                name:
                  type: string
                color:
                  type: string
                  description: Hex color code with leading `#` (exactly 7 characters, e.g. `#ff0000`)
      responses:
        '201':
          description: Label created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  name:
                    type: string
                  color:
                    type: string
                  url:
                    type: string

  /repos/{owner}/{repo}/labels/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Issues
      summary: Get a label
      operationId: getLabel
      responses:
        '200':
          description: Label details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  name:
                    type: string
                  color:
                    type: string
                  url:
                    type: string
        '404':
          description: Label not found
    patch:
      tags:
        - Issues
      summary: Edit a label
      operationId: editLabel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                color:
                  type: string
      responses:
        '200':
          description: Updated label
        '404':
          description: Label not found
    delete:
      tags:
        - Issues
      summary: Delete a label
      operationId: deleteLabel
      responses:
        '204':
          description: Label deleted
        '404':
          description: Label not found

  # ── Milestones ────────────────────────────────────────────────────────────────

  /repos/{owner}/{repo}/milestones:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Issues
      summary: List milestones for a repository
      operationId: listMilestones
      responses:
        '200':
          description: Repository milestones
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    title:
                      type: string
                    description:
                      type: string
                    state:
                      type: string
                      enum: [open, closed]
                    open_issues:
                      type: integer
                    closed_issues:
                      type: integer
                    closed_at:
                      type: string
                      format: date-time
                      nullable: true
                    due_on:
                      type: string
                      format: date-time
                      nullable: true
    post:
      tags:
        - Issues
      summary: Create a milestone
      operationId: createMilestone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                due_on:
                  type: string
                  format: date-time
      responses:
        '201':
          description: Milestone created

  /repos/{owner}/{repo}/milestones/{id}:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Issues
      summary: Get a milestone
      operationId: getMilestone
      responses:
        '200':
          description: Milestone details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  title:
                    type: string
                  description:
                    type: string
                  state:
                    type: string
                    enum: [open, closed]
                  open_issues:
                    type: integer
                  closed_issues:
                    type: integer
                  closed_at:
                    type: string
                    format: date-time
                    nullable: true
                  due_on:
                    type: string
                    format: date-time
                    nullable: true
        '404':
          description: Milestone not found
    patch:
      tags:
        - Issues
      summary: Edit a milestone
      operationId: editMilestone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                description:
                  type: string
                state:
                  type: string
                  enum: [open, closed]
                due_on:
                  type: string
                  format: date-time
      responses:
        '200':
          description: Updated milestone
        '404':
          description: Milestone not found
    delete:
      tags:
        - Issues
      summary: Delete a milestone
      operationId: deleteMilestone
      responses:
        '204':
          description: Milestone deleted
        '404':
          description: Milestone not found

  # ── Annotation Workspace Lifecycle ────────────────────────────────────────────

  /repos/{owner}/{repo}/annotations/ready:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Annotations
      summary: Check annotation workspace readiness
      description: Returns whether the Label Studio workspace for this repository is ready to accept requests.
      operationId: checkWorkspaceReadiness
      parameters:
        - name: service
          in: query
          description: "Workspace service type: 0 = Label Studio (Git), 1 = Label Studio (S3)"
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Workspace is ready
        '404':
          description: Workspace not found or not yet started

  /repos/{owner}/{repo}/annotations/start:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    post:
      tags:
        - Annotations
      summary: Start an annotation workspace
      description: Provisions and starts a Label Studio workspace for this repository. May take up to a few minutes; poll `/ready` to confirm readiness.
      operationId: startWorkspace
      parameters:
        - name: service
          in: query
          description: "Workspace service type: 0 = Label Studio (Git), 1 = Label Studio (S3)"
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Workspace start initiated

  /repos/{owner}/{repo}/annotations/workspace-usage:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Annotations
      summary: Get annotation workspace usage
      description: Returns current resource usage metrics for the repository's annotation workspace.
      operationId: getWorkspaceUsage
      parameters:
        - name: service
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Workspace usage metrics

  /repos/{owner}/{repo}/annotations/keep-alive:
    parameters:
      - $ref: './components/parameters/Owner.yaml'
      - $ref: './components/parameters/Repository.yaml'
    get:
      tags:
        - Annotations
      summary: Keep annotation workspace alive
      description: |
        Sends a keep-alive signal to the annotation workspace to prevent it from being
        shut down due to inactivity. Call this periodically (e.g., every few minutes)
        while users are actively using the workspace.
      operationId: keepWorkspaceAlive
      parameters:
        - name: service
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Keep-alive acknowledged

  # ── Organizations ─────────────────────────────────────────────────────────────

  /orgs/{orgname}:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
    get:
      tags:
        - Organizations
      summary: Get an organization
      operationId: getOrg
      responses:
        '200':
          description: Organization details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                  username:
                    type: string
                  full_name:
                    type: string
                  avatar_url:
                    type: string
                  description:
                    type: string
                  website:
                    type: string
                  location:
                    type: string
        '404':
          description: Organization not found
    patch:
      tags:
        - Organizations
      summary: Edit an organization
      operationId: editOrg
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                full_name:
                  type: string
                description:
                  type: string
                website:
                  type: string
                location:
                  type: string
      responses:
        '200':
          description: Organization updated
        '403':
          description: Not authorized

  /orgs/{orgname}/teams:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
    get:
      tags:
        - Organizations
      summary: List teams in an organization
      description: Returns teams that the authenticated user is a member of. Org owners see all teams.
      operationId: listOrgTeams
      responses:
        '200':
          description: Teams in the organization
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Team.yaml'

  /orgs/{orgname}/teams/repo:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
    get:
      tags:
        - Organizations
      summary: Search teams in an organization by name
      description: Searches teams in an organization by keyword. Useful for autocomplete when adding a repository to a team.
      operationId: listTeamsForRepo
      parameters:
        - name: q
          in: query
          description: Team name search keyword
          schema:
            type: string
      responses:
        '200':
          description: Matching teams
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/Team.yaml'

  /orgs/{orgname}/members:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
    get:
      tags:
        - Organizations
      summary: List members of an organization
      operationId: listOrgMembers
      responses:
        '200':
          description: Organization members
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: './components/schemas/User.yaml'

  /orgs/{orgname}/teams/{teamid}/members/{username}:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
      - name: teamid
        in: path
        required: true
        schema:
          type: integer
          format: int64
      - name: username
        in: path
        required: true
        schema:
          type: string
    put:
      tags:
        - Organizations
      summary: Add a member to a team
      description: Requires org owner permissions.
      operationId: addTeamMember
      responses:
        '204':
          description: Member added
        '403':
          description: Not org owner
        '404':
          description: Team or user not found
    delete:
      tags:
        - Organizations
      summary: Remove a member from a team
      description: Requires org owner permissions.
      operationId: removeTeamMember
      responses:
        '204':
          description: Member removed
        '403':
          description: Not org owner
        '404':
          description: Team or user not found

  /orgs/{orgname}/teams/{teamid}/members/invite:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
      - name: teamid
        in: path
        required: true
        schema:
          type: integer
          format: int64
    post:
      tags:
        - Organizations
      summary: Invite users to a team by email
      description: Sends invitation emails to the provided addresses. Requires org owner permissions.
      operationId: inviteTeamMembers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [emails]
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
      responses:
        '204':
          description: Invitations sent
        '403':
          description: Not org owner

  /orgs/{orgname}/teams/{teamid}/annotations/projects:
    parameters:
      - $ref: './components/parameters/Orgname.yaml'
      - name: teamid
        in: path
        required: true
        schema:
          type: integer
          format: int64
    get:
      tags:
        - Annotations
      summary: List Label Studio projects assigned to a team
      description: Lists all annotation projects that this team has access to, across all repositories in the organization. Requires org owner or team member.
      operationId: listTeamLabelStudioProjects
      responses:
        '200':
          description: Label Studio projects assigned to the team
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      format: int64
                    repo_id:
                      type: integer
                      format: int64
                    repo_name:
                      type: string
                    repo_owner:
                      type: string
                    project_id:
                      type: integer
                      format: int64
                      description: -1 means wildcard access to all projects
                    project_name:
                      type: string
                    access_level:
                      type: string
                      enum: [none, annotator]
                    created_unix:
                      type: integer
                      format: int64

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
       Use your DagsHub username and password/access token.
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: |
        You can generate a token [here](http://dagshub.com/user/settings/tokens)