artifacts

Services

RPC methods exposed by this API.

ArtifactService

ArtifactService manages an organization-scoped, versioned generic artifact store. storage_class decides whether content lives in remote_files or the version’s JSON payload. Attachment and provenance are links, and metadata uses the shared metadata values (sift.metadata.v1). No conversation owns an artifact. Links are append-only and belong to the version they were written at. A version’s rows are its complete link set: ATTACHED_TO rows carry forward to each new version, while SOURCE and DERIVED_FROM rows are a closed account of one version’s inputs. Linking and unlinking write a new version whose content is copied from the previous one. Artifact bytes live in remote_files (entity_type ‘artifact_versions’, entity_id = artifact_version_id): upload via the remote-files multipart endpoint, download via RemoteFileService.GetRemoteFileDownloadUrl.

Method	Request	Response	Description
CreateArtifact	CreateArtifactRequest	CreateArtifactResponse	Creates an artifact plus its version-1 entry. When conversation_id is set, the new artifact is also linked to that conversation. Use UpdateArtifact to add a version to an artifact that already exists.
UpdateArtifact	UpdateArtifactRequest	UpdateArtifactResponse	Writes a new version carrying the fields update_mask names. Everything the mask leaves out is copied from the latest version, so a caller can change one field without resending the rest.
GetArtifact	GetArtifactRequest	GetArtifactResponse	Resolves to the latest version unless artifact_version_id pins one.
ListArtifacts	ListArtifactsRequest	ListArtifactsResponse	One entry per artifact, resolved to its latest version, oldest first. With conversation_id set, only artifacts linked to that conversation; otherwise every artifact in the caller’s organization.
ListArtifactVersions	ListArtifactVersionsRequest	ListArtifactVersionsResponse	Full version history of one artifact, newest first.
PromoteArtifactVersion	PromoteArtifactVersionRequest	PromoteArtifactVersionResponse	Makes an older version the latest again by writing a new version whose title, summary, payload, metadata, and bytes are copied from it. The latest version’s ATTACHED_TO links carry forward. Only the artifact’s creator may promote, and promoting the current latest version is a FailedPrecondition.
LinkArtifactToConversation	LinkArtifactToConversationRequest	LinkArtifactToConversationResponse	Links an existing artifact to a conversation. Equivalent to LinkArtifact with relation ATTACHED_TO and entity_type CONVERSATION. Idempotent: linking an already-linked pair succeeds without effect.
UnlinkArtifactFromConversation	UnlinkArtifactFromConversationRequest	UnlinkArtifactFromConversationResponse	Removes one conversation’s link to an artifact. Equivalent to UnlinkArtifact with relation ATTACHED_TO and entity_type CONVERSATION, so it writes a new version that omits the link and carries the previous content forward. Idempotent: unlinking a missing link succeeds without writing a version.
ArchiveArtifact	ArchiveArtifactRequest	ArchiveArtifactResponse	Sets archived_date. Versions, bytes, and links are left in place. Idempotent: archiving an already-archived artifact succeeds without changing archived_date.
UnarchiveArtifact	UnarchiveArtifactRequest	UnarchiveArtifactResponse	Clears archived_date. Idempotent: unarchiving an active artifact succeeds without effect.

Messages

Data models used across requests/responses.

ArchiveArtifactRequest

Field	Type	Label	Description
artifact_id	string

ArchiveArtifactResponse

This message has no fields.

Artifact

The container. Everything that varies by version lives on ArtifactVersion, and the two travel together in ArtifactDetails.

Field	Type	Label	Description
artifact_id	string
organization_id	string
created_by_user_id	string
created_date	google.protobuf.Timestamp
archived_date	google.protobuf.Timestamp	optional	Unset while the artifact is active.
storage_class	ArtifactStorageClass
created_via	ArtifactCreatedVia
current_version_id	string		The artifact’s latest version. A pinned read reports it too, so a client holding an older version can tell that it is behind.

ArtifactDetails

An artifact and one of its versions: the one artifact_version_id pinned, or the latest.

Field	Type	Label	Description
artifact	Artifact
artifact_version	ArtifactVersion

ArtifactLinkInput

Field	Type	Label	Description
relation	ArtifactLinkRelation
entity_type	ArtifactEntityType
entity_id	string

ArtifactVersion

Field	Type	Label	Description
artifact_version_id	string
artifact_id	string
version	uint32
title	string	optional
summary	string	optional
authoring_message_id	string	optional	Set only for versions authored inside a conversation, and there only after the introducing message persists: uploads attach before the user sends, and agent turns persist messages only at end of turn.
source_tool_use_ids	string	repeated
remote_file_id	string	optional	Unset until bytes are uploaded.
created_date	google.protobuf.Timestamp
file_name	string	optional	From the version’s remote_files record. Unset until bytes are uploaded. Clients infer preview behavior from file_name / file_mime_type.
file_mime_type	string	optional
payload	google.protobuf.Struct	optional	Set by GetArtifact for STRUCTURED artifacts. The listings omit it.
metadata	sift.metadata.v1.MetadataValue	repeated	Metadata attached to this version.

CreateArtifactRequest

Field	Type	Label	Description
conversation_id	string	optional	Set to link the new artifact to a conversation at create time. Legal only for the conversation’s author. Equivalent to a links entry with relation ATTACHED_TO, entity_type CONVERSATION, and this conversation_id as entity_id.
title	string	optional
summary	string	optional
storage_class	ArtifactStorageClass	optional	A container field. Defaults to FILE when unset.
created_via	ArtifactCreatedVia	optional	A container field. Defaults to AGENT when unset. It also decides link attribution: an AGENT artifact’s links record no user, because the pod acts with the user’s key but the user granted nothing.
payload	google.protobuf.Struct	optional	Required for STRUCTURED and rejected otherwise. The serialized payload must not exceed 1 MiB.
links	ArtifactLinkInput	repeated	Links written at version 1.
metadata	sift.metadata.v1.MetadataValue	repeated	Metadata attached to the created version.

CreateArtifactResponse

Field	Type	Label	Description
artifact	ArtifactDetails

GetArtifactRequest

Field	Type	Label	Description
artifact_id	string
artifact_version_id	string	optional

GetArtifactResponse

Field	Type	Label	Description
artifact	ArtifactDetails

LinkArtifactToConversationRequest

Field	Type	Label	Description
artifact_id	string
conversation_id	string

LinkArtifactToConversationResponse

This message has no fields.

ListArtifactVersionsRequest

Field	Type	Label	Description
artifact_id	string
page_size	uint32
page_token	string

ListArtifactVersionsResponse

Field	Type	Label	Description
versions	ArtifactVersion	repeated
next_page_token	string

ListArtifactsRequest

Field	Type	Label	Description
conversation_id	string	optional	Unset lists every artifact in the caller’s organization.
page_size	uint32
page_token	string
filter	string		A Common Expression Language (CEL) filter string. Available fields are artifact_id, organization_id, created_by_user_id, storage_class, created_via, title, file_name, file_type, version, created_date, version_created_date (last updated), archived_date, the include_archived directive, and metadata through `metadata["<key>"]`. File type is the lowercase extension or MIME subtype; images use “image”, structured artifacts use “json”, and artifacts without a file use “file”. Links can be filtered with a comprehension such as `links.exists(l, l.relation == "ATTACHED_TO" && l.entity_type == "CONVERSATION" && l.entity_id == "<id>")`. Link sub-fields are relation, entity_type, entity_id, and artifact_version_id. Enum fields compare against proto value names without the prefix, for example `storage_class == "STRUCTURED"`, `relation == "ATTACHED_TO"`, and `entity_type == "CONVERSATION"`. The conversation_id field on this message combines with filter.

Archived artifacts are excluded unless the query says otherwise, either through include_archived == true or by filtering on archived_date, which governs archival on its own. | | order_by | string | | A comma-separated AIP-132 ordering string over created_date, version_created_date (last updated), archived_date, title, version, and file_type. Fields sort ascending by default and support a desc suffix. The default is created_date ascending. |

ListArtifactsResponse

Field	Type	Label	Description
artifacts	ArtifactDetails	repeated
next_page_token	string

PromoteArtifactVersionRequest

Field	Type	Label	Description
artifact_id	string
artifact_version_id	string		The version whose content becomes the new latest version.

PromoteArtifactVersionResponse

Field	Type	Label	Description
artifact	ArtifactDetails		The artifact resolved to the version this call wrote.

UnarchiveArtifactRequest

Field	Type	Label	Description
artifact_id	string

UnarchiveArtifactResponse

This message has no fields.

UnlinkArtifactFromConversationRequest

Field	Type	Label	Description
artifact_id	string
conversation_id	string

UnlinkArtifactFromConversationResponse

This message has no fields.

UpdateArtifactRequest

Field	Type	Label	Description
artifact_id	string
artifact	ArtifactDetails		Carries the values update_mask names. Only artifact_version fields are updatable; the container’s own fields are set at create time, and archival has its own RPCs. Leaving it out clears every field the mask names.
links	ArtifactLinkInput	repeated	Links written at the new version, when update_mask names `links`. The previous version’s ATTACHED_TO rows carry forward and these are added to them.
update_mask	google.protobuf.FieldMask		The fields to write. Available paths are `artifact_version.title`, `artifact_version.summary`, `artifact_version.payload`, `artifact_version.metadata`, `artifact_version.remote_file_id`, and `links`. A path the service does not know is rejected.

artifact_version.remote_file_id is a declaration, not a value: it says the caller is about to upload new bytes for the returned version, so the previous version’s remote_files rows are not carried forward. The current version stays unchanged until the upload commits. The request value is ignored. Leave the path out to keep the existing bytes. |

UpdateArtifactResponse

Field	Type	Label	Description
artifact	ArtifactDetails

Enums

Allowed constant values used in message fields.

ArtifactCreatedVia

Which surface wrote the artifact.

Name	Number	Description
ARTIFACT_CREATED_VIA_UNSPECIFIED	0	The producing surface is not specified.
ARTIFACT_CREATED_VIA_AGENT	1	An agent wrote the artifact.
ARTIFACT_CREATED_VIA_CANVAS	2	Canvas wrote the artifact.
ARTIFACT_CREATED_VIA_UPLOAD	3	A direct upload wrote the artifact.

ArtifactEntityType

The kind of entity an artifact link points at. entity_id is opaque: a UUID for Sift entities, or the provider tool_use_id for TOOL_USE.

Name	Number	Description
ARTIFACT_ENTITY_TYPE_UNSPECIFIED	0	The entity type is not specified.
ARTIFACT_ENTITY_TYPE_CONVERSATION	1
ARTIFACT_ENTITY_TYPE_CANVAS	2
ARTIFACT_ENTITY_TYPE_RUN	3
ARTIFACT_ENTITY_TYPE_ASSET	4
ARTIFACT_ENTITY_TYPE_ARTIFACT	5
ARTIFACT_ENTITY_TYPE_TOOL_USE	6

ArtifactLinkRelation

Name	Number	Description
ARTIFACT_LINK_RELATION_UNSPECIFIED	0	The link relation is not specified.
ARTIFACT_LINK_RELATION_ATTACHED_TO	1	Placement, where the artifact surfaces.
ARTIFACT_LINK_RELATION_SOURCE	2	Provenance, what the artifact was produced from; immutable.
ARTIFACT_LINK_RELATION_DERIVED_FROM	3	Artifact-to-artifact.

ArtifactStorageClass

Name	Number	Description
ARTIFACT_STORAGE_CLASS_UNSPECIFIED	0	The storage class is not specified.
ARTIFACT_STORAGE_CLASS_FILE	1	Bytes in remote_files, previewable by MIME type.
ARTIFACT_STORAGE_CLASS_STRUCTURED	2	Content is the JSON payload, no file.
ARTIFACT_STORAGE_CLASS_BLOB	3	Bytes in remote_files, opaque, download only.

Authenticate

Clients

Review

Export

Attachments

Reference

Services

ArtifactService

Messages

ArchiveArtifactRequest

ArchiveArtifactResponse

Artifact

ArtifactDetails

ArtifactLinkInput

ArtifactVersion

CreateArtifactRequest

CreateArtifactResponse

GetArtifactRequest

GetArtifactResponse

LinkArtifactToConversationRequest

LinkArtifactToConversationResponse

ListArtifactVersionsRequest

ListArtifactVersionsResponse

ListArtifactsRequest

ListArtifactsResponse

PromoteArtifactVersionRequest

PromoteArtifactVersionResponse

UnarchiveArtifactRequest

UnarchiveArtifactResponse

UnlinkArtifactFromConversationRequest

UnlinkArtifactFromConversationResponse

UpdateArtifactRequest

UpdateArtifactResponse

Enums

ArtifactCreatedVia

ArtifactEntityType

ArtifactLinkRelation

ArtifactStorageClass

​Services

​ArtifactService

​Messages

​ArchiveArtifactRequest

​ArchiveArtifactResponse

​Artifact

​ArtifactDetails

​ArtifactLinkInput

​ArtifactVersion

​CreateArtifactRequest

​CreateArtifactResponse

​GetArtifactRequest

​GetArtifactResponse

​LinkArtifactToConversationRequest

​LinkArtifactToConversationResponse

​ListArtifactVersionsRequest

​ListArtifactVersionsResponse

​ListArtifactsRequest

​ListArtifactsResponse

​PromoteArtifactVersionRequest

​PromoteArtifactVersionResponse

​UnarchiveArtifactRequest

​UnarchiveArtifactResponse

​UnlinkArtifactFromConversationRequest

​UnlinkArtifactFromConversationResponse

​UpdateArtifactRequest

​UpdateArtifactResponse

​Enums

​ArtifactCreatedVia

​ArtifactEntityType

​ArtifactLinkRelation

​ArtifactStorageClass

Services

ArtifactService

Messages

ArchiveArtifactRequest

ArchiveArtifactResponse

Artifact

ArtifactDetails

ArtifactLinkInput

ArtifactVersion

CreateArtifactRequest

CreateArtifactResponse

GetArtifactRequest

GetArtifactResponse

LinkArtifactToConversationRequest

LinkArtifactToConversationResponse

ListArtifactVersionsRequest

ListArtifactVersionsResponse

ListArtifactsRequest

ListArtifactsResponse

PromoteArtifactVersionRequest

PromoteArtifactVersionResponse

UnarchiveArtifactRequest

UnarchiveArtifactResponse

UnlinkArtifactFromConversationRequest

UnlinkArtifactFromConversationResponse

UpdateArtifactRequest

UpdateArtifactResponse

Enums

ArtifactCreatedVia

ArtifactEntityType

ArtifactLinkRelation

ArtifactStorageClass