Create a project in a workspace
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
}Authorizations
Section titled “ Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”This can either be the workspace ID (slug) or the workspace UUID
surrounded by curly-braces, for example: {workspace UUID}.
Request Body required
Section titled “ Request Body required ”object
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
The project’s immutable id.
The project’s key.
object
Links related to an Account.
object
A link to a resource related to this object.
object
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
The name of the project.
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.
Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.
Example generated
{ "type": "example", "links": { "html": { "href": "https://example.com", "name": "example" }, "avatar": { "href": "https://example.com", "name": "example" } }, "uuid": "example", "key": "example", "owner": { "type": "example", "links": { "avatar": { "href": "https://example.com", "name": "example" }, "self": { "href": "https://example.com", "name": "example" }, "html": { "href": "https://example.com", "name": "example" }, "members": { "href": "https://example.com", "name": "example" }, "projects": { "href": "https://example.com", "name": "example" }, "repositories": { "href": "https://example.com", "name": "example" } }, "created_on": "2026-04-15T12:00:00Z", "display_name": "example", "uuid": "example" }, "name": "example", "description": "example", "is_private": true, "created_on": "2026-04-15T12:00:00Z", "updated_on": "2026-04-15T12:00:00Z", "has_publicly_visible_repos": true}Responses
Section titled “ Responses ”A new project has been created.
object
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
The project’s immutable id.
The project’s key.
object
Links related to an Account.
object
A link to a resource related to this object.
object
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
A link to a resource related to this object.
object
The name of the project.
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.
Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.
Example generated
{ "type": "example", "links": { "html": { "href": "https://example.com", "name": "example" }, "avatar": { "href": "https://example.com", "name": "example" } }, "uuid": "example", "key": "example", "owner": { "type": "example", "links": { "avatar": { "href": "https://example.com", "name": "example" }, "self": { "href": "https://example.com", "name": "example" }, "html": { "href": "https://example.com", "name": "example" }, "members": { "href": "https://example.com", "name": "example" }, "projects": { "href": "https://example.com", "name": "example" }, "repositories": { "href": "https://example.com", "name": "example" } }, "created_on": "2026-04-15T12:00:00Z", "display_name": "example", "uuid": "example" }, "name": "example", "description": "example", "is_private": true, "created_on": "2026-04-15T12:00:00Z", "updated_on": "2026-04-15T12:00:00Z", "has_publicly_visible_repos": true}Headers
Section titled “ Headers ”The location of the newly created project
The user requesting to create a project does not have the necessary permissions.
Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.
object
object
Optional structured data that is endpoint-specific.
object
Example generated
{ "type": "example", "error": { "message": "example", "detail": "example", "data": {} }}A workspace doesn’t exist at this location.
Base type for most resource objects. It defines the common type element that identifies an object’s type. It also identifies the element as Swagger’s discriminator.
object
object
Optional structured data that is endpoint-specific.
object
Example generated
{ "type": "example", "error": { "message": "example", "detail": "example", "data": {} }}