Share feedback
Answers are generated based on the documentation.
Product manualDownload OpenAPI specificationMarkdown

Create a new repository

POST/v2/namespaces/{namespace}/repositories

Creates a new repository within the specified namespace. The repository will be created with the provided metadata including name, description, and privacy settings.

This operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.

Connection and access

API connection and authentication guidance

https://hub.docker.com — Docker HUB API

Use one of these alternatives. Requirements within an alternative apply together.

  • bearerAuth

Parameters

namespace path Required

Namespace of the repository, such as a user or organization name.

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Request

application/json

Schema: repo_creation_request

Example

{
  "description": "A sample application repository",
  "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
  "is_private": false,
  "name": "my-app",
  "namespace": "myorganization",
  "registry": "docker.io"
}

Response 201

Repository created successfully

application/json

Schema: repository_info

Example

{
  "categories": [],
  "collaborator_count": 0,
  "content_types": [],
  "date_registered": "2025-01-20T10:30:00Z",
  "description": "A sample application repository",
  "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
  "has_starred": false,
  "hub_user": "myorganization",
  "immutable_tags_settings": {
    "enabled": false,
    "rules": []
  },
  "is_automated": false,
  "is_private": false,
  "last_updated": "2025-01-20T10:30:00Z",
  "media_types": [],
  "name": "my-app",
  "namespace": "myorganization",
  "permissions": {
    "admin": true,
    "read": true,
    "write": true
  },
  "pull_count": 0,
  "repository_type": "image",
  "source": null,
  "star_count": 0,
  "status": 1,
  "status_description": "Active",
  "storage_size": null,
  "user": "myorganization"
}

Response 400

Bad Request

application/json

Schema: error

error

{
  "errinfo": null,
  "message": "bad request"
}

Response 401

Unauthorized

application/json

Schema: error

error

{
  "errinfo": null,
  "message": "unauthorized"
}

Response 403

Forbidden

application/json

Schema: error

error

{
  "errinfo": null,
  "message": "permission denied"
}

Response 404

Not Found

application/json

Schema: error

error

{
  "errinfo": null,
  "message": "not found"
}

Response 500

Internal

application/json

Schema: error

error

{
  "errinfo": null,
  "message": "internal error"
}

Referenced schemas

#/components/schemas/repo_creation_request

#/components/schemas/repository_info

Complete operation contract
{
  "description": "Creates a new repository within the specified namespace. The repository will be created\nwith the provided metadata including name, description, and privacy settings.\n\nThis operation accepts bearer tokens issued from organization access tokens (OATs). The token must have the required resource access and scopes.\n",
  "operationId": "CreateRepository",
  "requestBody": {
    "content": {
      "application/json": {
        "example": {
          "description": "A sample application repository",
          "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
          "is_private": false,
          "name": "my-app",
          "namespace": "myorganization",
          "registry": "docker.io"
        },
        "schema": {
          "$ref": "#/components/schemas/repo_creation_request"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "example": {
            "categories": [],
            "collaborator_count": 0,
            "content_types": [],
            "date_registered": "2025-01-20T10:30:00Z",
            "description": "A sample application repository",
            "full_description": "This is a comprehensive description of my application repository that contains additional details about the project.",
            "has_starred": false,
            "hub_user": "myorganization",
            "immutable_tags_settings": {
              "enabled": false,
              "rules": []
            },
            "is_automated": false,
            "is_private": false,
            "last_updated": "2025-01-20T10:30:00Z",
            "media_types": [],
            "name": "my-app",
            "namespace": "myorganization",
            "permissions": {
              "admin": true,
              "read": true,
              "write": true
            },
            "pull_count": 0,
            "repository_type": "image",
            "source": null,
            "star_count": 0,
            "status": 1,
            "status_description": "Active",
            "storage_size": null,
            "user": "myorganization"
          },
          "schema": {
            "$ref": "#/components/schemas/repository_info"
          }
        }
      },
      "description": "Repository created successfully"
    },
    "400": {
      "$ref": "#/components/responses/bad_request"
    },
    "401": {
      "$ref": "#/components/responses/unauthorized"
    },
    "403": {
      "$ref": "#/components/responses/forbidden"
    },
    "404": {
      "$ref": "#/components/responses/not_found"
    },
    "500": {
      "$ref": "#/components/responses/internal_error"
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "summary": "Create a new repository",
  "tags": [
    "repositories"
  ]
}