openapi.yaml

openapi: 3.0.0

info:
  version: 1.0.0
  title: beluga
  contact:
    url: https://github.com/AlexGustafsson/beluga/issues
  description: >
    A self hosted Docker Hub.
externalDocs:
  url: https://github.com/AlexGustafsson/beluga

tags:
  - name: Search
  - name: Repositories
  - name: Organizations
  - name: Users

servers:
  - url: http://localhost:8080

paths:
  /api/content/v1/products/search:
    description: Search
    get:
      operationId: get-search
      summary: Perform a search
      description: Perform search
      tags:
        - Search
      parameters:
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: type
          description: Type of responses
          required: false
          schema:
            type: string
        - in: query
          name: operating_system
          description: Comma separated operating systems
          required: false
          schema:
            type: string
        - in: query
          name: architecture
          description: Comma separated image architectures
          required: false
          schema:
            type: string
        - in: query
          name: q
          x-go-name: Query
          description: Free text query
          required: false
          schema:
            type: string
        - in: query
          name: source
          description: Product source
          required: false
          schema:
            type: string
        - in: query
          name: page
          description: Page integer
          required: false
          schema:
            type: integer
        - in: query
          name: sort
          description: Sort option, such as updated_at and suggested
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SummaryPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/repositories:
    post:
      operationId: post-repositories
      summary: Create a repository
      description: Create a repository
      tags:
        - Repositories
      requestBody:
        description: Repository to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRepositoryRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Repository"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/repositories/{namespace}:
    get:
      operationId: get-repositories
      summary: List repositories in a namespace
      description: List repositories in a namespace
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: page
          description: Page index
          required: false
          schema:
            type: integer
        - in: query
          name: ordering
          description: Sort order
          required: false
          schema:
            type: string
            default: "last_updated"
            enum: ["last_updated", "-last_updated", "name", "-name"]
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}:
    get:
      operationId: get-repository
      summary: List repositories in a namespace
      description: List repositories in a namespace
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryWithDetails"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      operationId: patch-repository
      summary: Patch repository
      description: Patch repository
      tags:
        - Repositories
      requestBody:
        description: Repository update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RepositoryUpdate"
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryWithDetails"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: delete-repository
      summary: Delete repository
      description: Delete repository
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
      responses:
        "202":
          description: Accepted
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}/tags:
    get:
      operationId: get-tags
      summary: List repositories in a namespace
      description: List repositories in a namespace
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
        - in: query
          name: ordering
          description: Sort order
          required: false
          schema:
            type: string
            default: "last_updated"
            enum: ["last_updated", "-last_updated", "name", "-name"]
        - in: query
          name: name
          description: Prefix of label names to match against
          required: false
          schema:
            type: string
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: page
          description: Page index
          required: false
          schema:
            type: integer
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}/tags/{tag}:
    get:
      operationId: get-tag
      summary: Get a tag
      description: Get a tag
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
        - in: path
          name: tag
          description: Name of the tag
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Tag
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tag"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}/tags/{tag}/images:
    get:
      operationId: get-images
      summary: List images in tag
      description: List images in tag
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
        - in: path
          name: tag
          description: Tag name
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Images
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ImageWithDetails"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}/dockerfile:
    get:
      operationId: get-dockerfile
      summary: Fetch dockerfile
      description: Fetch dockerfile
      tags:
        - Repositories
      parameters:
        - in: path
          name: namespace
          description: User or organization
          required: true
          schema:
            type: string
        - in: path
          name: repository
          description: Name of the repository
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Dockerfile
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Dockerfile"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/repositories/{namespace}/{repository}/stars:
    parameters:
      - in: path
        name: namespace
        description: User or organization
        required: true
        schema:
          type: string
      - in: path
        name: repository
        description: Name of the repository
        required: true
        schema:
          type: string
    post:
      operationId: star-repository
      summary: Star repository
      description: Star repository
      tags:
        - Repositories
      responses:
        "204":
          description: No Content
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      operationId: unstar-repository
      summary: Unstar repository
      description: Unstar repository
      tags:
        - Repositories
      responses:
        "204":
          description: No Content
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/orgs:
    get:
      operationId: get-organizations
      summary: Fetch organizations
      description: Fetch organizations
      tags:
        - Organizations
      parameters:
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: page
          description: Page index
          required: false
          schema:
            type: integer
        - in: query
          name: ordering
          description: Sort order
          required: false
          schema:
            type: string
            default: "last_updated"
            enum: ["last_updated", "-last_updated", "name", "-name"]
      responses:
        "200":
          description: Organizations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OrganizationsPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v2/orgs/{organization}:
    get:
      operationId: get-organization
      summary: Fetch organization
      description: Fetch organization
      tags:
        - Organizations
      parameters:
        - in: path
          name: organization
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Organization"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/user:
    get:
      operationId: get-current-user
      summary: Fetch current user
      description: Fetch current user
      tags:
        - Users
      responses:
        "200":
          description: User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      operationId: update-current-user
      summary: Update current user
      description: Update current user
      tags:
        - Users
      requestBody:
        description: User update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UserUpdate"
      responses:
        "200":
          description: User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/users/{user}:
    get:
      operationId: get-user
      summary: Fetch user
      description: Fetch user
      tags:
        - Users
      parameters:
        - in: path
          name: user
          required: true
          schema:
            type: string
      responses:
        "200":
          description: User
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/users/{user}/repositories/starred:
    get:
      operationId: get-user-starred
      summary: Fetch user starred repositories
      description: Fetch user starred repositories
      tags:
        - Users
      parameters:
        - in: path
          name: user
          required: true
          schema:
            type: string
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: page
          description: Page index
          required: false
          schema:
            type: integer
        - in: query
          name: ordering
          description: Sort order
          required: false
          schema:
            type: string
            default: "last_updated"
            enum: ["last_updated", "-last_updated", "name", "-name"]
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/users/{user}/repositories/contributed:
    get:
      operationId: get-user-contributed
      summary: Fetch user contributed repositories
      description: Fetch user contributed repositories
      tags:
        - Users
      parameters:
        - in: path
          name: user
          required: true
          schema:
            type: string
        - in: query
          name: page_size
          description: Page size
          required: false
          schema:
            type: integer
        - in: query
          name: page
          description: Page index
          required: false
          schema:
            type: integer
        - in: query
          name: ordering
          description: Sort order
          required: false
          schema:
            type: string
            default: "last_updated"
            enum: ["last_updated", "-last_updated", "name", "-name"]
      responses:
        "200":
          description: Repositories
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RepositoryPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/access-tokens:
    post:
      operationId: create-access-token
      summary: Create an access token
      description: Create an access token
      tags:
        - Tokens
      requestBody:
        description: Token request
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenRequest"
      responses:
        "200":
          description: Token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    get:
      operationId: get-access-tokens
      summary: Get access tokens
      description: Get access tokens
      tags:
        - Tokens
      responses:
        "200":
          description: Token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenPage"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /v2/access-tokens/{token}:
    parameters:
      - in: path
        name: token
        required: true
        schema:
          type: string
    patch:
      operationId: patch-access-token
      summary: Patch access token
      description: Patch access token
      tags:
        - Tokens
      requestBody:
        description: Tokens update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenUpdate"
      responses:
        "200":
          description: Token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Token"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  schemas:
    Page:
      type: object
      required:
        - count
        - next
        - previous
        - page
        - page_size
      properties:
        count:
          type: integer
          description: Total results
        next:
          type: string
          nullable: true
          description: URL to the next page
        previous:
          type: string
          nullable: true
          description: URL to the previous page
        page:
          type: integer
          description: Current page
        page_size:
          type: integer
          description: Number of entries per page
    Summary:
      type: object
      required:
        - id
        - name
        - slug
        - type
        - publisher
        - created_at
        - updated_at
        - short_description
        - source
        - popularity
        - categories
        - operating_systems
        - architectures
        - logo_url
        - certification_status
        - star_count
        - pull_count
        - filter_type
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        type:
          type: string
          enum: [image]
        publisher:
          $ref: "#/components/schemas/Publisher"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        short_description:
          type: string
        source:
          type: string
        popularity:
          type: integer
        categories:
          type: array
          items:
            $ref: "#/components/schemas/Label"
        operating_systems:
          type: array
          items:
            $ref: "#/components/schemas/Label"
        architectures:
          type: array
          items:
            $ref: "#/components/schemas/Label"
        logo_url:
          $ref: "#/components/schemas/Logo"
        certification_status:
          type: string
        star_count:
          type: integer
        pull_count:
          type: integer
        filter_type:
          type: string
    SummaryPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - summaries
          properties:
            summaries:
              type: array
              items:
                $ref: "#/components/schemas/Summary"
    Repository:
      type: object
      required:
        - name
        - namespace
        - repository_type
        - status
        - is_private
        - star_count
        - pull_count
        - last_updated
        - date_registered
        - affiliation
        - media_types
      properties:
        name:
          type: string
        namespace:
          type: string
        repository_type:
          type: string
          nullable: true
          enum: [image]
        status:
          type: integer
        is_private:
          type: boolean
        star_count:
          type: integer
        pull_count:
          type: integer
        last_updated:
          type: string
          format: date-time
        date_registered:
          type: string
          format: date-time
        affiliation:
          type: string
          nullable: true
        media_types:
          type: array
          items:
            type: string
    RepositoryPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - results
          properties:
            results:
              type: array
              items:
                $ref: "#/components/schemas/Repository"
    RepositoryWithDetails:
      allOf:
        - $ref: "#/components/schemas/Repository"
        - type: object
          required:
            - user
            - description
            - is_automated
            - can_edit
            - collaborator_count
            - hub_user
            - has_starred
            - full_description
            - permissions
          properties:
            user:
              type: string
            description:
              type: string
            is_automated:
              type: boolean
            can_edit:
              type: boolean
            collaborator_count:
              type: integer
            hub_user:
              type: string
            has_starred:
              type: boolean
            full_description:
              type: string
            permissions:
              type: object
              required:
                - read
                - write
                - admin
              properties:
                read:
                  type: boolean
                write:
                  type: boolean
                admin:
                  type: boolean
    Tag:
      type: object
      required:
        - creator
        - id
        - last_updated
        - last_updater
        - last_updated_username
        - name
        - repository
        - full_size
        - v2
        - tag_status
        - tag_last_pulled
        - tag_last_pushed
        - media_type
        - digest
        - images
      properties:
        creator:
          type: integer
        id:
          type: integer
        last_updated:
          type: string
          format: date-time
        last_updater:
          type: integer
        last_updated_username:
          type: string
        name:
          type: string
        repository:
          type: integer
        full_size:
          type: integer
          x-go-type: int64
        v2:
          type: boolean
        tag_status:
          type: string
        tag_last_pulled:
          type: string
          format: date-time
        tag_last_pushed:
          type: string
          format: date-time
        media_type:
          type: string
        digest:
          type: string
        images:
          type: array
          items:
            $ref: "#/components/schemas/Image"
    TagPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - results
          properties:
            results:
              type: array
              items:
                $ref: "#/components/schemas/Tag"
    Image:
      type: object
      required:
        - architecture
        - features
        - variant
        - digest
        - os
        - os_features
        - os_version
        - size
        - status
        - last_pulled
        - last_pushed
      properties:
        architecture:
          type: string
        features:
          type: string
          nullable: true
        variant:
          type: string
          nullable: true
        digest:
          type: string
        os:
          type: string
        os_features:
          type: string
        os_version:
          type: string
          nullable: true
        size:
          type: integer
          x-go-type: int64
        status:
          type: string
        last_pulled:
          type: string
          format: date-time
        last_pushed:
          type: string
          format: date-time
    ImageWithDetails:
      allOf:
        - $ref: "#/components/schemas/Image"
        - type: object
          required:
            - layers
          properties:
            layers:
              type: array
              items:
                $ref: "#/components/schemas/Layer"
    Organization:
      type: object
      required:
        - id
        - orgname
        - full_name
        - location
        - company
        - profile_url
        - date_joined
        - gravatar_url
        - gravatar_email
        - type
        - badge
        - is_active
      properties:
        id:
          type: string
        orgname:
          type: string
        full_name:
          type: string
        location:
          type: string
        company:
          type: string
        profile_url:
          type: string
        date_joined:
          type: string
          format: date-time
        gravatar_url:
          type: string
        gravatar_email:
          type: string
        type:
          type: string
        badge:
          type: string
        is_active:
          type: boolean
    OrganizationsPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - results
          properties:
            results:
              type: array
              items:
                $ref: "#/components/schemas/Organization"
    User:
      type: object
      required:
        - id
        - uuid
        - username
        - full_name
        - location
        - company
        - profile_url
        - date_joined
        - gravatar_url
        - gravatar_email
        - type
      properties:
        id:
          type: string
        uuid:
          type: string
        username:
          type: string
        full_name:
          type: string
        location:
          type: string
        company:
          type: string
        profile_url:
          type: string
        date_joined:
          type: string
          format: date-time
        gravatar_url:
          type: string
        gravatar_email:
          type: string
        type:
          type: string
    Error:
      type: object
      required:
        - message
        - status
        - errinfo
      properties:
        errinfo:
          type: object
          additionalProperties: true
        status:
          type: number
          x-go-type: int
        message:
          type: string
    Layer:
      type: object
      required:
        - size
        - instruction
      properties:
        digest:
          type: string
        size:
          type: integer
          x-go-type: int64
        instruction:
          type: string
    Label:
      type: object
      required:
        - name
        - label
      properties:
        name:
          type: string
        label:
          type: string
    Logo:
      type: object
      required:
        - small
        - small@2x
      properties:
        small:
          type: string
        small@2x:
          type: string
    Publisher:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    CreateRepositoryRequest:
      type: object
      required:
        - namespace
        - registry
        - image
        - name
        - description
        - privacy
        - is_private
      properties:
        namespace:
          type: string
        registry:
          type: string
        image:
          type: string
        name:
          type: string
        description:
          type: string
        privacy:
          type: string
          enum: ["public", "private"]
        is_private:
          type: boolean
    UserUpdate:
      type: object
      required:
        - company
        - full_name
        - gravatar_email
        - profile_url
        - location
      properties:
        company:
          type: string
        full_name:
          type: string
        gravatar_email:
          type: string
        profile_url:
          type: string
        location:
          type: string
    TokenRequest:
      type: object
      required:
        - token_label
        - scopes
      properties:
        token_label:
          type: string
        scopes:
          type: array
          items:
            type: string
    Token:
      type: object
      required:
        - uuid
        - client_id
        - client_ip
        - creator_ua
        - created_at
        - last_used
        - generated_by
        - is_active
        - token_label
        - scopes
      properties:
        uuid:
          type: string
        client_id:
          type: string
        creator_ip:
          type: string
        creator_ua:
          type: string
        created_at:
          type: string
        last_used:
          type: string
          nullable: true
        generated_by:
          type: string
        is_active:
          type: boolean
        token:
          type: string
        token_label:
          type: string
        scopes:
          type: array
          items:
            type: string
    TokenUpdate:
      type: object
      properties:
        is_active:
          type: boolean
        token_label:
          type: string
    TokenPage:
      allOf:
        - $ref: "#/components/schemas/Page"
        - type: object
          required:
            - active_count
            - results
          properties:
            active_count:
              type: number
            results:
              type: array
              items:
                $ref: "#/components/schemas/Token"
    Dockerfile:
      type: object
      properties:
        contents:
          type: string
    RepositoryUpdate:
      type: object
      properties:
        description:
          type: string
        full_description:
          type: string
        privacy:
          type: string
          enum: ["public", "private"]
        is_private:
          type: boolean