POST
Promote a session artifact to a file

Authorizations

Authorization
string
header
required

An opaque BMA personal or organization bearer token.

Headers

Idempotency-Key
string

Idempotency key for replay-safe mutating requests.

Required string length: 1 - 255

Path Parameters

orgID
string
required

Organization ID (org_...).

Pattern: ^org_[a-z2-7]{26}$
projectID
string
required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$
agentID
string
required

Agent ID (agt_...).

Pattern: ^agt_[a-z2-7]{26}$
sessionID
string
required

Agent session ID (ses_...).

Pattern: ^ses_[a-z2-7]{26}$
artifactID
string
required

Artifact ID (art_...).

Pattern: ^art_[a-z2-7]{26}$

Body

application/json
filename
string

File name; defaults to the artifact's filename.

Required string length: 1 - 255
scope
enum<string>

project (default) or session (scoped to this session).

Available options:
project,
session
metadata
object

String labels for the file.

Response

The file an idempotent replay created.

A project file. Field names follow the Anthropic Files API (filename, mime_type, size_bytes, scope); digest and metadata are BMA extensions.

id
string
required

File ID (file_...).

Pattern: ^file_[a-z2-7]{26}$
type
enum<string>
required
Available options:
file
org_id
string
required
Pattern: ^org_[a-z2-7]{26}$
project_id
string
required

Project ID (proj_...).

Pattern: ^proj_[a-z2-7]{26}$
filename
string
required
mime_type
string
required
size_bytes
integer<int64>
required
digest
string
required

SHA-256 digest of the content, sha256:.

Pattern: ^sha256:[0-9a-f]{64}$
metadata
object
required

Caller-defined string labels.

scope
object | null
required

The session this file is scoped to; null for a project-wide file.

created_at
string<date-time>
required
source_artifact_id
string

The artifact this file was promoted from.

Pattern: ^art_[a-z2-7]{26}$