Skip to content
Console
On this page

Create an artifact

Registers an artifact whose bytes were pushed by digest; verification runs after.

Registers an artifact whose bytes were pushed by digest; verification runs after.

  • Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/artifacts
  • Scope artifacts:write
  • Effect write — a successful call changes state.
  • Collection artifacts
  • Query artifact_id, validate_only, managed_upload

Request

FieldTypeWhat it is
parentstringThe project to create in. Required.
artifactArtifactThe artifact to create; only spec and caller-writable metadata are read. Required.
artifact_idstringThe id of the new artifact, the digest with - for :; the server derives it from digest when empty; the server assigns one when empty.
validate_onlyboolValidate and return the result without writing anything.
managed_uploadboolThe bytes were pushed to this project's managed upload reference, so the registry is asked before the digest is registered: it must hold the manifest for digest in the project's managed repository, with this media_type and size_bytes. The record then carries the pull reference. Unset, the artifact is registered as given (generic registration), and reference stays empty.

Artifact

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/artifacts/{artifact}, where {artifact} is the digest with - for :, for example sha256-4f1c….
metaResourceMetaResource metadata.
digeststringThe algorithm-qualified digest of the stored bytes, for example sha256:4f1c…. Required.
kindArtifactKindWhat the Artifact is. Required. One of image, sbom, provenance, signature, bundle.
media_typestringThe media type, for example application/vnd.oci.image.manifest.v1+json. Required.
size_bytesint64The size of the stored bytes. Required.
subjectstringThe Artifact this one describes, for an SBOM, provenance, or signature.
source_digestsstring[]Digests of the sources and inputs that produced it.
retentionRetentionClassHow long the Artifact is kept. One of standard, referenced.

ResourceMeta

FieldTypeWhat it is
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.

Response

FieldTypeWhat it is
namestringorgs/{org}/projects/{project}/artifacts/{artifact}, where {artifact} is the digest with - for :, for example sha256-4f1c….
uidstringart_<cell><ulid>. Output only.
metaResourceMetaResource metadata.
digeststringThe algorithm-qualified digest of the stored bytes, for example sha256:4f1c…. Required.
kindArtifactKindWhat the Artifact is. Required. One of image, sbom, provenance, signature, bundle.
media_typestringThe media type, for example application/vnd.oci.image.manifest.v1+json. Required.
size_bytesint64The size of the stored bytes. Required.
subjectstringThe Artifact this one describes, for an SBOM, provenance, or signature.
source_digestsstring[]Digests of the sources and inputs that produced it.
builderstringThe builder identity (a SPIFFE id) that produced it. Output only.
sbomstringThe newest SBOM whose subject is this Artifact. Output only.
provenancestringThe newest provenance attestation whose subject is this Artifact. Output only.
verification_stateVerificationStateWhether the signature and provenance verified. Evidence, never identity: a failure does not change the digest. Output only. One of unverified, pending, verified, failed.
verify_timetimestampWhen verification last ran. Output only.
retentionRetentionClassHow long the Artifact is kept. One of standard, referenced.
legal_holdboolA legal hold is active; Delete fails. Output only.
regionsstring[]The regions the bytes are replicated to. Output only.
referencestringThe OCI reference by digest to pull, for example registry.sylphx.com/<org>/<project>-image@sha256:4f1c…. Set by the server for an Artifact registered from a managed upload; empty for a generic registration. Output only.

ResourceMeta

FieldTypeWhat it is
generationint64Increases by one on every change to spec. Output only.
etagstringStrong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as If-Match or etag to make Update and Delete conditional; a mismatch fails with ABORTED / 409 ETAG_MISMATCH. Output only.
create_timetimestampWhen the Resource was created. Output only.
update_timetimestampWhen the Resource last changed. Output only.
delete_timetimestampSet while the Resource is being deleted. Output only.
labelsmap<string, string>Caller-writable, indexed labels (AIP-122 label rules).
annotationsmap<string, string>Caller-writable, unindexed annotations.
display_namestringCaller-writable human-readable name.
creatorstringThe principal that created the Resource. Output only.

Errors

Every error arrives in the body Errors describes.

Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/artifacts" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"digest":"…","kind":"image","media_type":"…","size_bytes":1}'