Transfer a website

A transfer moves a website — with its full history, content, and domains — from one organization to another in a single call.

Prerequisites

Access in both organizations: websites.transfer capability on the source website and website-creation rights in the target — see Access control
The target organization’s id, from GET /v1/organizations
For a website with custom domains enabled: active billing and unused paid capacity in the target — see Plans and limits

An API key carries access in a single organization, so it cannot pass the target-side check. Run transfers as a person who belongs to both organizations — from the dashboard, or a session on the app host.

Check the target's capacity

Skip this step for a website with custom domains disabled. A website using only its Cactal platform domain never counts toward a plan, even when published. For a website with custom domains enabled, the target organization must have active billing and unused paid capacity, or the transfer is rejected. Capacity normally matches the sites in use, so the practical path is often to disable custom domains, transfer, and have an owner in the target organization re-enable them, confirming the charge there. After a transfer out, the source organization’s freed capacity is released automatically.

Check the target's billing state

curl 'https://api.cactal.ai/v1/billing/state?organizationId=oTgt4rS6tU8vW0xY1zA3b' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

Confirm "status": "active" and compare billableSiteCapacity against billableSiteCount. Capacity must exceed the count to receive the site.

Transfer the website

POST /v1/websites/{websiteId}/transfer performs the move atomically.

curl -X POST 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT/transfer' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "targetOrganizationId": "oTgt4rS6tU8vW0xY1zA3b" }'

{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "organizationId": "oTgt4rS6tU8vW0xY1zA3b",
  "name": "Acme marketing site",
  "headVersion": 12,
  "publishedVersion": 11
}

The response is the website with its new organizationId. The website id never changes. Transferring to the website’s current organization returns 400.

Understand what moved

Everything owned by the website travels with it, because it is keyed by the website id:

Moves with the website	Notes
Source code and full version history	Head and published versions are unchanged.
CMS collections, fields, and items	Publish states preserved.
Assets	CDN URLs keep working.
Domains	The platform subdomain and custom domains keep serving; no DNS change needed.
Analytics	History stays attached to the website.

One thing is removed on purpose: every website-scoped access grant on the website is deleted during the transfer.

Website-scoped editors lose access at transfer time, and website-scoped API keys lose their grant on this website. A key whose only grant was this website stops authorizing anything. Re-invite editors and re-scope or re-issue keys in the target organization.

Restore access in the target organization

Members of the target organization now see the website through their organization roles; the source organization loses all visibility. Rebuild any per-website access:

Re-create a client key in the target organization

curl -X POST 'https://api.cactal.ai/v1/apiKeys' \
  -H "Authorization: Bearer $CACTAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "organizationId": "oTgt4rS6tU8vW0xY1zA3b",
    "name": "acme-content-agent",
    "expiresAt": null,
    "access": { "kind": "websites", "websiteIds": ["V1StGXR8_Z5jdHi6B-myT"], "role": "content_editor" }
  }'

Re-invite website editors with POST /v1/websites/{websiteId}/editors — see Invite teammates and clients. The transfer itself is recorded in the target organization’s audit log with the source and target organization ids.

Verify the transfer

Confirm the new owner organization

curl 'https://api.cactal.ai/v1/websites/V1StGXR8_Z5jdHi6B-myT' \
  -H "Authorization: Bearer $CACTAL_API_KEY"

You should see "organizationId": "oTgt4rS6tU8vW0xY1zA3b", and the website appears in GET /v1/websites?organizationId=oTgt4rS6tU8vW0xY1zA3b. If it was published, its hosts still serve — request the platform subdomain to confirm.

Troubleshooting

Symptom	Cause	Fix
`400` `Target organization must be different from the source organization`	`targetOrganizationId` is the website’s current organization.	Pick a different target.
`403` `forbidden`	The caller lacks access to the target organization, including any API key scoped to the source organization.	Run the transfer as a principal with `websites.create` access in the target organization.
`404` `Organization not found`	`targetOrganizationId` does not match an active organization.	Check the target organization id.
`403` `Billing must be active to receive this website`	The target has no active subscription.	Activate a plan in the target organization.
`403` `This organization has reached its website capacity`	The target has no unused paid capacity.	Disable custom domains on this website and re-enable them after the transfer, or disable them on another website in the target.
A client’s integration breaks after transfer	Its website-scoped key grant was deleted with the transfer.	Issue a new key in the target organization and update the integration.

Next steps

Manage API keys to rebuild scoped keys in the target organization
Invite teammates and clients to restore editor access
Websites concepts for the full website lifecycle

Get started

Core concepts

Guides

Build with agents

Platform

Transfer a website

Prerequisites

Troubleshooting

Next steps

​Prerequisites

​Troubleshooting

​Next steps

Prerequisites

Troubleshooting

Next steps