---
title: "Create a project in a workspace"
method: POST
path: "/workspaces/{workspace}/projects"
tags: ["Projects"]
---

# Create a project in a workspace

`POST /workspaces/{workspace}/projects`

Creates a new project.

Note that the avatar has to be embedded as either a data-url
or a URL to an external image as shown in the examples below:

```
$ body=$(cat << EOF
{
    "name": "Mars Project",
    "key": "MARS",
    "description": "Software for colonizing mars.",
    "links": {
        "avatar": {
            "href": "data:image/gif;base64,R0lGODlhEAAQAMQAAORHHOVSKudfOulrSOp3WOyDZu6QdvCchPGolfO0o/..."
        }
    },
    "is_private": false
}
EOF
)
$ curl -H "Content-Type: application/json" \
       -X POST \
       -d "$body" \
       https://api.bitbucket.org/2.0/workspaces/teams-in-space/projects/ | jq .
{
  // Serialized project document
}
```

or even:

```
$ body=$(cat << EOF
{
    "name": "Mars Project",
    "key": "MARS",
    "description": "Software for colonizing mars.",
    "links": {
        "avatar": {
            "href": "http://i.imgur.com/72tRx4w.gif"
        }
    },
    "is_private": false
}
EOF
)
$ curl -H "Content-Type: application/json" \
       -X POST \
       -d "$body" \
       https://api.bitbucket.org/2.0/workspaces/teams-in-space/projects/ | jq .
{
  // Serialized project document
}
```

## Request body

- Project — A Bitbucket project. Projects are used by teams to organize repositories.
  - `type` string, required
  - `links` object
    - `html` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
    - `avatar` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
  - `uuid` string — The project's immutable id.
  - `key` string — The project's key.
  - `owner` Team — A team object.
    - `type` string, required
    - `links` object — Links related to a Team.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `self` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `html` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `members` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `projects` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `repositories` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `name` string — The name of the project.
  - `description` string
  - `is_private` boolean — Indicates whether the project is publicly accessible, or whether it is private to the team and consequently only visible to team members. Note that private projects cannot contain public repositories.
  - `created_on` string, date-time
  - `updated_on` string, date-time
  - `has_publicly_visible_repos` boolean — Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.

## Response `201`

A new project has been created.

- Project — A Bitbucket project. Projects are used by teams to organize repositories.
  - `type` string, required
  - `links` object
    - `html` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
    - `avatar` object — A link to a resource related to this object.
      - `href` string, uri
      - `name` string
  - `uuid` string — The project's immutable id.
  - `key` string — The project's key.
  - `owner` Team — A team object.
    - `type` string, required
    - `links` object — Links related to a Team.
      - `avatar` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `self` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `html` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `members` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `projects` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
      - `repositories` Link — A link to a resource related to this object.
        - `href` string, uri
        - `name` string
    - `created_on` string, date-time
    - `display_name` string
    - `uuid` string
  - `name` string — The name of the project.
  - `description` string
  - `is_private` boolean — Indicates whether the project is publicly accessible, or whether it is private to the team and consequently only visible to team members. Note that private projects cannot contain public repositories.
  - `created_on` string, date-time
  - `updated_on` string, date-time
  - `has_publicly_visible_repos` boolean — Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.

## Other responses

- `403` — The user requesting to create a project does not have the necessary permissions.
- `404` — A workspace doesn't exist at this location.

---

[API](https://skmtc.net/bitbucket/apis/bitbucket-api.md) · [All operations](https://skmtc.net/bitbucket/apis/bitbucket-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bitbucket/bitbucket-api/versions/7e9be973015d/schema)