The fields of a case

Beside its title and its body, a case carries four things about how it matters and one about what it is tagged. All of them travel through POST /v1/test-cases and PATCH /v1/test-cases/{id}, and every one of them appears in the audit log as “was → became”.

Description and preconditions

Two free-text fields, description and precondition, up to 16 KiB each. They are shown as written — line breaks kept, no markup rendered yet — and on the dashboard they sit under their own headings on the case page and as two text areas on the form. Sending null in a PATCH clears one; leaving it out keeps it.

These two are the text of the case, so changing either raises the case’s version — a result that points at version 3 tested what version 3 said. Priority, tags, position and the suite are metadata: changing them does not move the version.

Priority

Five levels, in rank order:

low · normal · important · high · critical

normal is the default. The order is not decoration — priorityMin=high on the list means “high and critical” because the levels are ranked, and the dashboard shows each as a distinct glyph beside the title so the scale reads without colour.

Anything outside the five is refused with the list:

400 · validation failed — priority: must be one of low, normal, important, high, critical

Position

position is a case’s place among the cases of its suite (or among the unfiled ones), dense and zero-based. The list comes back in that order, suite by suite; sending a new position in a PATCH moves the case and renumbers its neighbours. Suites have the same field for the same reason.

Tags live in the title

A tag is written in the title, as @name, and that is where it is stored:

Checkout keeps the total right @smoke @payments

The rules are the ones the wider tool ecosystem already uses: a tag starts the title or follows a space or a tab, its body is made of \w = - _ ( ) . : & and ends in a word character or ), it is shorter than 120 characters, and its case is yours — Smoke and smoke are two tags. An e-mail address or a @ in the middle of a word is not a tag.

The API reads them out for you: every case answers with tags — the @names of its title, without the @, each once, in order — and the dashboard shows the clean title with the tags as chips. You can write them back either way:

• put them in the title — "title": "Checkout keeps the total right @smoke";
• or send tags beside a clean title — "title": "Checkout keeps the total right", "tags": ["smoke"], and the stored title gets the @smoke tail written for you.

When both are sent, tags wins over the title’s own tail; "tags": [] strips every tag. Two refusals guard the field:

Refusal	When
400 · validation failed — title: a title cannot consist of tags only	nothing is left once the tags are removed
400 · validation failed — tags.1: invalid tag 'smoke test' — a tag is 1 to 119 characters from \w = - _ ( ) . : &	a tag breaks the rule — the refusal names it

One source, an index behind it

The title is the only place a tag is kept. The table the list filters by is an index derived from titles, rebuilt from them on every write — so a tag can never disagree with the title it was read from, and POST /v1/admin/reindex-tags (owner only) rebuilds the whole index from the titles if it ever needs to be.

Renaming and merging tags

GET /v1/settings/tags lists the project’s tags with how many cases carry each — Smoke beside smoke, each with its own count. The same list is Settings → Tags on the dashboard, and two operations act on it:

• Rename — POST /v1/settings/tags/rename with { "from": "smok", "to": "smoke" } rewrites the title of every case that carries from, one audit entry per case. If to already exists the two simply merge; to is checked against the tag rule first.
• Merge — POST /v1/settings/tags/merge with { "from": ["Smoke", "smoke-test"], "into": "smoke" } replaces every tag in from with into, in every title, in one transaction; into need not exist yet, and from must not contain it.

Both answer how many cases they touched, and neither moves a case’s version — a tag is metadata.

Automated cases keep their tags in the code

An automated case gets its title — and so its tags — from the test in your repository. Renaming a tag here changes the case; the next import still sees the old title in the code and reports the difference. For those, add the tag in the test’s name and let the import carry it over.