Skip to content
rpicx
⌕ESC

输入关键词，搜索文档与 API

↑↓ 选择↵ 打开ESC 关闭

POST /api/v1/projects/{projectId}/domains

API 参考/project
POST/api/v1/projects/{projectId}/domains

接入自定义域名（需 admin 及以上，API Key 不可用；需项目开通 allow_custom_domain 权益）

projectoperationId: projectDomainCreate

请求参数

名称类型位置必填说明
projectIdstringpath是项目 ID（UUID）。携带 `X-API-Key` 时按 API Key scope 鉴权，否则按 JWT + 项目成员角色鉴权

请求体

请求数据

Content-Type · application/json

{
  "type": "object",
  "required": [
    "domain"
  ],
  "properties": {
    "domain": {
      "type": "string",
      "description": "小写主机名，禁止协议/端口/通配符，全局唯一"
    },
    "storage_id": {
      "type": "string",
      "format": "uuid",
      "description": "可选，须属于本项目且 status=active"
    }
  }
}

请求示例

cURL
curl -X POST 'http://localhost:8080/api/v1/projects/{projectId}/domains' \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <PROJECT_API_KEY>'
# 也可使用登录会话：-H 'Authorization: Bearer <JWT>'
JavaScript
const res = await fetch('http://localhost:8080/api/v1/projects/{projectId}/domains', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': '<PROJECT_API_KEY>'
  },
});
const data = await res.json();
Python
import requests

res = requests.post(
    'http://localhost:8080/api/v1/projects/{projectId}/domains',
    headers={'Accept': 'application/json', 'X-API-Key': '<PROJECT_API_KEY>'}
)
print(res.json())

响应

201创建成功（返回一次性验证 token，状态 pending_verification）

application/json

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "project_id": {
      "type": "string",
      "format": "uuid"
    },
    "storage_id": {
      "type": "string",
      "format": "uuid",
      "nullable": true
    },
    "domain": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "is_legacy": {
      "type": "boolean"
    },
    "verification_token": {
      "type": "string"
    },
    "verification_record_name": {
      "type": "string"
    },
    "verified_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "platform_cname_target": {
      "type": "string"
    },
    "cname_verified_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "ssl_status": {
      "type": "string"
    },
    "dns_suspended_at": {
      "type": "string",
      "format": "date-time",
      "nullable": true
    },
    "last_error": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
400请求参数错误

application/json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "example": "资源不存在"
    }
  }
}
403无权限（未通过 RBAC 或 2FA）

application/json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "example": "not_found"
    },
    "message": {
      "type": "string",
      "example": "资源不存在"
    }
  }
}

在线调试

在线调试
凭证仅保存在当前页面内存中
自定义请求 Header