Adopt Content
curl --request POST \
--url https://api.example.com/v0/workspaces/{id}/adoptimport requests
url = "https://api.example.com/v0/workspaces/{id}/adopt"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/workspaces/{id}/adopt', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/workspaces/{id}/adopt",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/workspaces/{id}/adopt"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/workspaces/{id}/adopt")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/adopt")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyWorkspaces
Adopt Content
POST /v0/workspaces/:id/adopt — Move standalone artifacts or a folder you own into the workspace
POST
/
v0
/
workspaces
/
{id}
/
adopt
Adopt Content
curl --request POST \
--url https://api.example.com/v0/workspaces/{id}/adoptimport requests
url = "https://api.example.com/v0/workspaces/{id}/adopt"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v0/workspaces/{id}/adopt', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/workspaces/{id}/adopt",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/workspaces/{id}/adopt"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/workspaces/{id}/adopt")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/workspaces/{id}/adopt")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_bodyMoves eligible standalone content you own into the workspace in one transaction. Nothing is copied: identity and version history are kept, and the content’s team shares are removed. Requires
writeContent. Everyone in the workspace then sees the adopted content. MCP: workspace_adopt. CLI: rip workspace adopt <workspace> <artifact>... | --folder <folder> [--destination-folder-id].
Auth: Authorization: Bearer tr_... (an account API key). {id} is the workspace id or slug (any case; a slug two of your workspaces share is 409 AMBIGUOUS_REFERENCE listing each candidate’s id).
Request body
Send exactly one ofartifactIds or folder:
| Field | Type | Required | Description |
|---|---|---|---|
artifactIds | string[] | One of the two | Each an artifact id, an alias (alias, ~agent/alias, _team/alias) or a page URL; at most 500, no duplicates |
destinationFolderId | string | null | With artifactIds only, optional | A folder of this workspace (its id). Without it, adopted artifacts land at the workspace root |
folder | string | One of the two | A personal folder you own: its id or slug. Its current artifacts come with it and stay inside it |
why | string | Yes (agents) | One sentence on what the person is trying to accomplish, in their terms (not a description of the edit); required on an agent write to workspace content, at most 300 characters. See Why on every write |
Response (201)
{ "ok": true, "data": { "artifactIds": ["5c9e…", "a13f…"], "folderId": null } }
artifactIds are the ids of the moved artifacts. folderId is the adopted folder’s id when you sent folder, otherwise null.
Everyone in the workspace can read every version an adopted artifact keeps, and so can anyone with its link once it has public access. Adoption is one-way: there is no route that moves workspace content back to standalone ownership.
Errors
Every check runs before any change is made.| Status | Code | Cause |
|---|---|---|
403 | STORAGE_LIMIT_REACHED | The workspace’s payer is not your own account (a team, or another account’s workspace) and the adopted files would take it past its plan’s storage limit. The body carries usedBytes, limitBytes, addedBytes and plan; nothing is stored. See Storage Usage |
403 | ACTIONS_LIMIT_REACHED | While the actions mode is enforce: an agent’s write to a workspace whose owner has used this month’s actions. Nothing is changed. See Actions Usage |
400 | WHY_REQUIRED | An agent write to workspace content without why |
400 | INVALID_FIELD | Neither or both of artifactIds and folder, destinationFolderId with folder, audience (refused with “Sharing is by workspace now: everyone in a workspace sees all of it. Keep private work in a separate workspace.”), or a field the operation does not take (the retired kind, artifactId and folderId included) |
400 | DUPLICATE_ARTIFACT | The same artifact appears twice |
400 | WORKSPACE_BULK_LIMIT | More than 500 artifacts |
404 | ARTIFACT_NOT_FOUND / FOLDER_NOT_FOUND | An artifact or the folder does not exist |
403 | WORKSPACE_FORBIDDEN | No writeContent, or the folder is not your personal folder |
409 | MIXED_OWNERSHIP | An artifact is not owned by you |
409 | ALREADY_IN_WORKSPACE | The artifact or folder already belongs to a workspace |
409 | INELIGIBLE_STORAGE | A public asset, independently hosted content, an unproven storage class, or public version history |
409 | CROSS_WORKSPACE_MOVE | destinationFolderId is not a folder of this workspace |
409 | ARTIFACT_FOLDER_CHANGED / FOLDER_CHANGED | Content moved while the request ran; retry |
410 | WORKSPACE_DELETED | The workspace is in the trash |
404 | WORKSPACE_NOT_FOUND | No workspace you reach has that id or slug |