---
title: "Apply one adopted file owner policy change [write]"
method: POST
path: "/artifacts/{id}/policy"
tags: ["artifacts"]
---

# Apply one adopted file owner policy change \[write\]

`POST /artifacts/{id}/policy`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/artifacts/{id}/policy`
- Auth: HTTP bearer

Reuse exact UUID/base_policy_version/base_version and change on retry. Owner-only share/place/alias/retire. Public pin changes require from_public_version CAS. Independent alias grants/revisions and workspace incarnation are enforced. Fresh tokens and new alias ids are canonical-server generated. Omit alias.id for creation; a supplied id must already belong to this resource. Raw public_token/shared_token input fields are not supported; strict unknown fields are 400. Existing token slots are retained by default; normal enable/rotation asks the canonical server to mint fresh URLs. Output token receipts and imported historical token identities remain unchanged. One alias per source workspace slug/null; unknown supplied ids, unknown unification and move collisions are 409, while updating the same id is valid. Alias changes with unify_public not true return only that selected alias and its tokens: null placement/public_version describe a narrowed response, never a global policy reset. Global/unify_public=true requires full management and returns a complete receipt. Consumers must not overwrite a full resource mirror with a selected-alias receipt. Revocation/deletion fences later content and discussion commits.

## Path parameters

- `id` string, required

## Request body

- ArtifactPolicyInput
  - `request_id` string, uuid, required
  - `base_policy_version` integer, required
  - `base_version` integer, required
  - `change` union, required
    - object
      - `kind` 'share', required
      - `enabled` boolean, required
      - `public_version` integer, nullable
      - `from_public_version` integer, nullable
      - `revoke_all` unknown
    - object
      - `kind` 'place', required
      - `workspace` object, nullable, required
        - `slug` string, required
        - `created_at` string, date-time, required
    - object
      - `kind` 'alias', required
      - `alias` object, required
        - `id` string: Existing resource alias only; omit to create a server-generated alias. Unknown supplied ids return 409.
        - `workspace` object, nullable, required: One alias per source workspace slug, including null; a move colliding with another alias returns 409. Same-id updates remain valid.
          - `slug` string, required
          - `created_at` string, date-time, required
        - `workspace_access` 'none' | 'view' | 'edit', required
        - `members` object[], required
          - `user_id` string, required
          - `access` 'view' | 'edit', required
        - `revision` integer
      - `expected_alias_revision` integer, required
      - `public_enabled` boolean
      - `rotate_shared_token` unknown
      - `unify_public` boolean
    - object
      - `kind` 'retire', required

## Response `200`

Exact lifecycle receipt; private, no-store

- ArtifactPolicyReceipt
  - `id` string, required
  - `request_id` string, uuid, nullable, required
  - `policy_version` integer, required
  - `name` string, required
  - `version` integer, required
  - `policy` ArtifactAccessPolicy, required
    - `version` unknown, required
    - `placement` object, nullable, required
      - `slug` string, required
      - `created_at` string, date-time, required
    - `aliases` object[], required
      - `id` string, required
      - `workspace` object, nullable, required
        - `slug` string, required
        - `created_at` string, date-time, required
      - `workspace_access` 'none' | 'view' | 'edit', required
      - `members` object[], required
        - `user_id` string, required
        - `access` 'view' | 'edit', required
      - `revision` integer, required
      - `public_token_hash` string
      - `shared_token_hash` string
    - `public_token_hash` string
    - `public_version` integer, nullable, required
  - `tokens` object, required: Only exact newly issued/revoked public and alias token receipts; private to the owner
  - `archived_at` string, date-time, nullable, required

## Other responses

- `default`: Error { error: { code, message } }; changed facts are 409, unavailable recovery retains fences and capacity

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/artifacts/:id/policy/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/8280a065ef6a?raw)