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.

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.

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.

• The same rules a create is held to. Every reviewer must hold binding law, every source must already be in the library, 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.

• 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.

• A jurisdiction has to be one we carry. SE, NO or EU, matched exactly — se is not SE. Anything else is a 400 naming what you sent.

• 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.

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