Migrating Off Kiwi TCMS: The Free Tier Route Through the API

A QA lead staring down a Kiwi TCMS migration usually expects the same headache as every other open source tool. No API, a database nobody wants to touch, and a weekend lost to scripting. That expectation is wrong here, and this post says so plainly in its first paragraph rather than manufacturing a fight that does not exist.

Migrating off Kiwi TCMS is, in practice, one of the calmer migrations in this category, and it is worth explaining exactly why before getting into the mechanics. Kiwi TCMS, checked on 25 August 2026, is GPL-2.0, shipped version 16.3 on 24 August 2026, has roughly 1.2k stars on GitHub, and has passed 500,000 container pulls. That is a healthy, actively maintained project by any normal measure. A team planning to leave it should say so honestly rather than inventing reasons to complain about a tool that has served them well.

The genuine complications in a Kiwi TCMS migration are not technical. They are tier shaped. A SQL export sits behind a paid subscription, and the free rolling release means a team may struggle to say exactly which version produced their data. This post covers both, plus the ordered route out through the free tier's real API.

The encouraging part, stated first

Kiwi exposes a documented API and personal API tokens. That single fact makes this a better tempered migration than most.

Cases and executions can be read programmatically instead of scraped from a web interface one page at a time. A team does not need database access or a support contract to get its own data out. They need an API token, generated from their own account settings, and a script willing to walk through pages of results.

The tier complication that actually bites

Here is where the honest picture gets less rosy. SQL exports sit inside the Private Tenant Extras subscription rather than the free Community Edition, according to kiwitcms.org, checked 25 August 2026. A team on the free tier cannot simply dump the database and walk away.

That leaves the API as the practical route for anyone not paying for the higher tiers. It works, but it means writing a small amount of script rather than running one export command from a settings page.

A few other tier facts are worth knowing before planning around them:

• The free Community Edition container displays ads from EthicalAds inside the instance you host, and ad free images require the Self Support subscription at 25 dollars a month, per kiwitcms.org's "Self Support Subscription Explained", dated 20 August 2025
• Community Edition builds are x86_64 only, so there is no aarch64 image on the free tier, ruling out an Apple Silicon laptop or a Graviton instance
• Community Edition is a rolling release with no version tagged images, so a free tier user cannot pin a specific version, a capability that arrives with the paid tier
• Multi tenancy sits in the Enterprise tier at 600 dollars a month, and the full pricing ladder runs 25, 75, 600 and 2000 dollars a month, per the kiwitcms.org features page and "Community Edition Explained", dated 18 February 2026

None of that makes Kiwi TCMS a bad product. It makes the free tier a specific, bounded thing. A migration plan should be built around its actual edges rather than an assumed set of capabilities that a team read about somewhere else.

A practical ordered approach

With the API confirmed as the route, the migration itself follows a predictable shape. Work through these steps in order:

• Enumerate plans, cases and executions through the API, one page of results at a time
• Write everything to a flat intermediate format your team controls, such as a set of CSV or JSON files
• Inspect that intermediate format closely before importing it anywhere else
• Cross check a sample against the live Kiwi instance to confirm nothing silently dropped

The middle step matters more than it looks. An intermediate format you own means the import target can change later without a second trip through the API. It also gives the team something to hand to an auditor without exposing the live instance itself.

What to check before trusting the output

Four things go wrong quietly in API based exports, and a rushed migration tends to discover them only after cutover, usually during the first week with the new system:

• Attachments, which the API often returns as a link rather than the file content itself
• Custom fields, which may not appear in every endpoint response depending on how they were configured
• Tags, which are easy to miss if the export script only walks the case and execution endpoints
• The link between an execution and the bug it raised, which lives in a separate relationship the script has to fetch explicitly

A support tooling team migrating around 2,200 cases and 9,000 historical executions found the case and execution data came across cleanly through the API in a single afternoon of scripting. The bug links took a second pass the following day, because that relationship lived on a different endpoint the first script had not called. The team caught the gap by spot checking twenty cases against the live instance before declaring the export finished.

The version question a rolling release creates

Because Community Edition ships no version tags, there is no clean way to say later which release produced a given export. The fix is simple but easy to forget under deadline pressure.

Record the container image digest at export time, not just the date. A digest is a fixed, verifiable reference to exactly what was running, in a way a date alone is not, since a rolling release can change underneath a stated date without anyone noticing.

Write the digest down next to the export files themselves. Anyone auditing the migration months later then has something concrete to point to instead of a guess based on when the export folder was created.

A fair closing note

Not every team needs to leave. If the free tier's boundaries, meaning the ads, the x86_64 only builds, and the lack of version pinning, still fit a team's actual needs, staying is a legitimate and reasonable answer.

This post exists for the teams whose needs have outgrown that tier, not to talk everyone into moving regardless of fit. A team of six running a handful of suites on Community Edition may simply never hit these limits in a way that matters day to day.

Recognizing that early saves the time this whole migration would otherwise cost, and it is a perfectly defensible answer to give a manager who asks why the team has not moved yet.

Common mistakes worth naming

A short list of patterns that repeat across these migrations, worth reading before starting rather than after:

• Assuming the SQL export is available on every tier without checking first
• Forgetting to record the image digest before decommissioning the old container
• Treating a clean case count as proof the bug links came across too
• Migrating without first confirming whether the free tier's limits actually matter to the team

Each one is a five minute check that saves a much longer conversation later, once the old instance is already gone.