Skip to content

Update api spec #1936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jessfraz merged 1 commit into from
Oct 29, 2026
Merged

Update api spec #1936

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 55 additions & 9 deletions spec.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26148,6 +26148,7 @@
"projects"
],
"summary": "List personal libraries and libraries belonging to the active organization.",
"description": "Returns an object with `items` and `next_page`, ordered by library ID. Request the next page with `?page_token=<next_page>` until `next_page` is null. Keep the same authenticated user and active organization for every page; changing that context requires starting a new list request.\n\nEach library has a stable `id`, a display `name`, either `user_id` or `org_id`, an opaque `revision`, and `can_manage`. Use the ID to track a library across renames. `can_manage` allows renaming/deleting the library, not editing all of its projects. Organization members can discover libraries; only organization admins can manage them. Project permissions remain unchanged.\n\nProjects with `library_id: null` have no named library. They do not appear as a library record here. Use `GET /user/projects?scope=personal&unassigned=true` for the default personal group, or `scope=organization&unassigned=true` for the active organization's unassigned projects.\n\nEach library includes its creation source: `zds` or `factory_portal`. Libraries created before source tracking are returned as `zds`. Clients can filter the results by source; API permissions remain unchanged.",
"operationId": "list_project_libraries",
"parameters": [
{
Expand Down Expand Up @@ -26265,6 +26266,7 @@
"projects"
],
"summary": "Create a personal library or a library owned by the active organization.",
"description": "Send JSON with a name and explicit ownership scope:\n\n```json { \"name\": \"Designs\", \"scope\": \"personal\" } ```\n\nUse `scope: \"organization\"` to create a library for the request's active organization; this requires organization-admin access. There is no organization ID in this body. Personal scope always uses the authenticated user.\n\nNames are trimmed, must contain 1–255 characters, and are unique ignoring case within each user or organization. Display capitalization is preserved. Duplicate names return HTTP 409. The HTTP 201 response contains the library ID, ownership, revision, and `can_manage`. Creating a library does not move existing projects; select its ID when creating a project, or move an existing project with `PUT /user/projects/{id}/library`.\n\nInclude `source` to identify the application that created the library:\n\n```json { \"name\": \"Factory designs\", \"scope\": \"personal\", \"source\": \"factory_portal\" } ```\n\nAccepted sources are `zds` and `factory_portal`. Omitting source defaults to `zds`. Null and unsupported values return HTTP 400.\n\nSource is returned in library responses and cannot be changed after creation. Clients use it to decide how to display libraries; it does not change API permissions. No API source filter is provided at the moment.",
"operationId": "create_project_library",
"requestBody": {
"content": {
Expand Down Expand Up @@ -26455,6 +26457,7 @@
"projects"
],
"summary": "Delete an empty cloud project library.",
"description": "Supply the library's last-read `revision` as the required `expected_revision` query parameter. URL-encode this value. Only the personal owner or an admin of the active organization can delete the library.\n\nMove or unassign all projects first. A nonempty library or stale revision returns HTTP 409. Success returns HTTP 204 without deleting projects or history. Library revisions are separate from project `revision` and `metadata_revision`.",
"operationId": "delete_project_library",
"parameters": [
{
Expand Down Expand Up @@ -26657,6 +26660,7 @@
"projects"
],
"summary": "Rename a library owned by the user or their active organization.",
"description": "Send JSON containing `name` and `expected_revision`, using the library's `revision` from the last library list response. The personal owner or an admin of the active organization can rename the library. Names follow the same validation and uniqueness rules as library creation.\n\nHTTP 200 returns the updated library and revision. A stale revision or duplicate name returns HTTP 409; refresh the library list before deciding whether to retry. Renaming keeps the library ID, ownership, and project assignments unchanged.\n\nRenaming doesn't change the library's source.",
"operationId": "rename_project_library",
"parameters": [
{
Expand Down Expand Up @@ -26772,6 +26776,7 @@
"projects"
],
"summary": "List projects in a cloud library, newest first.",
"description": "Returns project summaries in `items`, with `next_page` for continuation. Pass `?page_token=<next_page>` on the same library endpoint until `next_page` is null. Keep the same authenticated user and active organization for every page. Results are ordered by creation time descending, then project ID ascending.\n\nEach summary includes `library_id`, content `revision`, `metadata_revision`, and the caller's project `access` capabilities. Access to a library does not grant additional project permissions.\n\nProjects can move or disappear while pages load. Even an empty page can have a continuation token; stop only when `next_page` is null.\n\nWhen loading several libraries, a project may appear in library A's results, then move to library B before B is loaded. Combining those results can show the same project twice. Use the project ID to show it once, and fetch its latest details to confirm which library it belongs to. A missing list entry may also mean the project moved; fetch its details before treating it as deleted, and preserve unsynced local edits.",
"operationId": "list_library_projects",
"parameters": [
{
Expand Down Expand Up @@ -26997,6 +27002,7 @@
"projects"
],
"summary": "List the authenticated user's projects.",
"description": "Returns an array, including personal projects and projects accessible through the request's active organization. Optional `scope=personal` or `scope=organization` narrows ownership; `unassigned=true` includes only projects whose `library_id` is null. Combine them, for example: `GET /user/projects?scope=personal&unassigned=true`. Omitting both filters keeps returning all accessible projects, including projects in named libraries.\n\nUnassigned is a grouping within the existing ownership scope, not a stored default library. Use `GET /user/project-libraries/{id}/projects` for a named library's paginated project list. Filters do not grant additional access.",
"operationId": "list_projects",
"parameters": [
{
Expand Down Expand Up @@ -27110,7 +27116,8 @@
"tags": [
"projects"
],
"summary": "Create a draft project for the authenticated user.",
"summary": "Create a project for the authenticated user.",
"description": "Send multipart data with a JSON `body` part and file parts whose filenames are relative project paths. Include an optional `library_id` in the JSON to create the project in a named library:\n\n```json { \"title\": \"Bracket\", \"entrypoint_path\": \"main.kcl\", \"library_id\": \"<LIBRARY_ID>\" } ```\n\nA personal library creates a personal project. An accessible library belonging to the active organization creates an organization project with the caller as its creator; creating the project does not require library-management rights. Omitting `library_id` or passing null creates an unassigned personal project, even when the request has an active organization.\n\nThe HTTP 201 response includes `id`, `library_id`, content `revision`, and `metadata_revision`. Later saves preserve membership, even if they include a library field. Use `PUT /user/projects/{id}/library` to move or unassign an existing project instead of uploading its files again.",
"operationId": "create_project",
"requestBody": {
"content": {
Expand Down Expand Up @@ -27405,6 +27412,7 @@
"projects"
],
"summary": "Replace one of the authenticated user's projects.",
"description": "Content saves use the project's content `revision` as `expected_revision` and preserve its current library assignment. Omitting `library_id`, setting it to null, or supplying another library ID here does not move the project. Use `PUT /user/projects/{id}/library` with `metadata_revision` for library changes.",
"operationId": "update_project",
"parameters": [
{
Expand Down Expand Up @@ -27753,6 +27761,7 @@
"projects"
],
"summary": "Move a project to a named library or leave it unassigned.",
"description": "Read the project first, then send JSON using its `metadata_revision` as the required `expected_revision`. Do not use its content `revision` or a library's revision for this operation.\n\n```json { \"library_id\": \"<DESTINATION_LIBRARY_ID>\", \"expected_revision\": \"<METADATA_REVISION>\" } ```\n\nSave the JSON as `move-project.json`, with values from actual responses:\n\n```sh curl --fail-with-body \\ --request PUT \"${API_BASE_URL}/user/projects/${PROJECT_ID}/library\" \\ --header \"Authorization: Bearer ${API_TOKEN}\" \\ --header 'Content-Type: application/json' \\ --data-binary @move-project.json ```\n\nUse `library_id: null` to unassign the project. The destination must match the project's current ownership: the same user for a personal project, or the same organization for an organization project. Existing project write permission is required; managing the destination library does not grant it. To change ownership first, use `/user/projects/{id}/organization`.\n\nHTTP 200 returns the project with its library assignment and a new `metadata_revision`. A move preserves its ID, files, current content `revision`, version history, publication, and share links; it creates no content version. Ordinary saves preserve membership and cannot be used to move a project.\n\nA stale revision or a destination with different ownership returns HTTP 409. If another save, move, or ownership change conflicts with the move, fetch the latest project before deciding whether to retry. Missing or inaccessible projects/libraries fail their normal existence and permission checks.\n\nIf the connection drops or the request times out, the API may have completed the move even though the client did not receive a response. Fetch the project to check its current library. If library_id matches the requested destination, no further move is needed. Otherwise review its latest state before retrying with its new `metadata_revision`. No idempotency key is used for this operation.",
"operationId": "update_project_library",
"parameters": [
{
Expand Down Expand Up @@ -27964,8 +27973,8 @@
"tags": [
"projects"
],
"summary": "Move one of the authenticated user's projects into their active organization library.",
"description": "This changes only the project's ownership scope. The project ID, current revision, files, and version history remain unchanged so cloud bindings stay valid across the move.",
"summary": "Transfer one of the authenticated user's projects to their active organization.",
"description": "This changes only the project's ownership scope. The project ID, current revision, files, and version history remain unchanged so cloud bindings stay valid across the move.\n\nAn actual ownership change clears `library_id` and changes `metadata_revision`. The project becomes unassigned in the organization. To place it in a named organization library, use `PUT /user/projects/{id}/library` afterwards with the returned metadata revision. An already organization-owned project in the same organization is unchanged by this request.",
"operationId": "update_project_organization",
"parameters": [
{
Expand Down Expand Up @@ -28068,8 +28077,8 @@
"tags": [
"projects"
],
"summary": "Move an organization project back to its creator's personal library.",
"description": "Organization administrators may perform this move to revoke organization access. The project ID, current revision, files, and version history remain unchanged.",
"summary": "Transfer an organization project back to its creator's personal ownership.",
"description": "Organization administrators may perform this move to revoke organization access. The project ID, current revision, files, and version history remain unchanged.\n\nThe ownership change clears `library_id` and changes `metadata_revision`, leaving the project unassigned under its creator. Success returns HTTP 204. Fetch the project again before assigning it to a personal named library.",
"operationId": "delete_project_organization",
"parameters": [
{
Expand Down Expand Up @@ -37430,6 +37439,15 @@
"$ref": "#/components/schemas/ProjectLibraryScope"
}
]
},
"source": {
"description": "Application creating the library. Defaults to zds when omitted.",
"default": "zds",
"allOf": [
{
"$ref": "#/components/schemas/KclProjectLibrarySource"
}
]
}
},
"required": [
Expand Down Expand Up @@ -43455,6 +43473,25 @@
}
]
},
"KclProjectLibrarySource": {
"description": "Application that created a cloud project library.",
"oneOf": [
{
"description": "Created through Zoo Design Studio. Also the default.",
"type": "string",
"enum": [
"zds"
]
},
{
"description": "Created through Factory Portal.",
"type": "string",
"enum": [
"factory_portal"
]
}
]
},
"KclProjectPreviewStatus": {
"description": "Preview generation status for a KCL project.",
"oneOf": [
Expand Down Expand Up @@ -58395,6 +58432,14 @@
"description": "Opaque revision token required when renaming or deleting the library.",
"type": "string"
},
"source": {
"description": "Application that created the library. Cannot be changed after creation.",
"allOf": [
{
"$ref": "#/components/schemas/KclProjectLibrarySource"
}
]
},
"updated_at": {
"title": "DateTime",
"description": "When the library was last updated.",
Expand All @@ -58417,6 +58462,7 @@
"id",
"name",
"revision",
"source",
"updated_at"
]
},
Expand Down Expand Up @@ -58575,7 +58621,7 @@
]
},
"metadata_revision": {
"description": "Opaque token used to detect conflicting library moves.",
"description": "Opaque token for library moves. Send as expected_revision to the library endpoint. Read a fresh value after a save, move, or ownership change; do not parse it.",
"type": "string"
},
"preview_status": {
Expand Down Expand Up @@ -58612,7 +58658,7 @@
]
},
"revision": {
"description": "Opaque revision token for optimistic project mutations.",
"description": "Current content version's revision. Use as expected_revision for content saves. Library moves do not change this value.",
"type": "string"
},
"title": {
Expand Down Expand Up @@ -58829,7 +58875,7 @@
]
},
"metadata_revision": {
"description": "Opaque token used to detect conflicting library moves.",
"description": "Opaque token for library moves. Send as expected_revision to the library endpoint. Read a fresh value after a save, move, or ownership change; do not parse it.",
"type": "string"
},
"preview_status": {
Expand Down Expand Up @@ -58866,7 +58912,7 @@
]
},
"revision": {
"description": "Opaque revision token for optimistic project mutations.",
"description": "Current content version's revision. Use as expected_revision for content saves. Library moves do not change this value.",
"type": "string"
},
"title": {
Expand Down
Loading