Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Namespaces

Artifacts uses namespaces as top-level containers for repositories. Use them to separate repositories by environment, such as prod, staging, and dev, by tenant, or shard.

Namespaces are created implicitly — there is no separate step to create one. You choose a namespace name, then reference it in your Wrangler config or REST API path. The first time you create a repository under that name, Artifacts creates the namespace for you automatically.

Use namespaces as containers

Start with one namespace per environment or tenant boundary.

  • Use environment namespaces such as prod, staging, or dev.
  • Use tenant or shard namespaces when one shared namespace would become too hot or too large.
  • Keep repository names unique within each namespace.

Choose a namespace name

Start with a stable name such as default, staging, or agents-realtime.

Namespace names follow the same public naming rules as repo names:

  • start with a letter or digit
  • use letters, digits, ., _, or - after the first character
  • keep the name stable across your Workers, API clients, and Git workflows

If you have not chosen a namespace strategy yet, use default in the examples throughout this docset.

Use the same namespace everywhere

Use the same namespace name in your Wrangler binding:

JSONC
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "default"
    }
  ]
}

Use that same namespace in your REST base URL:

Terminal window
export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
export ARTIFACTS_NAMESPACE="default"
export ARTIFACTS_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts/namespaces/$ARTIFACTS_NAMESPACE"

Split namespaces when needed

Start with one namespace when you are learning the product. Add more namespaces when you need clearer boundaries between environments, teams, or high-rate workloads.

For more information, refer to Best practices for Artifacts.