Edit a profile

What an edit changes

This is the endpoint that changes what your audits actually do. A profile created here arrives as a draft nobody is using yet; an edit lands on a profile people may be running today, and it takes effect on the next analysis that starts. It is also where a draft you built is published — see below.

Send only the fields you want changed. Anything you leave out keeps the value it had, including the reviewers — omit workers entirely and only the profile record is touched.

The :id in the path is the profile's id as GET /v1/profiles lists it, which is the same string POST /v1/profiles hands back and the same one POST /v1/analyze takes. There is one id per profile and it works on every route. An id your organisation does not hold is a 404, which says nothing about whether it exists somewhere else.

Publishing, and staying published

status is what decides whether your organisation's own people are offered the profile in their list. Send "PUBLISHED" to publish it and "DRAFT" to take it back to a draft. This is the call that finishes a profile you built over the API: nobody has to open the admin panel for it.

Omit status and the stored one stands. An edit that renames a published profile leaves it published, and one that reworks a draft leaves it a draft. That is deliberate, and it is the reason the field has to be sent rather than derived: the alternative — taking the profile out of circulation on every edit — made profiles disappear from people's lists with nothing to say why.

It follows that a half-finished wording reaches everyone using a published profile the moment you save it. If that is not what you want, take the profile back to "DRAFT" first, edit, and publish again.

Only "DRAFT" and "PUBLISHED" are accepted; anything else is a 400 naming them, rather than a 200 for a profile that did not move. Creating a profile does not take this field at all — a profile is created as a draft and published here afterwards.

Sending workers replaces the whole set

workers is not merged reviewer by reviewer. The array you send is the profile's reviewers afterwards:

• A reviewer with an id you already have is edited in place.
• A reviewer with no id is created.
• A reviewer you leave out is no longer part of this profile. It is not deleted — if another profile names it, that profile is unaffected — and the rule sets it cited stay stored, still counted against your organisation's limit on legal sources whether or not anything cites them. That includes sources you created with snippets below.

A reviewer can belong to more than one profile. GET /v1/profiles marks such a reviewer with "shared": true, and editing it here changes every profile that names it — including profiles this request never mentioned. Read the list before you edit if you did not build the profile yourself.

Sending rules on a reviewer replaces its legal sources the same way. A pinpoint is the id the provision is addressed by (kap_6_par_1§), never the citation it is printed as (6 kap. 1 §), and sending the wrong one is refused naming the reference you wrote — creating a profile explains where to get the right one.

Adding your own rules in the same edit

snippets creates rule sets of your own together with the reviewers that cite them, exactly as on creating a profile. It travels only with workers — every entry must be cited by a reviewer, and only workers names any — and since workers replaces the whole set, send every reviewer the profile should keep, not only the one citing the new rule:

{
  "snippets": [
    {
      "ref": "ordningsregler",
      "name": "§ 1 Ordningsregler",
      "source": "Ordningsregler för Brf Eken, antagna 2025-03-11",
      "authorityType": "LOCAL_REGULATION",
      "content": "§ 1 …"
    }
  ],
  "workers": [
    { "name": "Ordningsgranskare", "snippetIds": ["ordningsregler"] }
  ]
}

No jurisdictions here: an edit refuses it, and the profile's stored legal orders stand.

ref is a label for this one request and is never stored; a reviewer cites the entry by putting the same string in snippetIds, and the server stores the key it mints in its place. The answer carries snippets, each entry's ref beside the id and snippetKey of the source — snippetKey for snippetIds, id for PATCH /v1/snippets/:id.

Resending the same snippets creates no second source. The address of a source written here follows from the profile and the entry's ref, so an integration that syncs its profiles on a schedule can resend its snippets every time: an entry identical to the source this profile already created under that ref writes nothing and is cited by the key it already has.

That holds for sources only. A reviewer with no id is created, so resending the example above unchanged creates a second reviewer and leaves the first one stored outside the profile. After the first edit, send each reviewer with the id the answer's workerIds gave it.

This endpoint never edits a stored source. An entry that reuses a ref this profile already created a source under, with anything different in it, is a 409 naming the stored id: change the source with PATCH /v1/snippets/:id, or give the entry a new ref.

An entry whose address already holds a legal source that belongs to another organisation is a 403; give the entry a different ref.

Two consequences follow, and neither is refused. Renaming a ref creates a new source and leaves the old one stored, as a reviewer you drop leaves its sources. And every source you create counts against your organisation's limit on legal sources, which GET /v1/quotas answers: the request is weighed as a whole before anything is written, and one that would take you past the limit is a 409 that creates nothing. An identical resend creates nothing and counts nothing.

Changing the shortcut

urlSlug is the address the profile opens at, as /p/{urlSlug}. Omit it and the stored one stands; send a new one to move the profile to a new address, or send "" to take the shortcut away. Anyone holding the old link lands on nothing afterwards, so treat it as you would any published URL.

Hiding a profile, and putting it back

unlisted: true takes the profile out of the lists your organisation's own people choose from, leaving it reachable on its /p/{urlSlug} shortcut and through this API. unlisted: false puts it back. Omit the field and the stored setting stands — an edit that renames a hidden profile leaves it hidden.

Anything that is not true or false is a 400. That matters more here than on a create: a value we could not read would look exactly like a field you never sent, so you would be answered 200 by a profile that is still hidden.

Listing is not publishing. A profile can be published and unlisted at the same time, which is precisely the profile that answers on its shortcut and appears in nobody's picker. The two fields are set independently, and sending one says nothing about the other.

Request body

An analysis already running uses the edited profile

Analyses are not frozen at the moment you start them. The profile is read when the analysis actually runs, which can be seconds or minutes after POST /v1/analyze answered — so an analysis queued before your edit will run under the profile as it is after it.

Usually that is invisible and harmless. Two edits will fail such an analysis outright: removing a reviewer it was going to run, and pushing the profile past your organisation's reviewer limit. The job then comes back from GET /v1/jobs/:jobId as FAILED with "errorCategory": "INVALID_CONFIGURATION", which is the one failure category that says the fault is in the configuration rather than in our systems — a retry of the same document will fail the same way until the profile is fixed.

If your integration edits profiles on a schedule, the safe habit is to edit when nothing of yours is in flight. Nothing stops you doing otherwise, and nothing ever silently changes an analysis you have already been given a result for.

What will be refused

• An id that names no profile of yours. A 404, and the id to check it against is the one GET /v1/profiles lists — the same string POST /v1/analyze takes.

• A profile your organisation does not own. Profiles you inherit — the ones you did not build — are read-only here. A 403 says so; copying one into your own organisation is a separate step.

• A change to a reviewer we own. Your profile may name one of ours, and naming it is all this endpoint lets you do with it: sent back as it stands, the profile keeps pointing at our record and keeps receiving our improvements to it. Changing any of its four writable fields is an edit of a record every other organisation runs, and is a 403 naming the reviewer, including when the id names a template's own record — and since this endpoint replaces the whole reviewer, omitting a field is a change to it unless it is empty already. To run your own version, send it as a new reviewer with no id; it is created under your organisation and stands beside ours.

• The same rules a create is held to. Every reviewer must hold binding law, every source must already be in the library — or be written in this request, in snippets — and the limits on reviewers, sources and instruction length apply unchanged. See creating a profile for what each of those means. One thing an edit adds: a reviewer that already holds more sources than the limit allows keeps what it has and may not be given more, so the allowance only ever ratchets down.

• A rule set is named by its snippetKey, never by its id. GET /v1/snippets publishes both fields on every record, and an analysis looks a rule set up by the key alone — so snippetIds takes keys, in spite of what the field is called. A document id there is a 400 naming each value you sent beside the key that record answers to. Worth reading twice on an edit: workers replaces what is stored rather than merging into it, so this is the write that decides which sources your reviewers hold from here on.

• A snippets entry is held to the rules POST /v1/snippets holds a source to, the field named with its position. Its content may be at most 2,500 characters, counted as Unicode code points, and a longer one is a 400 naming the source. Each of its anchors must address a provision of a law we hold, in a legal order that is open; one that addresses nothing is a 400 naming the entry by position.

• The server owns some fields. id comes from the path, status never moves on an edit, the legal orders follow the provisions your reviewers cite, and the authorship fields are ours. All four are refused rather than accepted and overwritten, and on a snippets entry so are id, snippetKey, tenantId, text and clonedFromSystemId.

• A jurisdiction has to be a code, and it has to be open. Two upper-case letters with an optional _ suffix — SE, US_NH — matched exactly; se is not SE and is a 400 naming what you sent. A well-formed code nobody has opened is a 400 naming it; the legal orders your organisation may use are in its settings.

• A shortcut another of your profiles holds. urlSlug is unique within your organisation, and taking one already in use is a 409 naming the profile that has it.

• A field that is not in the table above is refused, naming it. The same goes for a field on a reviewer. This matters more on an edit than anywhere else: a 200 means every field you sent replaced what was stored, so a misspelled field name is a 400 rather than an edit you believe you made.

• We have to be able to weigh your sources at all. Deciding which of a reviewer's sources bind means reading the norm hierarchy of its legal orders, and when that read fails we refuse rather than guess. Nothing is wrong with your request; retry, and tell us if it repeats.

Nothing is written unless all of it passes: the profile, its reviewers and the sources in snippets are one atomic write.

Which check refused

Every refusal above answers with a stable name in error.details.refusal, and the values that refusal names in error.details.values:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "No profile of that id exists in this workspace.",
    "details": {
      "refusal": "profile-not-found",
      "values": {}
    }
  }
}

Branch on details.refusal, never on message. The message is prose written for a person reading it once, and we reword it whenever we can say the same thing better; the name is the contract and does not move.

The table below is every refusal an edit can answer with, the ones it shares with a create included. Two of them only an edit reaches: profile-not-found and profile-owned-by-another-organisation.

Errors