Set authentication credentials for the Noark 5 API.

Supports two authentication methods:

• Basic auth (RFC 7617): username/password encoded as Base64

• OIDC / OAuth2 password grant: auto-discovers token endpoint via login/oidc/, with automatic token renewal via refresh_token

Args: username: The username for authentication. password: The password for authentication. base_url: Optional API base URL (default from env or http://localhost:8092/noark5v5/). auth_method: Authentication method — "auto" (default), "basic", or "oidc". With "auto", the server's root entity is queried to detect available login endpoints; OIDC is preferred over Basic. client_id: OIDC client identifier (optional, used with oidc method).

Returns confirmation and root entity links on success.

Get the root API links using authenticated client.

Returns all available relations from the API root, including those that require authentication (arkivstruktur/, metadata/, sakarkiv/). After login, this reveals top-level navigation endpoints.

To find global entity collections, follow the arkivstruktur or sakarkiv link to its URL, then use noark5_entity_links on that URL to discover OData query templates for each entity type (e.g., dokumentobjekt/{?$filter}). The cleaned base URLs can be passed to noark5_filter_entities.

Get full details of an entity by its URL.

Args: entity_url: The self-href URL of the entity to fetch.

Returns the formatted entity with all fields and links.

List all children of an entity using HATEOAS discovery.

Without parent_url, lists top-level entities (arkiv/fonds and arkivskaper). With parent_url, automatically discovers available child collections from the entity's links and fetches each type. Mirrors noark5_navigate_up for upward traversal.

Args: parent_url: The self-href URL of the parent entity (omit for top-level listing). filter_str: Optional OData $filter expression applied to each collection.

Returns formatted grouped list of children by type, or error message.

Global search across all entity types using $search (title match) with optional $filter.

Searches all collections found under arkivstruktur and sakarkiv for entities whose title matches the query. An optional OData $filter expression is ANDed with the $search term to further narrow results.

Use noark5_search_entities when you want to find entities globally by keyword, optionally constrained by a condition (e.g., date range, field value).

Use noark5_filter_entities instead when you need precise filtering on a known collection URL discovered via noark5_entity_links or noark5_list_children. Filter operates on one collection at a time with full OData expression support.

Args: query: The search term to match against entity titles (full-text, case-insensitive). filter_str: Optional OData $filter expression applied in addition to the search term (e.g., 'opprettetDato ge 2026-01-01T00:00:00Z').

Returns list of matching entities with their URLs, titles, and types.

Create a new arkivskaper (archive creator).

Args: arkivskaper_id: The unique identifier for the archive creator. navn: The name of the archive creator. attributes: Optional JSON object with additional fields. All optional: beskrivelse.

Returns details of the created arkivskaper including its URL.

Create a new top-level archive (fonds).

Args: tittel: The title of the new fonds. attributes: Optional JSON object with additional fields. All optional: beskrivelse, arkivstatus, dokumentmedium, oppbevaringssted, avsluttetDato, avsluttetAv, referanseAvsluttetAv.

Returns details of the created fonds including its URL.

Create a new arkivdel (series/partition) under a fonds.

Args: arkiv_url: The self-href URL of the parent fonds. tittel: The title of the new arkivdel. attributes: Optional JSON object with additional fields. All optional: beskrivelse, arkivdelstatus, dokumentmedium, oppbevaringssted, avsluttetDato, avsluttetAv, referanseAvsluttetAv, arkivperiodeStartDato, arkivperiodeSluttDato, referanseForloeper, referanseArvtaker.

Returns details of the created arkivdel including its URL.

Create a new mappe (file) under a parent entity.

Args: parent_url: The self-href URL of the parent (arkivdel, klasse, or mappe). tittel: The title of the new file. beskrivelse: Optional description for the file. attributes: Optional JSON object with additional fields. All optional: mappeID, offentligTittel, noekkelord, dokumentmedium, oppbevaringssted, avsluttetDato, avsluttetAv, referanseAvsluttetAv.

Returns details of the created mappe including its URL.

Create a new registrering (registration) under a mappe.

Args: mappe_url: The self-href URL of the parent mappe. tittel: The title of the new registration. attributes: Optional JSON object with additional fields. All optional: arkivertDato, arkivertAv, referanseArkivertAv, registreringsID, offentligTittel, beskrivelse, noekkelord, forfatter, dokumentmedium, oppbevaringssted.

Returns details of the created registrering including its URL.

Create a new dokumentbeskrivelse (document description) under a registrering.

Args: registrering_url: The self-href URL of the parent registrering. tittel: The title of the document description. attributes: Optional JSON object with additional fields. All optional: dokumenttype, dokumentstatus, beskrivelse, forfatter, dokumentmedium, oppbevaringssted, tilknyttetRegistreringSom, dokumentnummer, tilknyttetDato, tilknyttetAv, referanseTilknyttetAv, eksternReferanse.

Returns details of the created dokumentbeskrivelse including its URL.

Create a new klassifikasjonssystem (classification system) under an arkivdel.

Args: arkivdel_url: The self-href URL of the parent arkivdel. tittel: The title of the classification system. attributes: Optional JSON object with additional fields. All optional: klassifikasjonstype, beskrivelse, avsluttetDato, avsluttetAv, referanseAvsluttetAv.

Returns details of the created klassifikasjonssystem including its URL.

Create a new klasse (class) under a klassifikasjonssystem or another klasse.

Args: parent_url: The self-href URL of the parent (klassifikasjonssystem or klasse). tittel: The title of the class. attributes: Optional JSON object with additional fields. All optional: klasseID, beskrivelse, noekkelord, avsluttetDato, avsluttetAv, referanseAvsluttetAv.

Returns details of the created klasse including its URL.

Create a new saksmappe (case file) under an arkivdel.

Args: parent_url: The self-href URL of the parent arkivdel. tittel: The title of the case file. saksaar: Optional case year. Set to 0 or omit to let the server auto-assign. attributes: Optional JSON object with additional fields. All optional: sakssekvensnummer, saksdato, administrativEnhet, referanseAdministrativEnhet, saksansvarlig, referanseSaksansvarlig, journalenhet, saksstatus, utlaantDato, utlaantTil, referanseUtlaantTil. Also inherits from Mappe: mappeID, offentligTittel, beskrivelse, noekkelord, dokumentmedium, oppbevaringssted, avsluttetDato, avsluttetAv, referanseAvsluttetAv.

Returns details of the created saksmappe including its URL.

Create a new journalpost (registry entry) under a saksmappe.

Args: saksmappe_url: The self-href URL of the parent saksmappe. tittel: The title of the registry entry. attributes: Optional JSON object with additional fields. All optional: journalaar, journalsekvensnummer, journalpostnummer, journalposttype, journalstatus, journaldato, dokumentetsDato, mottattDato, sendtDato, forfallsdato, offentlighetsvurdertDato, antallVedlegg, utlaantDato, utlaantTil, referanseUtlaantTil, journalenhet. Also inherits from Registrering: arkivertDato, arkivertAv, referanseArkivertAv, registreringsID, offentligTittel, beskrivelse, noekkelord, forfatter, dokumentmedium, oppbevaringssted.

Returns details of the created journalpost including its URL.

Create a new arkivnotat (record note) under a saksmappe.

Args: saksmappe_url: The self-href URL of the parent saksmappe. tittel: The title of the record note. attributes: Optional JSON object with additional fields. All optional: dokumentetsDato, mottattDato, sendtDato, forfallsdato, offentlighetsvurdertDato, antallVedlegg, utlaantDato, utlaantTil, referanseUtlaantTil. Also inherits from Registrering: arkivertDato, arkivertAv, referanseArkivertAv, registreringsID, offentligTittel, beskrivelse, noekkelord, forfatter, dokumentmedium, oppbevaringssted.

Returns details of the created arkivnotat including its URL.

Update one or more fields on an entity using merge PATCH.

Accepts a JSON object mapping field names to new values. Multiple fields can be updated in a single call. Only the specified fields are sent; unchanged fields are preserved server-side (RFC 7396 merge semantics).

NOTE: This does NOT work for [0..] or [1..] sub-resources like 'forfatter' or 'noekkelord', which are modelled as separate entities by the API service. Use noark5_create_secondary_entity instead to add those.

Examples:

• Update single field: '{"tittel": "New Title"}'

• Update multiple fields: '{"tittel": "New", "beskrivelse": "Description"}'

• Structured field: '{"dokumenttype": {"kode": "U"}}'

To move an entity to a new parent, include '_links' in changes. First find the parent link's rel key using noark5_list_parents or noark5_entity_links. Examples:

• Move registrering to another mappe: '{"_links": {"https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/mappe/": {"href": ""}}}'

• Move mappe to another arkivdel: '{"_links": {"https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/arkivdel/": {"href": ""}}}'

Args: entity_url: The self-href URL of the entity to update. changes: JSON object mapping field names to new values (e.g., '{"tittel": "New"}').

Returns details of the updated entity.

Create a secondary [0..]/[1..] entity under a parent (e.g., forfatter, noekkelord).

In N5TG, fields with [0..] or [1..] cardinality are modelled as separate entities. Use this instead of noark5_update_entity to add them.

Common types and their field names: - forfatter: {'forfatter': 'Author Name'} - noekkelord: {'noekkelord': 'keyword'} - merknad: {'tekst': 'note text'} - kryssreferanse: {'kryssreferanse': 'reference'}

Args: parent_url: The self-href URL of the parent entity (e.g., dokumentbeskrivelse). entity_type: The type ('forfatter', 'noekkelord', 'merknad', etc.). field_name: The field name within the secondary entity. field_value: The value for that field.

Returns details of the created secondary entity.

Delete an entity.

Args: entity_url: The self-href URL of the entity to delete.

Returns confirmation or error message.

List all parent entities of an entity using HATEOAS discovery.

Uses N5TG-compliant link detection (per chapter 6 "Identifisere entitetstype" and "Rekursive entitetshierarkier") to find parent links via the entity's relation key and over{xx} relations for recursive hierarchies.

Some entities can have multiple parents simultaneously (e.g., dokumentbeskrivelse linked to several registreringer). Others have only one parent at a time but can be under different parent types (e.g., mappe under arkivdel, klasse, or another mappe). This tool finds all current parents and returns details about each.

Args: entity_url: The self-href URL of the entity to list parents for.

Returns formatted list of parent entities with their titles, types, and URLs.

List all navigation links on an entity, categorized by type.

Returns links organized into four categories:

• Parent links: navigate up the hierarchy (note: entities can have multiple parents)

• Children collections: list sub-entities (e.g., mapper under arkivdel)

• Create endpoints: POST to create new entities (ny-* relations)

• Query templates: OData URLs with {?$filter} for filtered queries

Useful to discover what navigation is possible from any entity. Use noark5_filter_entities with a query template URL for filtered listing. Use noark5_navigate_up to see details of all parent entities at once.

Args: entity_url: The self-href URL of the entity to inspect.

Returns categorized list of links with URLs and descriptions.

List or search metadata posts (katalogpost) within a specific catalog.

Use catalog_name to select the target katalog (e.g., "dokumentmedium", "format"). Omit filter_str to list all entries in small catalogs, or provide an OData filter to narrow down results in large ones (postal codes, countries, etc.).

Common filter examples:

• Exact code match: 'kode eq ''E'''

• Title substring: 'contains(kodenavn, ''EPUB'')'

• Multiple conditions: 'kode eq ''U'' and contains(kodenavn, ''UNKNOWN'')'

Args: catalog_name: Name of the metadata katalog to search in (e.g., "dokumentmedium", "format"). Leave empty to list all available catalogs. filter_str: Optional OData $filter expression applied within the catalog.

Returns formatted list of matching metadata entries with kode and kodenavn.

List or filter entities from a specific collection URL using OData $filter.

Operates on one collection at a time with full OData expression support. Use this when you have a known collection URL from noark5_entity_links or noark5_list_children and need precise field-level filtering.

Contrast with noark5_search_entities, which searches globally across all entity types using $search (title/text matching) — optionally combined with $filter for additional constraints.

Common filter examples:

• Filter by MIME type: 'mimetype eq ''application/epub+zip'''

• Filter by title substring: 'contains(tittel, ''MyArchive'')'

• Multiple conditions: 'mimetype eq ''application/pdf'' and contains(filnavn, ''report'')'

Args: collection_url: The base URL of the collection endpoint (without {?$filter}). E.g., from noark5_entity_links query template "base" URLs. filter_str: Optional OData $filter expression. Leave empty to list all entities.

Returns formatted list with systemID, title, and URL for each matching entity.

Download file content from a dokumentobjekt.

Resolves the referanseFil HATEOAS link on the given dokumentobjekt and downloads the binary content to disk (per N5TG chapter 6). Use noark5_list_dokumentobjekter first to find the desired objekt URL.

Args: dokobj_url: The self-href URL of the dokumentobjekt to download. output_path: Optional file path to save the downloaded content. If empty, a temporary file in /tmp/ is created with a random name. Note: Temporary files are NOT removed automatically. It is the user's responsibility to clean them up when no longer needed.

Returns saved file path and metadata.

Upload a file to an entity that has a fil relation key.

Any entity whose _links contains the relation key https://rel.arkivverket.no/noark5/v5/api/arkivstruktur/fil/ supports upload. (Use noark5_entity_links or noark5_list_children to discover this.)

Resolves the href of the fil relation from the entity's _links, then POSTs raw binary content to that URL. The server returns JSON containing all created and updated instances — typically a dokumentobjekt with file metadata (filnavn, mimeType, checksum, etc), plus any other entities it created during the upload (e.g., an embedded dokumentbeskrivelse when uploading from a registrering).

Args: entity_url: The self-href URL of any entity with a fil relation key. file_path: Path to a local file to upload. mime_type: MIME type of the uploaded file (default: application/octet-stream).

Returns details of all created/updated entities from the server response.