REST API

REST API Artifacts použijte ke správě repozitářů, vzdálených úložišť, forků, importů a tokenů z externích systémů.

Zkontrolujte Jmenné prostory nejprve a poté zvolte název jmenného prostoru, který použijete v těchto cestách API.

Základní adresa URL a ověřování

Trasy REST API Artifacts používají tuto základní cestu:

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

Požadavky používají ověřování Bearer:

Authorization: Bearer $CLOUDFLARE_API_TOKEN

Cesty tras uvedené níže jsou zobrazeny relativně k /accounts/$ACCOUNT_ID. Příklady s curl používají ARTIFACTS_BASE_URL nebo ARTIFACTS_ACCOUNT_BASE_URL aby byly příkazy kratší.

Následující příklady předpokládají:

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"

Všechny odpovědi JSON používají standardní obálku Cloudflare v4:

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

Úspěšné odpovědi typu blob, file a raw vrací bajty souboru přímo namísto JSON. Například GET /artifacts/namespaces/:namespace/repos/:name/file?ref=main&path=README.md vrátí obsah README.md hodnotou Content-Type: application/octet-stream. Chybové odpovědi stále používají standardní obálku:

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

Vrácené tokeny repozitáře jsou tajné údaje. Nezaznamenávejte je do protokolů ani je neukládejte do dlouhodobě existujících vzdálených úložišť, pokud to váš pracovní postup nevyžaduje.

Sdílené typy

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

Jmenné prostory

Vytvoření jmenného prostoru

Trasa: POST /artifacts/namespaces

Použijte základní URL adresu na úrovni účtu.

Tělo požadavku:

namespace NamespaceName povinné
jurisdiction "eu" | "us" volitelné (výchozí: neomezeno)

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

Jurisdikce platí pro každý repozitář v namespace a po vytvoření ji nelze změnit. Pokud vynecháte jurisdiction, Artifacts vytvoří neomezený namespace.

Další informace najdete v tématu Lokalizace dat.

Seznam jmenných prostorů

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

Použijte základní URL adresu na úrovni účtu.

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

Získat jmenný prostor

Trasa: GET /artifacts/namespaces/:namespace

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

Repozitáře

Vytvoření repozitáře

Trasa: POST /artifacts/namespaces/:namespace/repos

Tělo požadavku:

name RepoName povinné
description string volitelné
default_branch BranchName volitelné
read_only boolean volitelné

Typ odpovědi:

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

Odpovědi na vytvoření, fork a import vracejí pouze řetězec tokenu. Token má svou platnost zakódovanou přímo v ?expires= přípona. Samostatný POST /tokens trasa také vrátí expires_at společně s tokenem v prostém textu.

Seznam repozitářů

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

Parametry dotazu:

limit number volitelné (výchozí: 50, max: 200)
cursor Cursor volitelné
search string volitelné
sort "created_at" | "updated_at" | "last_push_at" | "name" volitelné (výchozí: "created_at")
direction "asc" | "desc" volitelné (výchozí: "desc")

Typ odpovědi:

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

Získat repozitář

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

Typ odpovědi:

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

Odstranění repozitáře

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

Tato trasa vrací 202 Accepted.

Typ odpovědi:

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

Vytvořit fork repozitáře

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

Tělo požadavku:

name RepoName povinné
description string volitelné
read_only boolean volitelné
default_branch_only boolean volitelné

Typ odpovědi:

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 veřejného vzdáleného repozitáře HTTPS

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

Tělo požadavku:

url string povinné
branch string volitelné
depth number volitelné
read_only boolean volitelné

Typ odpovědi:

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

export type ImportRepoResponse = ApiEnvelope<CreateRepoResult>;

Zadejte úplnou vzdálenou adresu URL Git přes HTTPS, například https://github.com/facebook/react nebo 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": []
}

Pokud repozitář existuje, ale stále probíhá import nebo forkování, může tato trasa vrátit 409 Conflict se zprávou o chybě, kterou lze opakovat.

Obsah repozitáře

Tyto trasy čtou objekty Git a soubory z existujícího repozitáře. Trasy pro objekty používají neměnné hashe Git SHA-1. Trasy pro soubory překládají cestu na větev, tag nebo hash commitu.

Čtěte historii commitů

Trasa: 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"

Čtení commitu

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

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

Čtení stromu

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

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

Čtení blobu

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

Vrátí nezpracované bajty blobu.

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

Čtení souboru

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

Vrátí nezpracované bajty souboru jako application/octet-stream.

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

Čtení nezpracovaného souboru

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

Vrátí bajty souboru s rozpoznaným Content-Type.

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

Tokeny

Tyto tokeny slouží pro trasy Git, nikoli k autentizaci požadavků REST API.

Seznam tokenů pro repozitář

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

Parametry dotazu:

state "active" | "expired" | "revoked" | "all" volitelné (výchozí: "active")
per_page number volitelné (výchozí: 30, max: 100)
page number volitelné (výchozí: 1)

Typ odpovědi:

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

Vytvoření tokenu

Trasa: POST /artifacts/namespaces/:namespace/tokens

Tělo požadavku:

repo RepoName povinné
scope "read" | "write" volitelné (výchozí: "write")
ttl number volitelné : Doba života tokenu v sekundách. Minimum je 60 (1 minuta), maximum 31,536,000 (1 rok). Výchozí hodnota je 86,400 (24 hodin).

Typ odpovědi:

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

Zrušit platnost tokenu

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

Typ odpovědi:

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

Chyby

Chyby aplikace rovněž používají obálku v4:

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

Další kroky

Workers binding

Zavolejte stejné operace Artifacts z Workeru prostřednictvím bindingu Artifacts.

Git protokol

Vzdálená úložiště repozitářů a tokeny používejte se standardními nástroji git-over-HTTPS.