packages

Create or replace a saved package by writing a complete UTF-8 text file set (no binary assets).

Create or replace a saved package by writing a complete UTF-8 text file set (no binary assets). Coding agents with local filesystem/git access should prefer packageGetGitRemote (pass create: true for new packages) to clone, edit, push, and publish with packagePublishExternalPush; tool-only agents use packageSave or repo sessions. The package repo is rooted at package.json and package.json#kody is the Kody-specific metadata block. Publish requires non-empty root README.md (human-focused: what it does, prerequisites, setup, done-when, plus a concise Intent section) and AGENTS.md (agent-focused: imports, smoke tests, edge cases). Ask the user if intent is unclear. Visibility is a repo setting (packageUpdate / repoUpdate), not package.json "private". Leftover "private" in manifests is ignored for catalog listing. New packages are created private; set changes.visibility: "public" after the user asks to list them on /community. Production package source safety policy: never replace source history, force publish, or packageSave over an existing package unless Kody has created a restorable backup snapshot and the user explicitly approved destructive overwrite. If existing source cannot be cloned or verified, stop and report the source recovery problem.

Org permission: package:write.

post/v1/packages

Request

  • Base URL: https://api.kody.codes
  • URL: https://api.kody.codes/v1/packages
  • Auth: HTTP bearer

Request body

package_idstring

Optional saved package id to update in place. Omit to create a new saved package.

confirm_destructive_overwriteboolean

Set to true only when the user explicitly approved destructive overwrite of existing package source history. Promoting publishes replace advertised history with a new root commit (and drop leftover session refs); promotePublished:false stays additive. Restorable backups retain prior content — secret scrub of backups still needs packageDelete or an explicit purge.

confirm_private_visibility_changeboolean

Set to true only when the user explicitly approved changing package.json "private". This flag does not change repo visibility: catalog listing is packageUpdate changes.visibility. Leftover "private" in manifests is ignored for the catalog.

Response

Success.

package_idstring required
kody_idstring required

Package name leaf (same value as slug). Kept as a compatibility alias; prefer slug or name.

slugstring required

Package name leaf (the path segment after the scope). Same value as kody_id.

namestring required
descriptionstring required
tagsstring[] required
has_appboolean required
hiddenboolean required
visibility'public' | 'private' required

Repo visibility / forkable. Public means default-branch HEAD is world-readable and forkable and the package appears on /community. Private is owner-only. Independent of internet_visible.

internet_visibleboolean required

When true, the hosted package app may be served on the public internet after capability approval. Independent of visibility/forkable. Defaults false.

locked_atstring nullable required

When set, publishes require a website click at /@{username}/{kodyId}/approve-publish?commit=<full 40-character SHA>. Agents may lock via packageUpdate (changes.locked: true). Unlocking is website-only at /@{username}/{kodyId}/settings. Do not abbreviate the commit.

source_idstring required
created_atstring required
updated_atstring required
next_stepsstring required

Follow-up guidance for continuing package work, including the git clone-edit-push lane for coding agents and any pending package secret approvals.

Changes

No recorded changes to this operation across all 2 revisions of this API.