Move a package to another home space

Change the package's home space — the space whose <type>:write authorizes editing, publishing, renaming and deleting it. The caller must hold that permission in BOTH the current home and the destination space, which must be one the caller can reach; an unreachable destination answers 404 rather than confirming it exists. The destination can never be a PERSONAL space (409 home_move_into_personal_space): a personal space homes only what is created or forked in it, and every member but a guest holds admin (hence <type>:write) in their own, so the move would otherwise put a team's package beyond every administrator's reach (RBAC spec §3.6 gives no admin a way in) for as long as its owner stays a member. POST /api/packages/{scope}/{name}/fork is the private copy. home_space_id is required and cannot be null: every package of the organization is homed in one of its spaces, and one that belongs to no team is homed in the organization's default space. It also reconciles PLACEMENT in the same transaction: every space that holds the package and is not the new home gains the package_shares row that now places it there (a package is present in a space through its home or a share, never through its space_packages row alone), the destination's own share, if any, is dropped since a package is not offered to the space it lives in, and the destination is ACTIVATED through the activation door itself — a package lives where it is written, exactly as creating one activates it at home — which writes the same package.activated audit entry a click on the switch would, and refuses the whole move with 422 bundle_invalid for an mcp-server whose latest archive is not executable. A destination that had deliberately switched the package OFF keeps that decision: the move transfers authority over a package, not a verdict about what a space runs. Those reconciling shares carry shared_by: null — nobody offered them, the home did until this call — so GET /api/packages/{scope}/{name}/shares lists them with a null sharer, and revoking one removes the package from that space like any other revocation. The draft itself is edited through PATCH /api/packages/{type}/{scope}/{name}, under its If-Match.

PUT/api/packages/{scope}/{name}/home

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Path Parameters

scope*string

Package scope (e.g. @myorg)

Match^@[a-z0-9][a-z0-9-]*$

name*string

Package name

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

X-Space-Id?string

Space ID. Required for space-scoped routes (agents, runs, schedules, and space-scoped module routes). Not needed for API key auth (space resolved from key).

Request Body

application/json

home_space_id*string

Destination space id (spc_…). Required and non-nullable — a package always has a home space.

keep_in_previous_home?boolean

Does the space being LEFT keep the package? true (the default) leaves it the authorless package_shares offer described above, so it goes on reading and running it and nothing it had scheduled stops. false completes the move: that offer and that space's space_packages row are removed together, in the same transaction — together, because withdrawing the offer alone would leave a placement row nothing places, which no page shows and no execution door honours. It asks no authority beyond the move's own <type>:write in both homes; requiring <type>:share as well would mean a caller holding write and not share could never move a package cleanly, only leave a copy behind, and withdrawing an access is the safe direction. It governs a space that was RUNNING the package: a space that held no space_packages row is left behind whatever the flag says, because the backfill exists to preserve what was running and an offer written to a space that never switched the package on would widen what it sees. The audit entry package.home_space_changed records it as keptInPreviousHome.

Defaulttrue

curl -X PUT "https://your-instance/api/packages/string/string/home" \  -H "Content-Type: application/json" \  -d '{    "home_space_id": "string"  }'

{
  "id": "string",
  "display_name": "string",
  "description": "string",
  "source": "local",
  "scope": "string",
  "version": "string",
  "definition": "draft",
  "manifest": {
    "name": "string",
    "version": "string",
    "type": "agent",
    "display_name": "string",
    "description": "string",
    "long_description": "string",
    "keywords": [
      "string"
    ],
    "license": "string",
    "author": "string",
    "repository": "string",
    "homepage": "string",
    "documentation": "string",
    "support": "string",
    "icon": "string",
    "icons": [
      {
        "src": "string",
        "size": "string",
        "theme": "light",
        "property1": null,
        "property2": null
      }
    ],
    "screenshots": [
      "string"
    ],
    "privacy_policies": [
      "string"
    ],
    "compatibility": {
      "platforms": [
        "darwin"
      ],
      "runtimes": {
        "property1": "string",
        "property2": "string"
      },
      "clients": {
        "property1": "string",
        "property2": "string"
      },
      "property1": null,
      "property2": null
    },
    "schema_version": "string",
    "dependencies": {
      "skills": {
        "property1": "string",
        "property2": "string"
      },
      "mcp_servers": {
        "property1": "string",
        "property2": "string"
      },
      "integrations": {
        "property1": "string",
        "property2": "string"
      },
      "property1": null,
      "property2": null
    },
    "_meta": {
      "property1": {
        "property1": null,
        "property2": null
      },
      "property2": {
        "property1": null,
        "property2": null
      }
    },
    "integrations_configuration": {
      "property1": {
        "tools": [
          "string"
        ],
        "scopes": [
          "string"
        ],
        "auth_key": "string",
        "property1": null,
        "property2": null
      },
      "property2": {
        "tools": [
          "string"
        ],
        "scopes": [
          "string"
        ],
        "auth_key": "string",
        "property1": null,
        "property2": null
      }
    },
    "input": {
      "schema": {
        "definitions": {},
        "dependencies": {},
        "$recursiveAnchor": "string",
        "$recursiveRef": "../dictionary",
        "$id": "../dictionary",
        "$schema": "http://example.com",
        "$ref": "../dictionary",
        "$anchor": "string",
        "$dynamicRef": "../dictionary",
        "$dynamicAnchor": "string",
        "$vocabulary": {
          "property1": true,
          "property2": true
        },
        "$comment": "string",
        "$defs": {
          "property1": null,
          "property2": null
        },
        "prefixItems": [
          null
        ],
        "items": null,
        "contains": null,
        "additionalProperties": null,
        "properties": {},
        "patternProperties": {},
        "dependentSchemas": {},
        "propertyNames": null,
        "if": null,
        "then": null,
        "else": null,
        "allOf": [
          null
        ],
        "anyOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "not": null,
        "unevaluatedItems": null,
        "unevaluatedProperties": null,
        "const": true,
        "enum": [
          true
        ],
        "multipleOf": 1,
        "maximum": 0,
        "exclusiveMaximum": 0,
        "minimum": 0,
        "exclusiveMinimum": 0,
        "maxLength": 0,
        "minLength": 0,
        "pattern": "/regex/",
        "maxItems": 0,
        "minItems": 0,
        "uniqueItems": false,
        "maxContains": 0,
        "minContains": 1,
        "maxProperties": 0,
        "minProperties": 0,
        "required": [],
        "dependentRequired": {
          "property1": [],
          "property2": []
        },
        "title": "string",
        "description": "string",
        "default": true,
        "deprecated": false,
        "readOnly": false,
        "writeOnly": false,
        "examples": [
          true
        ],
        "format": "string",
        "contentEncoding": "string",
        "contentMediaType": "string",
        "contentSchema": null,
        "type": "object"
      },
      "file_constraints": {
        "property1": {
          "accept": "string",
          "max_size": 1,
          "property1": null,
          "property2": null
        },
        "property2": {
          "accept": "string",
          "max_size": 1,
          "property1": null,
          "property2": null
        }
      },
      "ui_hints": {
        "property1": {
          "placeholder": "string",
          "property1": null,
          "property2": null
        },
        "property2": {
          "placeholder": "string",
          "property1": null,
          "property2": null
        }
      },
      "property_order": [
        "string"
      ],
      "_meta": {
        "property1": {
          "property1": null,
          "property2": null
        },
        "property2": {
          "property1": null,
          "property2": null
        }
      }
    },
    "output": {
      "schema": {
        "definitions": {},
        "dependencies": {},
        "$recursiveAnchor": "string",
        "$recursiveRef": "../dictionary",
        "$id": "../dictionary",
        "$schema": "http://example.com",
        "$ref": "../dictionary",
        "$anchor": "string",
        "$dynamicRef": "../dictionary",
        "$dynamicAnchor": "string",
        "$vocabulary": {
          "property1": true,
          "property2": true
        },
        "$comment": "string",
        "$defs": {
          "property1": null,
          "property2": null
        },
        "prefixItems": [
          null
        ],
        "items": null,
        "contains": null,
        "additionalProperties": null,
        "properties": {},
        "patternProperties": {},
        "dependentSchemas": {},
        "propertyNames": null,
        "if": null,
        "then": null,
        "else": null,
        "allOf": [
          null
        ],
        "anyOf": [
          null
        ],
        "oneOf": [
          null
        ],
        "not": null,
        "unevaluatedItems": null,
        "unevaluatedProperties": null,
        "const": true,
        "enum": [
          true
        ],
        "multipleOf": 1,
        "maximum": 0,
        "exclusiveMaximum": 0,
        "minimum": 0,
        "exclusiveMinimum": 0,
        "maxLength": 0,
        "minLength": 0,
        "pattern": "/regex/",
        "maxItems": 0,
        "minItems": 0,
        "uniqueItems": false,
        "maxContains": 0,
        "minContains": 1,
        "maxProperties": 0,
        "minProperties": 0,
        "required": [],
        "dependentRequired": {
          "property1": [],
          "property2": []
        },
        "title": "string",
        "description": "string",
        "default": true,
        "deprecated": false,
        "readOnly": false,
        "writeOnly": false,
        "examples": [
          true
        ],
        "format": "string",
        "contentEncoding": "string",
        "contentMediaType": "string",
        "contentSchema": null,
        "type": "object"
      },
      "file_constraints": {
        "property1": {
          "accept": "string",
          "max_size": 1,
          "property1": null,
          "property2": null
        },
        "property2": {
          "accept": "string",
          "max_size": 1,
          "property1": null,
          "property2": null
        }
      },
      "ui_hints": {
        "property1": {
          "placeholder": "string",
          "property1": null,
          "property2": null
        },
        "property2": {
          "placeholder": "string",
          "property1": null,
          "property2": null
        }
      },
      "property_order": [
        "string"
      ],
      "_meta": {
        "property1": {
          "property1": null,
          "property2": null
        },
        "property2": {
          "property1": null,
          "property2": null
        }
      }
    },
    "timeout": 1,
    "property1": null,
    "property2": null,
    "runtime_tools": [
      "output"
    ]
  },
  "prompt": "string",
  "updatedAt": "2019-08-24T14:15:22Z",
  "input": {
    "values": {},
    "locked_fields": [
      "string"
    ],
    "schema": {},
    "file_constraints": {
      "property1": {
        "accept": "string",
        "max_size": 0
      },
      "property2": {
        "accept": "string",
        "max_size": 0
      }
    },
    "ui_hints": {
      "property1": {
        "placeholder": "string"
      },
      "property2": {
        "placeholder": "string"
      }
    },
    "property_order": [
      "string"
    ]
  },
  "output": {
    "schema": {},
    "property_order": [
      "string"
    ]
  },
  "dependencies": {
    "skills": [
      {
        "id": "string",
        "version": "string",
        "name": "string",
        "description": "string",
        "home_writable": true
      }
    ],
    "mcp_servers": [
      {
        "id": "string",
        "version": "string"
      }
    ],
    "integrations": [
      {
        "id": "string",
        "version": "string",
        "tools": [
          "string"
        ],
        "scopes": [
          "string"
        ]
      }
    ]
  },
  "last_run": {
    "id": "string",
    "status": "string",
    "started_at": "2019-08-24T14:15:22Z",
    "duration": 0
  },
  "running_runs": 0,
  "version_count": 0,
  "forked_from": "string",
  "home_space_id": "string",
  "home_writable": true,
  "home_deletable": true,
  "home_shareable": true,
  "has_unarchived_changes": true,
  "effective_timeout_seconds": 0,
  "active": true
}

{
  "type": "https://docs.appstrate.dev/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "name: Invalid input: expected string, received undefined (+2 more)",
  "code": "validation_failed",
  "request_id": "req_abc123",
  "errors": [
    {
      "field": "name",
      "code": "required",
      "message": "Invalid input: expected string, received undefined"
    },
    {
      "field": "email",
      "code": "invalid_format",
      "message": "Invalid email address"
    },
    {
      "field": "age",
      "code": "invalid_type",
      "message": "Invalid input: expected number, received string"
    }
  ]
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Resource not found",
  "code": "not_found",
  "request_id": "req_abc123"
}

{
  "type": "http://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "string",
  "request_id": "string",
  "param": "string",
  "retry_after": 0,
  "errors": [
    {
      "field": "string",
      "code": "string",
      "message": "string",
      "title": "string",
      "candidate_connections": [
        {
          "id": "string",
          "label": "string",
          "account_id": "string",
          "owned_by_actor": true,
          "needs_reconnection": true
        }
      ],
      "connection_id": "string",
      "missing_scopes": [
        "string"
      ],
      "owned_by_actor": true,
      "required_scopes": [
        "string"
      ],
      "auth_key": "string",
      "required_auth_key": "string",
      "available_auth_keys": [
        "string"
      ],
      "connect_url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "packageId": "string"
    }
  ]
}

{
  "type": "about:blank",
  "title": "Invalid MCP Server Bundle",
  "status": 422,
  "detail": "MCP-server package '@myorg/tools' has no activatable published version.",
  "code": "bundle_invalid",
  "request_id": "req_abc123"
}

Move a package to another home space

Authorization

Path Parameters

Header Parameters

Request Body

Multiple body fields failed validation

Single non-body field failed validation