---
title: "EditCollection"
method: POST
path: "/kythene.v1.KytheneService/EditCollection"
tags: ["kythene.v1.KytheneService"]
---

# EditCollection

`POST /kythene.v1.KytheneService/EditCollection`

## Request

- Base URL: `https://kythene.com` (the document declares no server; this is the origin it was published from)
- URL: `https://kythene.com/kythene.v1.KytheneService/EditCollection`
- Auth: none required

EditCollection edits a collection's membership with one call - the aggregate
 of add / reorder / move behind an action - returning a lean ack (revisions
 and any newly-exposed share-code holders) rather than whole collections.

## Headers

- `Connect-Protocol-Version` 1, required: Define the version of the Connect protocol
- `Connect-Timeout-Ms` number: Define the timeout, in ms

## Request body

- KytheneV1EditCollectionRequest
  - `collectionId` string: collection_id is the collection to edit (for a move, the SOURCE collection).
  - `action` string: action is one of: "add" (add files), "reorder" (set the full member order), "move" (move a file to another collection), "rename" (change the title), "tags" (replace the collection's tags).
  - `artifacts` KytheneV1NewArtifact[]: add: new files to create and append.
    - `name` string: name is the artifact's filename-like name, e.g. "bench-results.json".
    - `mime` string: mime is the content type; defaults to application/octet-stream.
    - `content` string, byte: content carries the artifact bytes (32 MiB max per artifact over the API and the CLI). An MCP request is capped far lower - the tool description carries that endpoint's real ceiling.
    - `note` string: note is an optional version note.
  - `existingArtifactIds` string[]: add: references to already-published artifacts of the same space to append.
  - `note` string: add: optional version note.
  - `artifactIds` string[]: reorder: the FULL current member set, every artifact once, in the order you want (a partial or unknown-id list is rejected; work from a fresh get_collection).
  - `artifactId` string: move: the artifact to move, and the destination collection (same space); collection_id is the source.
  - `toCollectionId` string: to_collection_id is the collection to move the artifact INTO; collection_id is the one it leaves. Both must be in the same space.
  - `title` string: rename: the new title. The collection keeps its id, links, comments, reviews and history; the revision does not change.
  - `space` string: space optionally selects which of your spaces to act in (an id or name from list_spaces). Omit it when you belong to a single space.
  - `tags` string[]: tags: the full set of tags the collection should carry (labels and projects); names not yet in the workspace become new labels.
  - `dryRun` boolean: tags: true to report the effect without changing anything.

## Response `200`

Success

- KytheneV1EditCollectionResponse
  - `ok` boolean: ok is true when the edit applied.
  - `revision` integer: revision is the collection's revision after add/reorder, or (unchanged) after a rename.
  - `fromRevision` integer: from_revision / to_revision are the source and destination revisions after a move.
  - `toRevision` integer
  - `shareCodeHolders` string[]: share_code_holders lists share-code labels whose holders can now read a newly-added or newly-moved file anonymously (the exposure the edit created).
  - `url` string: url is the collection's canonical link - after a move, the file within its destination - hand THAT to a person, never the bare id.
  - `tagsAdded` string[]: tags: what the change does (or would, on a dry run). Tell the person who gains or loses access BEFORE you make a change that does either.
  - `tagsRemoved` string[]
  - `membersGain` string[]: members_gain / members_lose: workspace members who can now / can no longer see the collection (a private project decides this), by name.
  - `membersLose` string[]
  - `guestsGain` string[]: guests_gain / guests_lose: share links (by label) and tag passwords whose holders can now / can no longer read it without an account.
  - `guestsLose` string[]

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/kythene/apis/kythene-v1.md) · [All operations](https://skmtc.dev/kythene/apis/kythene-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/kythene/apis/kythene-v1/revisions/5a768e642d10?raw)