REST API

外部システムから、Artifacts の REST API でリポジトリ、リモート、フォーク、インポート、トークンを管理できます。

先に Namespaces を確認し、これらの API パスで使う名前空間名を決めてください。

ベース URL と認証

Artifacts の REST ルートは、次のベースパスを使います。

https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts/namespaces/$ARTIFACTS_NAMESPACE

リクエストは Bearer 認証を使います。

Authorization: Bearer $CLOUDFLARE_API_TOKEN

以下のルートパスは /accounts/$ACCOUNT_ID からの相対パスです。curl の例では、コマンドを短くするために ARTIFACTS_BASE_URL または ARTIFACTS_ACCOUNT_BASE_URL を使います。

次の例では、次の前提で説明します。

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"
export ARTIFACTS_ACCOUNT_BASE_URL="https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/artifacts"

JSON レスポンスはすべて、標準の Cloudflare v4 エンベロープを使います。

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

成功した blob、ファイル、raw のレスポンスは、JSON ではなくファイルのバイト列を直接返します。たとえば、GET /artifacts/namespaces/:namespace/repos/:name/file?ref=main&path=README.md は、Content-Type: application/octet-stream で README.md の内容を返します。エラーレスポンスは、引き続き標準のエンベロープを使います。

{
	"result": null,
	"success": false,
	"errors": [
		{
			"code": 10200,
			"message": "File not found"
		}
	],
	"messages": []
}

返されたリポジトリトークンはシークレットです。ログに残したり、ワークフローで必要でない限り、長期間使うリモートに保存したりしないでください。

共有型

export type NamespaceName = string;
export type Jurisdiction = "eu" | "us";
export type RepoName = string;
export type BranchName = string;
export type Scope = "read" | "write";
export type TokenState = "active" | "expired" | "revoked";
export type ArtifactToken = string;
export type Cursor = string;
export type RepoSortField =
	| "created_at"
	| "updated_at"
	| "last_push_at"
	| "name";
export type SortDirection = "asc" | "desc";

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

export interface CursorResultInfo {
	cursor: string;
	per_page: number;
	count: number;
}

export interface OffsetResultInfo {
	page: number;
	per_page: number;
	total_pages: number;
	count: number;
	total_count: number;
}

export type ResultInfo = CursorResultInfo | OffsetResultInfo;

export interface ApiEnvelope<T> {
	result: T | null;
	success: boolean;
	errors: ApiError[];
	messages: ApiError[];
	result_info?: ResultInfo;
}

export interface RepoInfo {
	id: string;
	name: RepoName;
	description: string | null;
	default_branch: string;
	created_at: string;
	updated_at: string;
	last_push_at: string | null;
	source: string | null;
	read_only: boolean;
}

export interface RepoWithRemote extends RepoInfo {
	remote: string;
}

export interface TokenInfo {
	id: string;
	scope: Scope;
	state: TokenState;
	created_at: string;
	expires_at: string;
}

名前空間

名前空間を作成する

Route: POST /artifacts/namespaces

アカウントレベルのベース URL を使います。

リクエスト本文:

namespace NamespaceName 必須
jurisdiction "eu" | "us" 任意（デフォルト: unrestricted）

curl --request POST "$ARTIFACTS_ACCOUNT_BASE_URL/namespaces" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "namespace": "my-eu-namespace",
    "jurisdiction": "eu"
  }'

管轄（jurisdiction）は、名前空間内のすべてのリポジトリに適用され、作成後は変更できません。jurisdiction を省略すると、Artifacts は制限なしの名前空間を作成します。

詳しくは、Data localization を参照してください。

名前空間を一覧する

Route: GET /artifacts/namespaces?limit=&cursor=

アカウントレベルのベース URL を使います。

curl "$ARTIFACTS_ACCOUNT_BASE_URL/namespaces?limit=20" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

名前空間を取得する

Route: GET /artifacts/namespaces/:namespace

curl "$ARTIFACTS_ACCOUNT_BASE_URL/namespaces/$ARTIFACTS_NAMESPACE" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

リポジトリ

リポジトリを作成する

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

リクエスト本文:

name RepoName 必須
description string 任意
default_branch BranchName 任意
read_only boolean 任意

レスポンスの型:

export interface CreateRepoRequest {
	name: RepoName;
	description?: string;
	default_branch?: BranchName;
	read_only?: boolean;
}

export interface CreateRepoResult {
	id: string;
	name: RepoName;
	description: string | null;
	default_branch: string;
	remote: string;
	token: ArtifactToken;
}

export type CreateRepoResponse = ApiEnvelope<CreateRepoResult>;

curl --request POST "$ARTIFACTS_BASE_URL/repos" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "starter-repo",
    "description": "Repository for automation experiments",
    "default_branch": "main",
    "read_only": false
  }'

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

作成、フォーク、インポートのレスポンスは、トークン文字列だけを返します。トークンは有効期限を ?expires= サフィックスに直接含めます。別の POST /tokens ルートは、平文トークンとともに expires_at も返します。

リポジトリを一覧する

Route: GET /artifacts/namespaces/:namespace/repos?limit=&cursor=&search=&sort=&direction=

クエリパラメーター:

limit number 任意（デフォルト: 50、最大: 200）
cursor Cursor 任意
search string 任意
sort "created_at" | "updated_at" | "last_push_at" | "name" 任意（デフォルト: "created_at"）
direction "asc" | "desc" 任意（デフォルト: "desc"）

レスポンスの型:

export interface ListReposQuery {
	limit?: number;
	cursor?: Cursor;
	search?: string;
	sort?: RepoSortField;
	direction?: SortDirection;
}

export type ListReposResponse = ApiEnvelope<RepoWithRemote[]>;

curl "$ARTIFACTS_BASE_URL/repos?limit=20&sort=updated_at&direction=desc" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

{
	"result": [
		{
			"id": "repo_123",
			"name": "starter-repo",
			"description": "Repository for automation experiments",
			"default_branch": "main",
			"created_at": "<ISO_TIMESTAMP>",
			"updated_at": "<ISO_TIMESTAMP>",
			"last_push_at": "<ISO_TIMESTAMP>",
			"source": null,
			"read_only": false,
			"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git"
		}
	],
	"success": true,
	"errors": [],
	"messages": [],
	"result_info": {
		"cursor": "next-cursor",
		"per_page": 20,
		"count": 1
	}
}

リポジトリを取得する

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

レスポンスの型:

export type GetRepoResponse = ApiEnvelope<RepoWithRemote>;

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

{
	"result": {
		"id": "repo_123",
		"name": "starter-repo",
		"description": "Repository for automation experiments",
		"default_branch": "main",
		"created_at": "<ISO_TIMESTAMP>",
		"updated_at": "<ISO_TIMESTAMP>",
		"last_push_at": "<ISO_TIMESTAMP>",
		"source": null,
		"read_only": false,
		"remote": "https://<ACCOUNT_ID>.artifacts.cloudflare.net/git/default/starter-repo.git"
	},
	"success": true,
	"errors": [],
	"messages": []
}

リポジトリを削除する

Route: DELETE /artifacts/namespaces/:namespace/repos/:name

このルートは 202 Accepted を返します。

レスポンスの型:

export interface DeleteRepoResult {
	id: string;
}

export type DeleteRepoResponse = ApiEnvelope<DeleteRepoResult>;

curl --request DELETE "$ARTIFACTS_BASE_URL/repos/$ARTIFACTS_REPO" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

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

リポジトリをフォークする

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

リクエスト本文:

name RepoName 必須
description string 任意
read_only boolean 任意
default_branch_only boolean 任意

レスポンスの型:

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": []
}

公開 HTTPS リモートをインポートする

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

リクエスト本文:

url string 必須
branch string 任意
depth number 任意
read_only boolean 任意

レスポンスの型:

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

export type ImportRepoResponse = ApiEnvelope<CreateRepoResult>;

完全な HTTPS の Git リモート URL を渡します。例: https://github.com/facebook/react または 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": []
}

リポジトリが存在するが、インポートまたはフォークの途中である場合、このルートは再試行可能なエラーメッセージ付きで 409 Conflict を返すことがあります。

リポジトリのコンテンツ

これらのルートは、既存リポジトリから Git オブジェクトとファイルを読み取ります。オブジェクト用ルートは不変の Git SHA-1 ハッシュを使います。ファイル用ルートは、ブランチ、タグ、またはコミットハッシュでパスを解決します。

コミット履歴を読む

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"

コミットを読む

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"

ツリーを読む

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"

blob を読む

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

blob の生バイト列を返します。

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

ファイルを読む

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

application/octet-stream としてファイルの生バイト列を返します。

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

raw ファイルを読む

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

推定した Content-Type でファイルのバイト列を返します。

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

トークン

これらのトークンは Git ルート用です。REST API リクエストの認証には使いません。

リポジトリのトークンを一覧する

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

クエリパラメーター:

state "active" | "expired" | "revoked" | "all" 任意（デフォルト: "active"）
per_page number 任意（デフォルト: 30、最大: 100）
page number 任意（デフォルト: 1）

レスポンスの型:

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
	}
}

トークンを作成する

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

リクエスト本文:

repo RepoName 必須
scope "read" | "write" 任意（デフォルト: "write"）
ttl number 任意 — トークンの有効期間（秒）。最小 60（1 分）、最大 31,536,000（1 年）。デフォルトは 86,400（24 時間）です。

レスポンスの型:

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": []
}

トークンを取り消す

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

レスポンスの型:

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": []
}

エラー

アプリケーションエラーも v4 エンベロープを使います。

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

次のステップ

Workers binding

Worker から Artifacts バインディングを通じて、同じ Artifacts 操作を呼び出します。

Git protocol

標準の git-over-HTTPS ツールで、リポジトリのリモートとトークンを使います。