1# Artifacts API Reference
2 
3Use Artifacts through the **Workers binding**, the **REST control plane**, and **Git-compatible remotes**.
4 
5**Prefer retrieval** for exact request and response details. Verify current behavior at `https://developers.cloudflare.com/artifacts/` before relying on specific auth flows, route details, or generated binding types.
6 
7## Workers Binding
8 
9Artifacts exposes a Worker binding on `env.ARTIFACTS`.
10 
11### Namespace Methods
12 
13| Method | Use For |
14|--------|---------|
15| `create(name, opts?)` | Create a repo and receive its initial remote and token |
16| `get(name)` | Resolve a repo handle for repo-scoped operations |
17| `list(opts?)` | List repos in a namespace |
18| `delete(name)` | Delete a repo |
19 
20```typescript
21const created = await env.ARTIFACTS.create("starter-repo", {
22  description: "Repository for automation experiments",
23  setDefaultBranch: "main"
24});
25const repo = await env.ARTIFACTS.get("starter-repo");
26const page = await env.ARTIFACTS.list({ limit: 10 });
27```
28 
29Use the REST API when you need to import a repo from another HTTPS remote.
30 
31### Repo Handle Methods
32 
33Use a repo handle returned by `get()` or `create()`.
34 
35| Method | Use For |
36|--------|---------|
37| `info()` | Read repo metadata, including the remote URL |
38| `createToken(scope?, ttl?)` | Mint a repo-scoped read or write token |
39| `listTokens()` | Inspect active tokens |
40| `validateToken(token)` | Check whether a token is still valid |
41| `revokeToken(tokenOrId)` | Revoke a token by ID or value |
42| `fork(name, opts?)` | Fork one repo into another |
43 
44```typescript
45const repo = await env.ARTIFACTS.get("starter-repo");
46if (!repo) throw new Error("Repo not found");
47 
48const info = await repo.info();
49const token = await repo.createToken("read", 3600);
50const forked = await repo.fork("starter-repo-copy", {
51  defaultBranchOnly: true
52});
53```
54 
55### Binding Notes
56 
57- Current docs describe the runtime binding surface as `create`, `get`, `list`, `delete`, and repo-handle methods like `info`, `createToken`, and `fork`.
58- Use `npx wrangler types` in the target project and treat the generated `worker-configuration.d.ts` as the source of truth for that environment.
59- If generated types appear to expose `import()` or a different `get()` shape, verify the live docs before depending on those methods.
60 
61Verify current runtime behavior in the live docs before depending on methods that are not shown in the Workers binding reference.
62 
63## REST API
64 
65Artifacts currently documents a namespace-scoped control plane:
66 
67```txt
68https://artifacts.cloudflare.net/v1/api/namespaces/$ARTIFACTS_NAMESPACE
69```
70 
71Some deployments also expose an `/edge/v1/api/...` base path. Verify the correct base URL for your environment in the live docs.
72 
73Requests to the standard `/v1/api/...` routes use a **gateway JWT** with Bearer authentication.
74 
75Returned repo tokens authenticate **Git operations** against the repo `remote`. They do not authenticate REST control-plane requests.
76 
77Current docs show the standard Cloudflare v4 response envelope around REST results.
78 
79### Repo Routes
80 
81| Route | Use For |
82|-------|---------|
83| `POST /repos` | Create a repo |
84| `GET /repos` | List repos |
85| `GET /repos/:name` | Read repo metadata and remote |
86| `DELETE /repos/:name` | Delete a repo |
87| `POST /repos/:name/fork` | Fork a repo |
88| `POST /repos/:name/import` | Import a public HTTPS remote |
89 
90```bash
91curl --request POST "$ARTIFACTS_BASE_URL/repos" \
92  --header "Authorization: Bearer $ARTIFACTS_JWT" \
93  --header "Content-Type: application/json" \
94  --data '{"name":"starter-repo"}'
95```
96 
97Important current details from the docs draft:
98- `POST /repos/:name/import` accepts a full HTTPS remote URL such as GitHub or GitLab.
99- Import supports options such as `branch`, `depth`, and `read_only`.
100- Repo metadata includes fields such as description, default branch, timestamps, and the Git `remote`.
101 
102### Token Routes
103 
104| Route | Use For |
105|-------|---------|
106| `GET /repos/:name/tokens` | List repo tokens |
107| `POST /tokens` | Create a token for a repo |
108| `DELETE /tokens/:id` | Revoke a token by ID |
109 
110Current docs show list-token filtering and pagination by token state. Retrieve the exact query shape from the live docs when you need token audit or cleanup workflows.
111 
112Use **read** tokens for clone, fetch, pull, and indexing workflows. Use **write** tokens only when a workflow must push or otherwise mutate a repo.
113 
114## Git-Compatible Access
115 
116Artifacts returns repo `remote` URLs that work with standard git-over-HTTPS tooling.
117 
118Recommended current auth pattern for local workflows:
119 
120```bash
121git -c http.extraHeader="Authorization: Bearer $ARTIFACTS_TOKEN" clone "$ARTIFACTS_REMOTE" artifacts-clone
122```
123 
124Use a self-contained Basic-auth remote only for short-lived commands that need credentials embedded in the URL.
125 
126`read` tokens support `clone`, `fetch`, and `pull`. `git push` requires a `write` token.
127 
128For large repos where startup time matters more than a full clone, Artifacts also documents **ArtifactFS**. Retrieve current details from `https://developers.cloudflare.com/artifacts/` when you need mount-style access.
129