# Create a new repository


[API catalog](/reference/api/) · [Docker Hub overview](/reference/api/hub/latest/) · [Product manual](https://docs.docker.com/docker-hub/) · [OpenAPI specification](/reference/api/hub/latest.yaml)

API version: 2-beta



`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](/reference/api/hub/latest/#authentication)


Server: `https://hub.docker.com`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
[
  {
    "bearerAuth": []
  }
]
```
## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "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"
}' \
  'https://hub.docker.com/v2/namespaces/<NAMESPACE>/repositories'
```

## Parameters

### namespace

Location: path. Required: yes.

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

```json
{
  "description": "Namespace of the repository, such as a user or organization name.",
  "in": "path",
  "name": "namespace",
  "pointer": "/paths/~1v2~1namespaces~1{namespace}~1repositories/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Request  application/json




Schema:

```json
{
  "$ref": "#/components/schemas/repo_creation_request"
}
```




Example:
```json
{
  "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 application/json

Repository created successfully


Schema:

```json
{
  "$ref": "#/components/schemas/repository_info"
}
```




Example:
```json
{
  "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 application/json

Bad Request


Schema:

```json
{
  "$ref": "#/components/schemas/error"
}
```




error:
```json
{
  "errinfo": null,
  "message": "bad request"
}
```


### Response 401 application/json

Unauthorized


Schema:

```json
{
  "$ref": "#/components/schemas/error"
}
```




error:
```json
{
  "errinfo": null,
  "message": "unauthorized"
}
```


### Response 403 application/json

Forbidden


Schema:

```json
{
  "$ref": "#/components/schemas/error"
}
```




error:
```json
{
  "errinfo": null,
  "message": "permission denied"
}
```


### Response 404 application/json

Not Found


Schema:

```json
{
  "$ref": "#/components/schemas/error"
}
```




error:
```json
{
  "errinfo": null,
  "message": "not found"
}
```


### Response 500 application/json

Internal


Schema:

```json
{
  "$ref": "#/components/schemas/error"
}
```




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


## Complete operation contract

```json
{
  "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"
  ]
}
```

## Referenced schemas

- `#/components/responses/bad_request`

- `#/components/responses/forbidden`

- `#/components/responses/internal_error`

- `#/components/responses/not_found`

- `#/components/responses/unauthorized`

- [#/components/schemas/repo_creation_request](/reference/api/hub/latest/schemas/repo_creation_request/)

- [#/components/schemas/repository_info](/reference/api/hub/latest/schemas/repository_info/)