[Artifacts] Improve get-started guide for Workers (#30352)

* [Artifacts] Improve get-started guide for Workers

- Add try/catch error handling for repo creation with 409 conflict response
- Clarify returned values and their purposes
- Add bullet points explaining name and token fields
- Add step to switch to Worker directory before deploy
- Improve explanations throughout the guide

* Update src/content/docs/artifacts/get-started/workers.mdx

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* Update src/content/docs/artifacts/get-started/workers.mdx

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* [Artifacts] Additional documentation improvements

- Update namespaces concept page
- Expand git-client example with more details
- Improve isomorphic-git example
- Clarify REST API get-started instructions

* [Artifacts] Address PR feedback: simplify Workers example, add errors page, fix contractions

* Update errors.mdx

* [Artifacts] Update workers-binding docs: remove broken get() metadata access, add metadata notes to create/import/fork

* [Artifacts] Restructure errors page with linkable anchors for each error code

* [Artifacts] Add token events to event subscriptions docs

---------

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: dinasaur404

src/content/docs/artifacts/api/errors.mdx

@@ -0,0 +1,31 @@
+---
+title: Errors
+description: Error codes returned by the Artifacts REST API and Workers binding.
+pcx_content_type: reference
+sidebar:
+  order: 4
+head:
+  - tag: title
+    content: Errors · Artifacts
+products:
+  - artifacts
+---
+
+This is a list of Artifacts errors.
+
+## Error codes
+
+| Name | Code | Description |
+|------|------|-------------|
+| `ALREADY_EXISTS` | 10201 | The target repository already exists in the namespace. |
+| `NOT_FOUND` | 10200 | The repository or remote resource does not exist. |
+| `IMPORT_IN_PROGRESS` | 10302 | The repository is still being imported and is not yet available. |
+| `FORK_IN_PROGRESS` | 10303 | The repository is still being forked and is not yet available. |
+| `INVALID_INPUT` | 10100 | A request parameter is missing, malformed, or outside the accepted range. |
+| `INVALID_REPO_NAME` | 10101 | The repository name does not meet naming requirements. |
+| `INVALID_TTL` | 10103 | The token TTL is outside the allowed range (60–31,536,000 seconds). |
+| `INVALID_URL` | 10104 | The source URL does not point to a valid git repository. |
+| `REMOTE_AUTH_REQUIRED` | 10106 | The remote repository requires authentication. |
+| `UPSTREAM_UNAVAILABLE` | 10401 | The remote git server could not be reached. |
+| `MEMORY_LIMIT` | 10402 | The operation exceeds service memory limits. |
+| `INTERNAL_ERROR` | 10400 | An unexpected internal error occurred. |

src/content/docs/artifacts/api/rest-api.mdx

@@ -489,7 +489,7 @@ Request body:
 
 - `repo` <Type text="RepoName" /> <MetaInfo text="required" />
 - `scope` <Type text='"read" | "write"' /> <MetaInfo text='optional (default: "write")' />
-- `ttl` <Type text="number" /> <MetaInfo text="optional (seconds, default: 86400)" />
+- `ttl` <Type text="number" /> <MetaInfo text="optional" /> — Token time-to-live in seconds. Minimum 60 (1 minute), maximum 31,536,000 (1 year). Defaults to 86,400 (24 hours).
 
 Response type:
 

src/content/docs/artifacts/api/workers-binding.mdx

@@ -64,6 +64,8 @@ Use namespace methods on `env.ARTIFACTS` to create, list, inspect, import, or de
 - `opts.setDefaultBranch` <Type text="string" /> <MetaInfo text="optional" />
 - Returns <Type text="Promise<ArtifactsCreateRepoResult>" />
 
+`create()` returns repo metadata including `name`, `remote`, `defaultBranch`, and an initial token. Save these values if you need them later.
+
 <TypeScriptExample>
 
 ```ts
@@ -85,20 +87,21 @@ async function createRepo(artifacts: Artifacts) {
 
 </TypeScriptExample>
 
-The returned token encodes its expiry directly in the `?expires=` suffix.
-
 ### `get(name)`
 
 - `name` <Type text="RepoName" /> <MetaInfo text="required" />
 - Returns <Type text="Promise<ArtifactsRepo>" />
 - Throws if the repo does not exist or is not ready yet.
 
+`get()` returns a handle to an existing repo. Use the handle to call async methods on the repo, such as `createToken()`, `listTokens()`, `revokeToken()`, and `fork()`.
+
 <TypeScriptExample>
 
 ```ts
 async function getRepoHandle(artifacts: Artifacts) {
 	const repo = await artifacts.get("starter-repo");
-	return repo;
+	const token = await repo.createToken("read", 3600);
+	return token;
 }
 ```
 
@@ -142,6 +145,8 @@ Import a repository from an external git remote.
 - `params.target.opts.readOnly` <Type text="boolean" /> <MetaInfo text="optional" />
 - Returns <Type text="Promise<ArtifactsCreateRepoResult>" />
 
+`import()` returns repo metadata including `name`, `remote`, `defaultBranch`, and an initial token. Save the `remote` and `name` values if you need them later.
+
 <TypeScriptExample>
 
 ```ts
@@ -166,8 +171,6 @@ async function importFromGitHub(artifacts: Artifacts) {
 
 </TypeScriptExample>
 
-Imported repos return the same create-style token format. The token encodes its expiry directly in the `?expires=` suffix.
-
 ### `delete(name)`
 
 - `name` <Type text="RepoName" /> <MetaInfo text="required" />
@@ -185,18 +188,7 @@ async function deleteRepo(artifacts: Artifacts) {
 
 ## Repo handle methods
 
-Call `await artifacts.get(name)` to get a repo handle. The handle extends `ArtifactsRepoInfo`, so repo metadata (`id`, `name`, `remote`, `defaultBranch`, etc.) is available directly as properties.
-
-<TypeScriptExample>
-
-```ts
-async function getRemoteUrl(artifacts: Artifacts) {
-	const repo = await artifacts.get("starter-repo");
-	return repo.remote;
-}
-```
-
-</TypeScriptExample>
+Call `await artifacts.get(name)` to get a repo handle. Use the handle to call async methods on the repo.
 
 ### `createToken(scope?, ttl?)`
 
@@ -260,6 +252,8 @@ async function revokeToken(artifacts: Artifacts, tokenOrId: string) {
 - `opts.defaultBranchOnly` <Type text="boolean" /> <MetaInfo text="optional" />
 - Returns <Type text="Promise<ArtifactsCreateRepoResult>" />
 
+`fork()` returns metadata for the new repo. Save the `remote` and `name` values if you need them later.
+
 <TypeScriptExample>
 
 ```ts
@@ -300,24 +294,14 @@ export default {
 			});
 		}
 
-		if (request.method === "GET" && url.pathname === "/repos/starter-repo") {
-			const repo = await env.ARTIFACTS.get("starter-repo");
-			return Response.json({
-				id: repo.id,
-				name: repo.name,
-				remote: repo.remote,
-				defaultBranch: repo.defaultBranch,
-			});
-		}
-
 		if (request.method === "POST" && url.pathname === "/tokens") {
 			const repo = await env.ARTIFACTS.get("starter-repo");
 			const token = await repo.createToken("read", 3600);
 			return Response.json(token);
 		}
 
 		return Response.json(
-			{ message: "Use POST /repos, GET /repos/starter-repo, or POST /tokens." },
+			{ message: "Use POST /repos or POST /tokens." },
 			{ status: 404 },
 		);
 	},

src/content/docs/artifacts/concepts/namespaces.mdx

@@ -10,11 +10,9 @@ products:
 
 import { WranglerConfig } from "~/components";
 
-Artifacts uses namespaces as top-level containers for repositories. Use them to separate repositories by environment, such as `prod`, `staging`, and `dev`, or by tenant and shard.
+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.
 
-You do not create namespaces separately.
-
-Choose a namespace name, then use that name in your Wrangler config or REST API path when you create the first repo. Artifacts creates the namespace implicitly at that point.
+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
 

src/content/docs/artifacts/examples/git-client.mdx

@@ -8,40 +8,52 @@ products:
   - artifacts
 ---
 
-Use this pattern when you want to discover a repo over the REST API and then hand the returned HTTPS remote to a standard Git client.
+You can use a standard Git client to interact with Artifacts repos. This example walks through clone, but the same approach works for fetch, pull, push, and any other Git operation.
+
+To do this, you need to:
+- Fetch the repo's remote URL from the REST API
+- Mint a short-lived token scoped to that repo
+
+Once you have the remote URL and token, you can use them to run Git commands against the repo. 
 
 This example assumes the repo already exists and that you have a [Cloudflare API token](/fundamentals/api/get-started/create-token/) with **Artifacts** > **Edit**.
 
 ## Fetch the remote and clone the repo
 
-First, fetch the repo metadata from the REST API. Then mint a read token for that repo and use the returned remote with `git clone`.
+Replace the placeholder values with your account ID, API token, and repo name. The script fetches the repo's remote URL from the API, mints a read-only token that expires in one hour, and clones the repo to a local directory.
 
 The example below uses `jq` to extract fields from the JSON responses.
 
 ```bash
+# Set your account details
 export ACCOUNT_ID="<YOUR_ACCOUNT_ID>"
 export ARTIFACTS_NAMESPACE="default"
 export ARTIFACTS_REPO="starter-repo"
 export CLOUDFLARE_API_TOKEN="<YOUR_API_TOKEN>"
 export ARTIFACTS_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts/namespaces/$ARTIFACTS_NAMESPACE"
 
+# Fetch the repo's remote URL
 REPO_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO" \
   --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN")
 
 ARTIFACTS_REMOTE=$(printf '%s' "$REPO_JSON" | jq -r '.result.remote')
 
+# Mint a short-lived read token
 TOKEN_JSON=$(curl --silent "$ARTIFACTS_BASE_URL/tokens" \
   --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   --header "Content-Type: application/json" \
   --data "{\"repo\":\"$ARTIFACTS_REPO\",\"scope\":\"read\",\"ttl\":3600}")
 
 ARTIFACTS_TOKEN=$(printf '%s' "$TOKEN_JSON" | jq -r '.result.plaintext')
 
+# Clone the repo
 git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
 ```
+You now have a standard Git checkout in `./artifacts-clone`.
 
 This flow is useful when another system owns repo discovery or access control, but your local tooling still expects a normal git remote.
 
+### Authentication
 Treat `ARTIFACTS_TOKEN` as a secret. Keep it out of logs, and prefer `http.extraHeader` over saving credentials in a remote URL.
 
 If you need a self-contained remote URL for a short-lived workflow, extract the token secret and build the authenticated remote only for that command:

src/content/docs/artifacts/examples/isomorphic-git.mdx

@@ -10,11 +10,17 @@ products:
 
 import { Details, PackageManagers, TypeScriptExample } from "~/components";
 
-Use [isomorphic-git](https://isomorphic-git.org/) in a Cloudflare Worker when you need Git operations without a Git binary.
+Use [isomorphic-git](https://isomorphic-git.org/) to run Git operations on Artifacts repos directly from a Cloudflare Worker.
 
-This works with Artifacts because Artifacts exposes standard Git smart HTTP remotes. In Workers, pair `isomorphic-git/http/web` with a small in-memory filesystem because the runtime does not expose a local disk.
+The Artifacts binding creates and manages repos, but it cannot read or write files inside them — for that, you need Git. Since Workers do not have a git binary or a local filesystem, `isomorphic-git` fills that gap. It provides Git operations like init, commit, and push as JavaScript function calls, using an in-memory filesystem in place of a real disk.
 
-## Install the dependency
+Use this when your Worker needs to programmatically build and push file trees to an Artifacts repo — for example, an AI agent that generates code and commits it, or an automation that clones a repo, modifies files, and pushes changes back.
+
+## Prerequisites
+
+Follow the [Artifacts Workers setup guide](/artifacts/get-started/workers/) to set up a Worker with an Artifacts binding. 
+
+### Install the dependency
 
 Install `isomorphic-git` in your Worker project:
 
@@ -43,17 +49,20 @@ export interface Env {
 
 export default {
 	async fetch(_request: Request, env: Env) {
+		// Create a new Artifacts repo
 		const repoName = `worker-demo-${crypto.randomUUID().slice(0, 8)}`;
 		const created = await env.ARTIFACTS.create(repoName);
 
-		// Artifacts returns art_v1_<secret>?expires=<unix_seconds>.
-		// For Git Basic auth, pass only the secret as the password.
+		// Artifacts tokens include expiry metadata: art_v1_<secret>?expires=<unix_seconds>
+		// Git Basic auth expects only the token secret as the password
 		const tokenSecret = created.token.split("?expires=")[0];
+
+		// Set up an in-memory filesystem and initialize a Git repo
 		const dir = "/workspace";
 		const fs = new MemoryFS();
-
 		await git.init({ fs, dir, defaultBranch: "main" });
 
+		// Write files
 		await fs.promises.writeFile(
 			`${dir}/README.md`,
 			"# Artifacts repo created from a Worker\n",
@@ -63,6 +72,7 @@ export default {
 			'export const message = "hello from Artifacts";\n',
 		);
 
+		// Stage and commit
 		await git.add({ fs, dir, filepath: "README.md" });
 		await git.add({ fs, dir, filepath: "src/index.ts" });
 
@@ -76,6 +86,7 @@ export default {
 			},
 		});
 
+		// Push to the Artifacts remote
 		const push = await git.push({
 			fs,
 			http,

src/content/docs/artifacts/get-started/rest-api.mdx

@@ -29,11 +29,11 @@ You need:
 - A local `git` client.
 - `jq`, if you want to extract response fields automatically.
 
-For Workers-based access instead of direct HTTP calls, use the [Workers get started guide](/artifacts/get-started/workers/).
+If you want to create and manage repos directly from a Worker (instead of calling the REST API), use the [Workers get started guide](/artifacts/get-started/workers/).
 
 ## 1. Export your environment variables
 
-Set the variables used in the examples:
+Set the following variables using your Cloudflare account ID and Artifacts API token:
 
 ```sh
 export ARTIFACTS_NAMESPACE="default"
@@ -45,7 +45,7 @@ export ARTIFACTS_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUN
 
 Use a unique repo name each time you run this guide.
 
-Artifacts uses Bearer authentication for control-plane requests:
+Artifacts uses Bearer authentication for API requests:
 
 ```txt
 Authorization: Bearer $CLOUDFLARE_API_TOKEN
@@ -82,10 +82,11 @@ The response resembles the following:
 	"messages": []
 }
 ```
+The response includes two values which you will need for Git operations: 
+- `remote`: the Git remote URL for this repo. `<ACCOUNT_ID>` will be your actual Cloudflare account ID. Use this URL for all Git commands (git push, git clone). Note that this uses a different URL than the REST API you used to create the repo.
+- `token`: a short-lived credential for Git operations. The token encodes its expiry directly in the `?expires=` suffix as a Unix timestamp.
 
-The REST control-plane base URL and the returned Git remote use different hosts. Use the exact `result.remote` value for Git operations. The example above uses `<ACCOUNT_ID>` as a placeholder for your Cloudflare account ID.
 
-The returned token encodes its expiry directly in the `?expires=` suffix.
 
 Copy the `remote` and `token` values from `result` into local shell variables: