Skip to main content
POST
Add a Custom Domain for Blob Storage
Adds a subdomain, such as cdn.example.com, that serves the account’s public blob files. Create a CNAME record of that hostname pointing to cname_target and the TXT record from verification, then call Verify a custom domain. The number of domains depends on the plan: 0 below Enterprise-4, then 1, 3 and 10. Returns 201. Scope: blob:write.
string
required
Subdomain only, without a scheme or path.
string
Serve only this folder on the domain. Omit it to serve the whole account.
boolean
Defaults to false. When true, the domain serves .html, .htm, .xhtml, .svg and .xml files in the browser with their real type, sandboxed. See Custom domains.
string
The workspace ID, when the blob belongs to a workspace. The call acts on the blob of the workspace owner and needs the blob:read workspace permission (blob:manage on routes that change data). Leave it out to act on your own blob.

Example request

Response

object
The domain, still pending until the CNAME is found and the ownership TXT record is verified. It only becomes active after both. Responds with 201.

Error Responses

string
The error code indicating the reason for failure. Possible values:
  • AUTH_TOKEN_MISSING (401): No Authorization header was sent.
  • API_KEY_INVALID (401): The API key doesn’t exist, was revoked, or its secret doesn’t match.
  • API_KEY_SCOPE_DENIED (403): The key lacks the scope this route needs (blob:read or blob:write); details.required names it.
  • WORKSPACE_PERMISSION_DENIED (403): Only with workspace_id: you’re not a member, or your role lacks the blob permission.
  • WORKSPACE_NOT_FOUND (404): Only with workspace_id: no workspace with that ID, or you’re not a member.
  • VALIDATION_ERROR (400): A parameter or body field failed validation. details.path names the field.
  • INVALID_CUSTOM_DOMAIN_FORMAT (400): The hostname isn’t a valid subdomain.
  • PLAN_RESTRICTED_FEATURE (403): The plan has no custom domains (below Enterprise-4).
  • BLOB_NAMESPACE_SUSPENDED (403): The account’s blob storage is suspended, or its plan expired.
  • BLOB_CUSTOM_DOMAIN_LIMIT (409): The plan includes custom domains and the limit is reached.
  • BLOB_CUSTOM_DOMAIN_TAKEN (409): The hostname is already in use.