REST API (7)·续

REST API (7)·续

name RepoName required
description string optional
read_only boolean optional
default_branch_only boolean optional

Response type:

export interface ForkRepoRequest {
    name: RepoName;
    description?: string;
    read_only?: boolean;
    default_branch_only?: boolean;
}

export interface ForkRepoResult extends CreateRepoResult {
    objects: number;
}

export type ForkRepoResponse = ApiEnvelope<ForkRepoResult>;

curl --request POST "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/fork" \
    --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{
      "name": "starter-repo-copy",
      "description": "Fork for testing",
      "read_only": false,
      "default_branch_only": true
    }'

{
    "result": {
        "id": "repo_456",
        "name": "starter-repo-copy",
        "description": "Repository for automation experiments",
        "default_branch": "main",
        "remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo-copy.git",
        "token": "art_v1_89abcdef0123456789abcdef0123456789abcdef?expires=1760003600",
        "objects": 128
    },
    "success": true,
    "errors": [],
    "messages": []
}

Import a public HTTPS remote

Route: POST /artifacts/namespaces/:namespace/repos/:name/import

Request body:

url string required
branch string optional
depth number optional
read_only boolean optional

Response type:

export interface ImportRepoRequest {
    url: string;
    branch?: string;
    depth?: number;
    read_only?: boolean;
}

export type ImportRepoResponse = ApiEnvelope<CreateRepoResult>;

Pass a full HTTPS Git remote URL, for example https://github.com/facebook/react or https://gitlab.com/group/project.git.

curl --request POST "$ARTIFACTS_BASE_URL/repos/react-mirror/import" \
    --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{
      "url": "https://github.com/facebook/react",
      "branch": "main",
      "depth": 100
    }'

{
    "result": {
        "id": "repo_789",
        "name": "react-mirror",
        "description": null,
        "default_branch": "main",
        "remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/react-mirror.git",
        "token": "art_v1_fedcba9876543210fedcba9876543210fedcba98?expires=1760007200"
    },
    "success": true,
    "errors": [],
    "messages": []
}

If a repo exists but is still importing or forking, this route can return 409 Conflict with a retriable error message.

Repo content

These routes read Git objects and files from an existing repo. Object routes use immutable Git SHA-1 hashes. File routes resolve a path at a branch, tag, or commit hash.

Read commit history

Route: GET /artifacts/namespaces/:namespace/repos/:name/log?ref=&limit=&offset=

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/log?ref=main&limit=10" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Read a commit

Route: GET /artifacts/namespaces/:namespace/repos/:name/commit/:hash

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/commit/$COMMIT_HASH" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Read a tree

Route: GET /artifacts/namespaces/:namespace/repos/:name/tree/:hash

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/tree/$TREE_HASH" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Read a blob

Route: GET /artifacts/namespaces/:namespace/repos/:name/blob/:hash

Returns raw blob bytes.

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/blob/$BLOB_HASH" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Read a file

Route: GET /artifacts/namespaces/:namespace/repos/:name/file?ref=&path=

Returns raw file bytes as application/octet-stream.

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/file?ref=main&path=README.md" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Read a raw file

Route: GET /artifacts/namespaces/:namespace/repos/:name/raw/:ref/:path

Returns file bytes with a sniffed Content-Type.

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/raw/main/README.md" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Tokens

These tokens are for Git routes. They do not authenticate REST API requests.

List tokens for a repo

Route: GET /artifacts/namespaces/:namespace/repos/:name/tokens?state=&per_page=&page=

Query parameters:

state "active" | "expired" | "revoked" | "all" optional (default: "active")
per_page number optional (default: 30, max: 100)
page number optional (default: 1)

Response type:

export interface ListTokensQuery {
    state?: TokenState | "all";
    per_page?: number;
    page?: number;
}

export type ListTokensResponse = ApiEnvelope<TokenInfo[]>;

curl "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO/tokens?state=all&per_page=30&page=1" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
    "result": [
        {
            "id": "0123456789abcdef",
            "scope": "read",
            "state": "active",
            "created_at": "<ISO_TIMESTAMP>",
            "expires_at": "<ISO_TIMESTAMP>"
        }
    ],
    "success": true,
    "errors": [],
    "messages": [],
    "result_info": {
        "page": 1,
        "per_page": 30,
        "total_pages": 1,
        "count": 1,
        "total_count": 1
    }
}

Create a token

Route: POST /artifacts/namespaces/:namespace/tokens

Request body:

repo RepoName required
scope "read" | "write" optional (default: "write")
ttl number 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:

export interface CreateTokenRequest {
    repo: RepoName;
    scope?: Scope;
    ttl?: number;
}

export interface CreateTokenResult {
    id: string;
    plaintext: ArtifactToken;
    scope: Scope;
    expires_at: string;
}

export type CreateTokenResponse = ApiEnvelope<CreateTokenResult>;

curl --request POST "$ARTIFACTS_BASE_URL/tokens" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "repo": "starter-repo",
    "scope": "read",
    "ttl": 3600
  }'

{
    "result": {
        "id": "0123456789abcdef",
        "plaintext": "art_v1_0123456789abcdef0123456789abcdef01234567?expires=1760000000",
        "scope": "read",
        "expires_at": "<ISO_TIMESTAMP>"
    },
    "success": true,
    "errors": [],
    "messages": []
}

Revoke a token

Route: DELETE /artifacts/namespaces/:namespace/tokens/:id

Response type:

export interface DeleteTokenResult {
    id: string;
}

export type DeleteTokenResponse = ApiEnvelope<DeleteTokenResult>;

curl --request DELETE "$ARTIFACTS_BASE_URL/tokens/0123456789abcdef" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
    "result": {
        "id": "0123456789abcdef"
    },
    "success": true,
    "errors": [],
    "messages": []
}

Errors

Application errors also use the v4 envelope:

export interface ApiError {
    code: number;
    message: string;
    documentation_url?: string;
    source?: {
        pointer?: string;
    };
}

Next steps

Workers binding

Call the same Artifacts operations from a Worker through the Artifacts binding.

Git protocol

Use repo remotes and tokens with standard git-over-HTTPS tooling.

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/artifacts/api/rest-api/#page","headline":"REST API","description":"Manage Artifacts repos and tokens over HTTP.","url":"https://developers.cloudflare.com/artifacts/api/rest-api/","inLanguage":"en","image":"https://developers.cloudflare.com/artifacts/api/rest-api/og.png?v=203efb725994f626","dateModified":"2026-10-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Call Artifacts from a Worker binding. title: Workers binding image: https://developers.cloudflare.com/artifacts/api/workers-binding/og.png?v=8f6f94f63f1b3c24

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/artifacts/llms.txt
Use this file to discover all available pages before exploring further.

REST API (7)·续

REST API (7)·续

Import a public HTTPS remote

Repo content

Read commit history

Read a commit

Read a tree

Read a blob

Read a file

Read a raw file

Tokens

List tokens for a repo

Create a token

Revoke a token

Errors

Next steps

Workers binding

Git protocol

On this page