如何通过Bitbucket REST API在指定父项目下创建仓库？

我之前也碰到过这个坑，折腾了好一会儿才搞明白核心问题——大多是没找对project参数的正确格式，或者混淆了Bitbucket Cloud和Server的API差异。下面分情况给你讲清楚：

一、如果你用的是Bitbucket Cloud（云端版本） #

官方API要求请求体里的project是一个包含key字段的JSON对象，注意必须用项目的key，不是项目名称，这是最容易踩的坑！

正确的cURL示例： #

curl -X POST -u your-username:your-app-password \
  "https://api.bitbucket.org/2.0/repositories/your-workspace-slug" \
  -H "Content-Type: application/json" \
  -d '{
    "scm": "git",
    "name": "your-new-repo",
    "project": {
      "key": "PROJ"  # 这里填你目标项目的key，不是名称
    },
    "is_private": true
  }'

关键注意点： #

• 项目key在哪找？ 打开Bitbucket项目主页，URL里的最后一段就是key（比如https://bitbucket.org/your-workspace/proj里的proj），或者在项目设置的「General」标签页里也能看到。
• 一定要设置Content-Type: application/json请求头，否则Bitbucket会把请求体当成普通文本，无法解析JSON结构。
• 确保你的认证账号（或App Password）拥有该项目下创建仓库的权限，权限不足会返回看似参数错误的响应。

二、如果你用的是Bitbucket Server/Data Center（本地部署版本） #

这里的API逻辑不一样，创建仓库的端点本身就包含了项目key，不需要在请求体里传project对象：

正确的cURL示例： #

curl -X POST -u your-username:your-password \
  "http://your-bitbucket-server-url/rest/api/1.0/projects/PROJ/repos" \
  -H "Content-Type: application/json" \
  -d '{
    "scmId": "git",
    "name": "your-new-repo",
    "description": "Repo under specific project"
  }'

这里的PROJ就是目标项目的key，直接写在API路径里即可。

排障小技巧 #

如果还是失败，建议：

• 加上-v参数运行cURL，查看详细的响应内容，Bitbucket的错误信息会明确指出问题（比如「project not found」「invalid field」）。
• 先在Bitbucket网页端手动创建一个仓库，对比API请求的参数和网页端实际提交的参数（可以用浏览器开发者工具抓包），快速定位差异。

内容的提问来源于stack exchange，提问作者ZeaX