Create a profile

What you are creating

A profile is one kind of audit: which reviewers run, which legal sources each of them may cite, which document type it expects, and what language it answers in. Until now it existed only as something an administrator built in the web application; this endpoint builds the same object, and it is the same code that validates both.

You send the profile's name, the document type it audits, and the reviewers. A reviewer is a name, an instruction in its own words, and the legal sources it holds — provisions named directly, rule sets named by key, or both. Rule sets of your own that do not exist yet can be written in the same call, in snippets — see below.

The id you get back is the id everything else takes

profileId is what the profile is called everywhere: it is how GET /v1/profiles lists it, what you send as profileId to POST /v1/analyze, and what addresses it for PATCH /v1/profiles/:id, and what removes it again with DELETE /v1/profiles/:id if you created it by mistake. Store that one string and use it for all four.

workerIds are the reviewers, and they are spelled differently — longer, and carrying your organisation's own identifier. That is not something to correct or trim: send each one back exactly as you were given it. It is the same string GET /v1/profiles lists for that reviewer, and the same one POST /v1/analyze takes — a reviewer is matched by the record it names rather than by the characters you send, so an id you cached earlier keeps working too.

It arrives as a draft, deliberately

A profile created here is a draft. Your own integration can run it immediately — GET /v1/profiles returns it and POST /v1/analyze accepts it — but the people who use the web application do not see it in their list until it is published.

That is the point of the draft: minting something already live is a different risk from changing something that is, so building a profile and putting it into circulation stay two separate acts. Sending status here is refused rather than ignored, so a request never comes back 201 having quietly not published anything.

Publishing is one more call, and it is yours to make: PATCH /v1/profiles/:id with {"status": "PUBLISHED"}. Nobody has to open the admin panel for it.

The legal orders are derived, not declared

Whichever jurisdictions your provisions belong to are the jurisdictions the profile is stored against. You do not send them, and sending them alongside cited provisions is a 400.

The one exception is a profile that cites no statute at all — a profile built entirely on your own rule sets. There is nothing to derive from, so jurisdictions is required, and if your organisation has a default it is used instead. If neither is there, the answer is a 400 naming jurisdictions: send it, or cite a provision and let it be derived.

Either way, a jurisdiction we do not carry is refused naming it and listing the ones we do. It is matched exactly: se is not SE.

Your own rules can be created in the same call

A profile is often built on rules nobody else holds — an association's own regulations, an employer's own guidelines. snippets writes those rules together with the profile and the reviewers that cite them, so one request creates all three, and nothing is left behind if any part of it is refused.

{
  "name": "Granskning av ordningsregler",
  "documentType": "Styrelsebeslut",
  "jurisdictions": ["SE"],
  "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"] }
  ]
}

answers 201:

{
  "success": true,
  "profileId": "granskning_av_ordningsregler_k4m2",
  "workerIds": ["tenant_9f3a_worker_ordningsgranskare_p8x1"],
  "status": "DRAFT",
  "snippets": [
    {
      "ref": "ordningsregler",
      "id": "tenant_9f3a_snippet_ordningsregler_3fa91c07",
      "snippetKey": "tenant_9f3a_snippet_ordningsregler_3fa91c07"
    }
  ]
}

ref is a label for this one request, and it is never stored. You choose it — lower-case letters, digits, _ and -, unique within the request — and a reviewer cites the entry by putting the same string in snippetIds. The server mints the source's durable identity and stores its key in snippetIds in place of your ref, so you never have to carry an identifier from one call into the next. Every entry must be cited by at least one reviewer: an uncited one would be a source nobody reads that still counts against your limit.

Two identities come back beside each ref, as they do from POST /v1/snippets. snippetKey is what a reviewer cites — send it in snippetIds when a later request names this source without writing it again. id addresses the record, for PATCH /v1/snippets/:id when you want to change what it says; this endpoint never edits a stored source.

Each entry takes exactly the fields POST /v1/snippets takes, is refused by the same rules, and has the field named with its position — snippets[0].text cannot be set: …. Its content is compiled into the citable element before the 201 is answered, so the very next analysis can cite it. Two more things to know before you send one:

• Send jurisdictions. A profile whose reviewers cite only their own sources cites no statute, so there is nothing to derive its legal orders from — see above.
• 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: if its entries would take you past the limit it is a 409 and nothing is created.

A retried POST creates a second profile, second reviewers and second sources, as a retried create always has. To change a profile you already have — and add rules to it — use PATCH /v1/profiles/:id, where resending the same snippets entry is recognised rather than duplicated.

A profile can answer on a shortcut

urlSlug is the address the profile opens at, as /p/{urlSlug}. It is optional and free text, and it is what a colleague pastes into a chat rather than a profile id. Two profiles in the same organisation may not hold the same shortcut — the second one is a 409 naming the profile that has it — but two different organisations may.

A profile can be kept out of the pickers

unlisted: true builds a profile that does not appear in the lists your organisation's own people choose from. It still exists, it still runs, and it is still reachable on its /p/{urlSlug} shortcut and through this API — it is simply not offered to everyone. This is the field to send when you are building a profile for one team rather than for the whole organisation.

Two things are worth knowing before you send it. A profile with unlisted: true and no urlSlug can be reached by your integration and by nothing else, which is a perfectly reasonable thing to build and a surprising thing to discover later. And listing is not the same control as publishing: a profile created here is a draft either way until it is published.

It defaults to false, and anything that is not true or false is a 400 rather than a silently ignored value. You can change it afterwards with PATCH /v1/profiles/:id.

A provision has two names, and only one of them works here

Each entry in rules names one provision with three fields — jurisdiction, work and pinpoint. The one to get right is pinpoint, because every provision carries two names:

• What it is called — 6 kap. 1 §, 7 §, 9 a §. This is the citation a lawyer writes and a report prints. It is not what you send.
• What it is addressed by — kap_6_par_1§, par_7§, par_9a§. This is the pinpoint.

They are matched exactly, character for character, and nothing translates between them. Sending the citation addresses no provision of that law, and the write is refused naming the reference you wrote — see Every provision must exist inside the statute it cites below.

Take a pinpoint from a response and send it back unchanged. The anchors on GET /v1/snippets/:snippetId carry it in exactly the form this endpoint expects. Never assemble one from a citation, and never adjust the one you were given — work and pinpoint are opaque, and their shape differs per legal order.

Request body

What will be refused

Every rule the web application applies applies here, and they are worth knowing before you write the request:

• A profile must have at least one reviewer. A reviewer is what does the reading, so a profile with none would answer every analysis with nothing at all. Sending workers: [] is a 400 rather than a 201 for an empty audit.
• A reviewer must hold binding law. A reviewer whose sources are all guidance, general advice or preparatory works cannot substantiate a finding, and the profile is refused naming that reviewer. Which instrument types bind is a property of the jurisdiction, not of this API.
• Every source must already be in the library, and you can put it there. A provision from a statute we have not ingested is refused naming the work. This endpoint does not fetch one for you — GET /v1/laws/:jurisdiction/:work does, on the spot, so the fix for that refusal is one call and a retry.
• 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, rather than a 201 for a profile whose rule sets would be missing from every report it produces without anything saying so.
• Every provision must exist inside the statute it cites. A pinpoint is matched against the provision's stored address exactly — par_7§, never the 7 § a citation is printed as — and one that addresses nothing is refused naming the reference you wrote. This matters because a reference that resolves to no provision is dropped from the analysis without a word, so the audit would run against less law than you asked for and the report would not say so. Take the pinpoints from GET /v1/laws/:jurisdiction/:work, which lists a law's provisions with the address each answers to — one page at a time, so follow nextCursor until it is null if the pinpoint you want is not in the first page — or check one you already have with GET /v1/snippets?jurisdiction=…&work=…&pinpoint=…, which answers 404 when nothing is addressed.
• A repealed provision cannot be cited. A repeal leaves the section in the register as a numbered placeholder carrying no text, so a reviewer citing one holds a legal source with nothing in it — and it would pass every check above, because the provision exists and its statute binds. GET /v1/laws/:jurisdiction/:work marks each such provision with isRepealNotice. Only provisions you are adding are refused: a reviewer that already stores one keeps it, so an existing profile can still be edited — and cleaned up.
• There is a limit on reviewers per profile — three, unless your organisation is configured otherwise.
• There is a limit on legal sources per reviewer — 25, counting cited provisions and rule sets together. Split a reviewer that needs more into two.
• There is a limit on how long an instruction may be — 1000 characters, counted as Unicode code points.
• A source's content has a ceiling — 2,500 characters, counted as Unicode code points. A longer snippets entry is a 400 naming the source, and nothing is written.
• A source's anchors must exist. Each anchor on a snippets entry addresses a provision of a law we hold, in a legal order that is open, exactly as on POST /v1/snippets; one that addresses nothing is a 400 naming the entry by position and every such anchor.
• An entry whose address already holds a legal source that belongs to another organisation is a 403; give the entry a different ref.
• There is a ceiling on how many profiles your organisation may hold, answered by GET /v1/quotas. Creating one past it is a 409; editing the profiles you have is never affected.
• A value has to have the right shape, not just the right field name. The profile and its reviewers are checked against the stored data contract as the last step before the write, so a snippetIds entry that is not a string — or any other value of a type the table above does not name — is a 400 quoting the field and what was wrong with it, never a 201 with that field quietly dropped.
• The server owns some fields. id, status, workers[].id and the authorship fields are refused rather than accepted and overwritten — and on a snippets entry id, snippetKey, tenantId, text, clonedFromSystemId and the authorship fields too.
• A field that is not in the table above is refused, naming it. The same goes for a field on a reviewer or on a snippets entry. Nothing is accepted and quietly ignored: a 201 means every field you sent was stored, so a typo is a 400 you can act on rather than a setting that silently never took effect.
• A jurisdiction has to be a code, and it has to be open. A code is two upper-case letters with an optional _ suffix — SE, NO, US_NH — matched exactly; se is a 400 naming what you sent and the field it arrived in, whether a cited provision or jurisdictions. A well-formed code is then held to the catalogue: a legal order is opened by the platform's administrators, and one nobody has opened is a 400 naming every such code. There is no list to copy from here — the legal orders your organisation may use are in its settings, and what is open changes without a release.
• 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 — because with no hierarchy every source weighs as non-binding, so guessing would tell you to add binding law you already have. 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": "BAD_REQUEST",
    "message": "The profile names 4 reviewers, which is more than the 3 this organisation allows.",
    "details": {
      "refusal": "too-many-reviewers",
      "values": { "count": 4, "limit": 3 }
    }
  }
}

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. values carries what the sentence interpolates, so you can build your own message without parsing ours.

Several names share one status — too-many-reviewers and record-fails-data-contract are both 400 — which is the whole reason this is here.

Errors