---
title: "Allocate, inspect, or hand off a tenant-owned artifact"
method: POST
path: "/v1/artifact-operations"
tags: ["runs", "artifacts"]
---

# Allocate, inspect, or hand off a tenant-owned artifact

`POST /v1/artifact-operations`

## Request

- Base URL: `https://api.runx.ai`
- URL: `https://api.runx.ai/v1/artifact-operations`
- Auth: HTTP bearer

Stores one bounded artifact, returns verified metadata, or copies an explicitly approved artifact into a registered target principal. Other artifact operations remain available only inside the trusted hosted runtime.

## Request body

- union
  - ArtifactAllocationRequest
    - `operation` 'artifact.allocate', required
    - `run_id` string, required
    - `input` object, required
      - `idempotency_key` string, required
      - `data_base64` string, required
      - `content_digest` string, required
      - `media_type` string, required
  - ArtifactInspectionRequest
    - `operation` 'artifact.inspect', required
    - `run_id` string, required
    - `input` object, required
      - `artifact_ref` string, required
  - ArtifactHandoffRequest
    - `operation` 'artifact.handoff', required
    - `run_id` string, required
    - `input` object, required
      - `source_artifact_ref` string, required
      - `target_principal_id` string, required
      - `idempotency_key` string, required
  - ArtifactDownloadRequest
    - `operation` 'artifact.download', required
    - `run_id` string, required
    - `input` object, required
      - `artifact_ref` string, required
      - `maximum_bytes` integer
  - ArtifactAccessRequest
    - `operation` 'artifact.access', required
    - `run_id` string, required
    - `input` object, required
      - `artifact_ref` string, required
      - `expires_in_seconds` integer

## Response `200`

Verified artifact operation evidence.

- union
  - object
    - `schema` 'runx.provider.operation.v1', required
    - `status` 'success', required
    - `provider` 'runx-artifact', required
    - `operation` 'artifact.allocate', required
    - `target` string, required
    - `result` union, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
      - object
        - `source_artifact_ref` string, required
        - `target_principal_ref` string, required
        - `artifact` HostedArtifactEvidence, required
          - `artifact_ref` string, required
          - `content_digest` string, required
          - `media_type` string, required
          - `size_bytes` integer, required
          - `created_at` string, date-time, required
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
        - `data_base64` string, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
        - `url` string, uri, required
        - `expires_at` string, date-time, required
    - `transport` 'hosted_control_plane', required
    - `readback_ref` string, required
    - `access` 'mutate', required
    - `principal_ref` string, required
    - `finality` 'verified', required
    - `result_digest` string, required
    - `operation_id` string, required
    - `idempotency_key` string, required
  - object
    - `schema` 'runx.provider.operation.v1', required
    - `status` 'success', required
    - `provider` 'runx-artifact', required
    - `operation` 'artifact.handoff', required
    - `target` string, required
    - `result` union, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
        - `source_artifact_ref` string, required
        - `target_principal_ref` string, required
        - `artifact` HostedArtifactEvidence, required
          - `artifact_ref` string, required
          - `content_digest` string, required
          - `media_type` string, required
          - `size_bytes` integer, required
          - `created_at` string, date-time, required
      - object
        - `source_artifact_ref` string, required
        - `target_principal_ref` string, required
        - `artifact` HostedArtifactEvidence, required
          - `artifact_ref` string, required
          - `content_digest` string, required
          - `media_type` string, required
          - `size_bytes` integer, required
          - `created_at` string, date-time, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
        - `data_base64` string, required
        - `source_artifact_ref` string, required
        - `target_principal_ref` string, required
        - `artifact` HostedArtifactEvidence, required
          - `artifact_ref` string, required
          - `content_digest` string, required
          - `media_type` string, required
          - `size_bytes` integer, required
          - `created_at` string, date-time, required
      - object
        - `artifact_ref` string, required
        - `content_digest` string, required
        - `media_type` string, required
        - `size_bytes` integer, required
        - `created_at` string, date-time, required
        - `url` string, uri, required
        - `expires_at` string, date-time, required
        - `source_artifact_ref` string, required
        - `target_principal_ref` string, required
        - `artifact` HostedArtifactEvidence, required
          - `artifact_ref` string, required
          - `content_digest` string, required
          - `media_type` string, required
          - `size_bytes` integer, required
          - `created_at` string, date-time, required
    - `transport` 'hosted_control_plane', required
    - `readback_ref` string, required
    - `access` 'mutate', required
    - `principal_ref` string, required
    - `finality` 'verified', required
    - `result_digest` string, required
    - `operation_id` string, required
    - `idempotency_key` string, required

## Other responses

- `400`: Validation error.
- `401`: Unauthorized.
- `403`: Missing artifact operation scope.
- `404`: Artifact not found.
- `409`: Artifact operation conflict.
- `413`: Artifact request is too large.
- `429`: Artifact operation rate limit exceeded.
- `502`: Artifact storage returned an invalid result.
- `503`: Artifact operation is unavailable.

---

[API](https://skmtc.dev/runx/apis/runx-hosted-api.md) · [All operations](https://skmtc.dev/runx/apis/runx-hosted-api/llms.txt) · [OpenAPI document](https://skmtc.dev/runx/apis/runx-hosted-api/revisions/6c940d8edacc?raw)