Test mode

Two prefixes, one rule

Every credential is one of two kinds, and you can tell which from the prefix — deliberately, so it is obvious in a config file, a code review, and a log line.

What a test account starts with

Nothing. A fresh test key sees an empty account — GET /v1/datasets answers [] — so the first thing you do with one is create a dataset and upload to it, exactly as you would live.

[]

Saying so plainly rather than promising a populated sandbox: there is no seeded data behind a test key today. What the mode gives you is a place to work that costs nothing and cannot touch your live data — upload a handful of rows you invented, or a real file you have not decided to send us yet, and every endpoint behaves as it does live.

That is still the fastest way to see the response shape before committing to it: no data-sharing agreement, no export, no cleanup. Just not a dataset we made for you.

Which mode a response came from

Datasets and versions carry livemode, a boolean, and that is the field that answers the question. Not as a courtesy — as a guard: a client can assert on it, and a staging deploy accidentally pointed at the sandbox announces itself in the payload rather than three weeks later in a number someone reported.

Do not confuse it with mode. That field also appears on a dataset and means something else entirely — whether the dataset is persistent or expires. Two similar words, two unrelated questions; livemode is the one about test and live.

The metric grid carries neither. A metrics response is horizon, the axis and the sections, and nothing about the credential that asked for it. So assert on the dataset you resolved before you query it, not on the grid that comes back — and note that this makes a grid alone insufficient to tell the two worlds apart, which is a gap in the response rather than a subtlety to work around.

They do not cross

A dataset created with a test key does not exist as far as a live key is concerned, and there is no promotion path between them — you create live datasets with a live key and upload real data to them. The enforced behaviour is that isolation, not separate infrastructure: livemode is a field on the same records, and the guarantee is what the API refuses to return across it.

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type":     "https://developer.plantactic.com/errors/not-found",
  "title":    "Not found",
  "status":   404,
  "detail":   "No dataset 9f2c4b1e-7a83-4d02-9c15-6b0e2a1d4f77, or it has
               no active version.",
  "instance": "/v1/datasets/9f2c4b1e-.../metrics"
}

The 404 is deliberate rather than a 403: confirming that an id exists somewhere you cannot reach is itself information. Note what the body does not say — it is word-for-word the response you get for an id that never existed, one that belongs to another account, and one that is merely still building. Four different situations, one answer.

The two keys are also revocable independently. Rotating a leaked test key is a config change rather than a live-data exposure — though anything you chose to upload to a test dataset is still yours to weigh.

A connected Claude session is always live. Test mode is a property of ptx_test_ REST keys; the credential the connector creates on approval is issued live, so there is no sandbox variant of it. See the connector guide.

Getting a live key

Ask for one. Both prefixes are issued by Plantactic against your account rather than minted from a form, so moving from test to live is a message rather than a button — mail support@plantactic.com from the address on your account.

Nothing about your test datasets moves with you. A live key cannot read them and a test key cannot read live data, which is the point of the boundary and is covered above.

Platforms computing metrics for many of their own customers go through the same conversation, mainly to settle the data-processing agreement rather than to qualify you.

Keeping them apart in practice

• Store them under different names. Not one PLANTACTIC_API_KEY that changes meaning per environment — PLANTACTIC_TEST_KEY and PLANTACTIC_LIVE_KEY, so a missing variable fails loudly instead of silently falling back.
• Grep for the prefix in CI. ptx_live_ appearing anywhere in a repository, a fixture, or a test log should fail the build. The prefix exists to make that a one-line check.
• Assert on livemode — not on mode, which is about expiry and reads the same in both worlds. Cheaper than any amount of config discipline, and it catches the case where the config was right and the deploy was not. Resolve the dataset to do it: the metric grid carries no mode field.
• Keep keys server-side. A key authorises your whole organisation — and /v1 allows no browser origin at all, so a page cannot call this API directly by any route. Proxy through your own backend.