Apier MCP Server

Use this for a current-snapshot read of a Norwegian company's annual accounts (årsregnskap) from the OPEN Regnskapsregisteret tier. Given a 9-digit organisasjonsnummer (organisation number) it returns `has_filed_annual_accounts` (a tri-state — `true` = at least one annual-accounts record on file, `false` = the register authoritatively reports none for a covered entity, `null` = unknown / the open tier does not cover the entity, e.g. banks & insurers filing via a separate oppstillingsplan), `last_accounts_year` (the most-recent accounting year in Europe/Oslo), and that year's minimal `key_figures`: currency, presentation basis, total assets, annual result, operating result, and total equity + liabilities. `currency` is always surfaced so the monetary figures are never silently read as NOK — large issuers report in USD/EUR. The upstream read never throws: an unreachable register, a 404, or any non-200 all degrade to the tri-state `null` (unknown), never to a fabricated `false`. v1 is current-snapshot only — no multi-year history and no closed/authenticated tier. Input: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check. Failure modes the agent must handle: SCOPE_INSUFFICIENT if the key is not scoped read:brreg; VALIDATION_FAILED on a non-9-digit or mod-11-failing input. Note a well-formed but unknown org_number does NOT 404 here — it returns 200 with `has_filed_annual_accounts: null`. For the filing status as one input to a go/no-go verdict, use get_company_verification; for the registry identity, use get_company_context. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Use this to answer "who can legally sign for this Norwegian company, and how?" before acting on its behalf. Given a 9-digit organisasjonsnummer (organisation number) it returns a deterministic signing-authority classification — `sole` (one role signs alone), `joint` (several roles must sign together), `by_role` (multiple alternative combinations; the valid path depends on which role you hold), `prokura_only` (no signaturrett, but prokura is defined), `no_authority` (neither registered), or `unknown` (the signing rule could not be determined). The answer is normalised from the open Brønnøysund Fullmakttjenesten signing combinations (Brønnøysund applies the statutory signing rules server-side and returns `signeringsKombinasjon`; Apier buckets that output — it does NOT re-encode statute) combined with the signaturrett / prokura role-holders already loaded from /roller. `data.combinations[]` carries each combination's Brønnøysund `kombinasjons_id`, a human `description`, and its role codes; the holders are listed once on `data.signaturrett_holders` / `data.prokura_holders`. `data.kombinasjon_available` is `false` when the live Fullmakt lookup was unreachable, in which case the classification degrades to the /roller holders plus any prokura combinations still fetched. No legal citation is asserted. Input: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check. Failure modes the agent must handle: 404 not_found for a well-formed but unknown org_number; SCOPE_INSUFFICIENT if the key is not scoped read:brreg; UPSTREAM_UNAVAILABLE if Brønnøysund is unreachable and no serviceable cache exists; VALIDATION_FAILED on a non-9-digit or mod-11-failing input. For a fast go/no-go trust verdict rather than the full signing breakdown, use get_company_verification instead. This tool answers STATUTORY signing authority as recorded in the register: it takes no actor input and knows nothing about Altinn delegations. For which actions a SPECIFIC person (11-digit fødselsnummer / D-nummer) may perform for the org, use list_acting_capacity; for what the calling consumer's own delegation permits, use check_authorization. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Retrieve the structured Brønnøysund identity slice for a Norwegian organisation by its 9-digit organisasjonsnummer (organisation number, the public ID issued by the Brønnøysund Register Centre / Enhetsregisteret — Central Register of Legal Entities). The response carries the canonical registry facts: legal name; entity type / organisasjonsform (e.g. AS / Aksjeselskap (limited company), ENK / Enkeltpersonforetak (sole proprietorship), NUF / Norskregistrert utenlandsk foretak (Norwegian branch of a foreign company), ASA / Allmennaksjeselskap (public limited company)); the Norwegian Industrial Classification (NACE) industry codes assigned to the entity; the registered street and postal addresses; the Enhetsregisteret incorporation date; the dissolution date when the entity has been deregistered (`slettedato`); and the role-code summary (signaturrett / signing-authority and prokura / power-of-procuration role codes assigned to natural persons — codes only, never personal identifiers per the data-minimisation policy). Cache window is 24 hours; cache hits are served from the canonical companies table without re-hitting Brønnøysund. Choose this tool when an agent needs the identity slice ONLY without the rule-engine compliance verdict; pair with get_company_obligations or get_company_deadlines for the regulatory layer. Input: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check. Failure modes: 404 NOT_FOUND if the org_number is well-formed but unknown to Brønnøysund; SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; UPSTREAM_TIMEOUT on Brønnøysund latency; VALIDATION_FAILED on shape or mod-11 failure. Required scope: `read:brreg`. For a compliance verdict (obligations + deadlines) rather than registry identity, use get_company_summary instead. Closest overlap: get_company_profile returns the same Brønnøysund identity family — what distinguishes THIS tool is the signaturrett/prokura role-code summary, the open distress flags (konkurs, under_avvikling, under_tvangsavvikling), and the annual-accounts filing status; for the plain registry profile with NACE code descriptions and person role codes only, use get_company_profile instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Compute the upcoming Norwegian regulatory filing calendar for a specific organisation, looking horizon_months into the future. The response is one entry per (obligation, period) pair, each carrying: a stable obligation_id matching get_company_obligations; the due_date as an ISO 8601 timestamp in Europe/Oslo (DST-aware — the engine never hardcodes +01:00 / +02:00 and CET ↔ CEST transitions do not shift due dates by a calendar day); the legal_reference citation; a recurring boolean indicating whether the deadline repeats on a fixed cadence; and a business_day_adjusted boolean indicating whether the engine moved the date to the next Norwegian business day to land off a weekend or public holiday. Choose this tool when the agent needs the calendar view (when does the next MVA / A-melding / Årsregnskap filing land?) rather than the obligation menu. Pair with get_company_obligations to learn what each obligation_id requires. Inputs: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check, plus an optional horizon_months between 1 and 60 (defaults to the endpoint's standard horizon — matches the route's own horizonMonthsSchema clamp). Determinism (Rule 9): same input + same rulebook_version produces a byte-identical calendar. Failure modes: 404 NOT_FOUND for unknown org_numbers; SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; VALIDATION_FAILED on shape, mod-11, or out-of-range horizon (boundary [1, 60] matching the underlying route — round-7 polish widened from [1, 24] so the tool no longer refuses horizons the REST surface accepts). Required scope: `read:brreg` (matches the underlying /v1/company/{org}/deadlines route's `SCOPE_REQUIREMENTS` binding — round-7 polish corrected an earlier `read:rulebook` declaration that would have produced SCOPE_INSUFFICIENT at runtime since the route checks read:brreg). For the per-obligation compliance verdict rather than the date calendar, use get_company_obligations instead. For the entity-type-level filing calendar that needs no organisasjonsnummer (and no API key), use get_public_deadlines instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Use this to reconcile a Norwegian company's Altinn 3 filing history against the filings YOUR consumer submitted through Apier — the accountant/auditor reconciliation wedge. Given a 9-digit organisasjonsnummer (organisation number) it returns the org's Altinn filing instances (Mva-melding, A-melding, Skattemelding, …) — form code, title, receiving agency, submitted_at (Europe/Oslo), status, and instance id — each PAIRED with its Apier audit-log entry where one exists: `filed_via_apier` is true with an `apier_record` (audit_log id + correlation_id) for filings Apier submitted, false for filings made directly in Altinn. Pairing is best-effort — a transient audit-read failure degrades every filing to `filed_via_apier: false` rather than failing the call. Offset-paginated via optional { limit } (1–100, default 20) and { offset } (≥ 0, default 0); the response carries a `pagination` block with `has_more` and `next_offset`. An org with no filings returns 200 with an empty list, never a 404. This is a MOCK-GATED build: deterministic synthetic fixtures today; the live Altinn path is dormant until the `altinn:instances.read` Maskinporten scope is approved. Input: { org_number, limit?, offset? }. Failure modes the agent must handle: SCOPE_INSUFFICIENT if the key is not scoped read:altinn; AUTH_NO_DELEGATION in live mode when the org has not delegated to your system user; VALIDATION_FAILED on a non-9-digit or mod-11-failing org_number or an out-of-range limit/offset. For a company's upcoming filing deadlines rather than its past filings, use get_company_deadlines instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Evaluate the Apier Rulebook for a Norwegian organisation and return every applicable regulatory obligation with its current state and the legal reference it derives from. The response is one entry per obligation, each carrying: a stable obligation_id (e.g. `MVA_FILING_BIMONTHLY`, `A_MELDING_MONTHLY`, `ARSREGNSKAP_FILING`); the legal_reference citation pinning the obligation to lovdata.no (`Skatteforvaltningsloven § 8-3`, `Aksjeloven § 7-6`, etc.); the current state enum (`filed` / `pending` / `in_progress` / `failed` / `overdue` / `unknown`); the bokmål description (description_nb) inherited byte-for-byte from the Rulebook — agents must NEVER re-translate this string; and the freshness window the evaluation is valid until. Determinism (Rule 9): the same org_number plus rulebook_version always produces a byte-identical obligation list. The evaluation always runs against the CURRENT instant — there is no historical-instant input at v1. (The underlying /v1/company/{org}/obligations route does not parse `?as_of=` today; the PR-070-tools brief's proposed `as_of` parameter was dropped to match the route exactly. Historical-instant evaluation lands in a future PR once the route adds the parameter.) Choose this tool when the agent needs the full obligation menu rather than upcoming deadlines (use get_company_deadlines for the calendar view). Failure modes: 404 NOT_FOUND for unknown org_numbers; SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; VALIDATION_FAILED on shape or mod-11. Required scope: `read:brreg` (matches the underlying /v1/company/{org}/obligations route's `SCOPE_REQUIREMENTS` binding — round-7 polish corrected an earlier `read:rulebook` declaration that would have produced SCOPE_INSUFFICIENT at runtime since the route checks read:brreg). For the upcoming filing calendar alone, use get_company_deadlines instead. For the universal entity-type-level obligation set that needs no organisasjonsnummer (and no API key), use get_public_obligations instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Resolve a Norwegian organisasjonsnummer (9-digit org number) into a structured company profile sourced from Brønnøysund Enhetsregisteret (data.brreg.no). The response carries the company's display name, organisational form (e.g. AS = Aksjeselskap, ENK = Enkeltpersonforetak, ASA = Allmennaksjeselskap), Norwegian industry codes (NACE) with descriptions, the registered street address (forretningsadresse) and any separate business address (postadresse), the Enhetsregisteret registration date, the agent-facing status enum (`active` for operating entities, `dissolved` for entities that have been deleted, gone bankrupt, are under voluntary or forced liquidation), the dissolution date when known (slettedato), the MVA-registered flag (registrertIMvaregisteret), and a deduplicated list of role codes assigned to natural persons (DAGL, LEDE, MEDL, NESTL, INNH, etc.). Per Norwegian data minimisation rules (CLAUDE.md Rule 11), the response deliberately CARRIES role codes ONLY — never personal identifiers (fødselsdato, personnummer, home address, email, phone). The data is Tier 1 public infrastructure under NLOD (Norsk lisens for offentlige data); no delegation is required. Cache TTL is 24 hours (matches Brreg's daily publish cadence); if Brreg is unavailable, the response may serve a stale cached row up to 7 days old with metadata.stale=true and metadata.staleness_seconds populated. Required scope: `read:brreg`. Raw-HTTP fallback note: the backing REST route is POST /api/v1/brreg/company-profile (the org number goes in the JSON body), whereas the sibling company tools are GET /api/v1/company/{org}/… — a known method inconsistency, so do not assume GET when calling this endpoint directly over HTTP. For an evaluated compliance verdict rather than the raw registry profile, use get_company_summary instead. Closest overlap: get_company_context returns the same Brønnøysund identity family — what distinguishes THIS tool is the full address detail (forretningsadresse + postadresse) and NACE code descriptions, with person role CODES only; when you need the signaturrett/prokura role-code summary, the open distress flags, or the annual-accounts filing status, use get_company_context instead. Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Retrieve a one-shot compliance summary for a Norwegian organisation by its 9-digit organisasjonsnummer (organisation number, the public ID issued by the Brønnøysund Register Centre / Enhetsregisteret — Central Register of Legal Entities). Use this as your FIRST call when orienting against a company: one round-trip COMPOSES entity_type (e.g. AS / Aksjeselskap (limited company), ENK / Enkeltpersonforetak (sole proprietorship), NUF / Norskregistrert utenlandsk foretak (Norwegian branch of a foreign company)), the nace_codes industry classification, mva_registered (VAT-registration tri-state), the served data_tier, the full obligations[] catalogue the Universal Rulebook evaluates (one verdict per applicable rule, each carrying its own per-obligation state), and the rolling deadlines[] filing calendar — all computed from one rule version and one company snapshot so downstream reasoning never has to reconcile drifting views. The obligations[] array is byte-identical to what get_company_obligations returns (same rule-engine evaluation, shared cache row); deadlines[] matches get_company_deadlines over the same horizon on tier_1, and on tier_2 additionally carries the definitive per-period filing_status (filed / overdue, sourced from compliance_states) that the standalone deadlines tool never injects. This MCP tool exposes only { org_number }, so call get_company_deadlines when you need to control the deadline horizon_months. On tier_1 it also returns upgrade_path, a Norwegian pointer at the Altinn delegation flow (null on tier_2). It deliberately does NOT return the registry identity flat — no legal name, registered municipality, signaturrett (signing authority), prokura (power of procuration), role-holders, or a top-level company-wide status enum; call get_company_context for those identity fields. For deeper drill-down on individual obligations call get_company_obligations; for upcoming filing dates alone call get_company_deadlines. Input: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check. Failure modes the agent must handle: 404 not_found if the org_number is well-formed but unknown; SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; UPSTREAM_TIMEOUT if Brønnøysund is slow; VALIDATION_FAILED on a non-9-digit or mod-11-failing input. For the registry identity flat (legal name, signaturrett, prokura, role-holders) without a compliance verdict, use get_company_context instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Get the deterministic verification verdict for a Norwegian organisation by its 9-digit organisasjonsnummer (organisation number, the public ID issued by the Brønnøysund Register Centre / Enhetsregisteret). Use this for a fast go / no-go trust check before acting on a company's behalf. The verdict is reduced from the SAME Tier 1 Brønnøysund data as get_company_context (no separate fetch) and keys ONLY off two facts: whether the entity is active, and whether signing authority — signaturrett, power of procuration (prokura), or a sole-proprietor innehaver (who legally signs alone for an ENK) — is visible in the open role data. The `verification_status` values: `pass` (active AND a signing-authority holder is visible), `fail` (NOT active — a bankrupt (konkurs), under-liquidation (under avvikling), or dissolved / compulsorily-dissolved (oppløst / tvangsoppløst) company reports a non-active Brønnøysund status and therefore verdicts `fail`), and `unknown` (the registry status is indeterminate, OR the company is active but no signing authority is visible in the open role data — the register routinely omits signing arrangements, so the verdict never claims an absence it cannot see; a human should confirm who can bind the company). `warn` remains in the vocabulary for contract stability but is not emitted today. Alongside the verdict you get seven signals — is_active, not_bankrupt, not_under_dissolution, not_forcibly_dissolved, has_signing_authority_defined, has_filed_annual_accounts, mva_registered — each `true` / `false` / `null` (`null` means genuinely unknown from the open registries, NEVER a silent `false`). These distress / MVA / filing signals are surfaced for TRANSPARENCY only and NEVER change the verdict. You also get a Norwegian-bokmål `summary`, the `signing_authority_summary`, `last_accounts_year`, the registry identity echo (name, entity_type, nace_codes, municipality), the `data_sources` provenance tags, and a `verification_timestamp`. Deterministic: same org_number + same rulebook version → byte-identical verdict. Call get_company_context for the raw identity slice, get_company_summary for the obligation-and-deadline compliance layer, or get_company_obligations for per-obligation drill-down. Input: { org_number } as 9 digits passing the Brønnøysund MOD-11 control-digit check. Failure modes the agent must handle: 404 NOT_FOUND if the org_number is well-formed but unknown to Brønnøysund; SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; UPSTREAM_UNAVAILABLE if Brønnøysund is unreachable with no serviceable cache; VALIDATION_FAILED on a non-9-digit or mod-11-failing input. Required scope: `read:brreg`. The verdict only checks that signing authority is VISIBLE; the full signing-combination breakdown behind it (who signs, alone or jointly, with the Brønnøysund combination ids) is available from get_company_authority. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088). Cost: 50 øre (NOK 0.50) per call, debited from the API key's prepaid credit balance when credit enforcement is live. Current prices for every metered tool are discoverable without authentication via the get_pricing tool (or GET /api/v1/pricing for REST clients). A call with insufficient balance returns INSUFFICIENT_CREDITS with top_up_url, balance_ore and cost_ore for self-recovery; while enforcement is live, every successful metered call reports its remaining balance on metadata.credits.

Compute the universal Norwegian regulatory filing calendar — the set of deadlines that apply to every Norwegian business of the covered categories (MVA, A-melding, Årsregnskap), independent of any specific organisation. The response is the calendar for a single Europe/Oslo calendar year, one entry per (obligation, period) pair with: a stable obligation_id (e.g. `MVA_FILING_BIMONTHLY`, `A_MELDING_MONTHLY`, `ARSREGNSKAP_FILING`); the due_date as an ISO 8601 timestamp in Europe/Oslo (DST-aware — CET ↔ CEST transitions never shift due dates by a calendar day); the legal_reference citation pinning the deadline to lovdata.no; a recurring boolean; and a business_day_adjusted boolean. Choose this tool when an agent needs the universal calendar (questions like 'when is the next MVA filing deadline' that don't depend on a specific org_number) — it requires no organisasjonsnummer and no scope check beyond rulebook read access. Input: optional `year` (Europe/Oslo calendar year, integer between 2020 and 2100; defaults to the current Oslo year at the endpoint when omitted — a request at 23:30 UTC on 31 Dec is already 00:30 of the next year in Oslo during CET, and the route's default uses the Oslo wall-clock not UTC). Determinism (Rule 9): same input + same rulebook_version produces a byte-identical calendar. Failure modes: SCOPE_INSUFFICIENT if the API key is not scoped read:rulebook; VALIDATION_FAILED on year shape (non-integer, outside 2020–2100; the 2020 lower bound matches the underlying /v1/public/deadlines route's MIN_YEAR — older years aren't in the Rulebook's coverage window). Required scope: `read:rulebook`. For a specific company's filing calendar rather than the universal one, use get_company_deadlines instead.

Retrieve the universal obligation set for a Norwegian entity type. Returns every regulatory obligation that applies by virtue of an entity BEING that organisational form, BEFORE per-company Tier-2 data (employee count, MVA registration, turnover) is layered on. Use this tool when an agent wants to answer 'what does an AS owe?' or 'what are the baseline filings for an Enkeltpersonforetak?' without naming a specific company. Each obligation in the response carries a tier_2_required boolean — true means the rule engine needs commercial data to know whether the obligation actually applies to a SPECIFIC company (e.g. MVA / VAT registration only applies above the NOK 50,000 turnover threshold), false means the obligation applies unconditionally to every entity of that type. Common Norwegian regulatory concepts surfaced in the response include MVA / VAT (Merverdiavgift, Norwegian value-added tax), A-melding (the monthly employer payroll report consolidating tax + payroll-tax + pension data), Aksjonærregisteret (shareholder register filing), and Årsregnskap (annual accounts). Input: { entity_type } from the closed enum AS (aksjeselskap) / ENK (enkeltpersonforetak) / ANS (ansvarlig selskap) / DA (delt ansvar) / NUF (norskregistrert utenlandsk foretak). For per-company evaluation that DOES layer on commercial data, call get_company_obligations. Failure modes the agent must handle: VALIDATION_FAILED on an unknown entity_type (the enum is closed; there is no 'OTHER' fallback); SCOPE_INSUFFICIENT if the API key is not scoped read:rulebook; UPSTREAM_TIMEOUT on rulebook latency. For a specific company's evaluated obligations rather than the entity-type template, use get_company_obligations instead.

Resolve every Norwegian regulatory action a person is currently authorised to perform on behalf of a specific organisation. The lookup combines the actor's Altinn role assignments (DAGL — Daglig leder / managing director, LEDE — Styreleder / board chair, MEDL — Styremedlem / board member, NESTL — Nestleder / vice chair, INNH — Innehaver / sole proprietor, REGN — Regnskapsfører / accountant, REVI — Revisor / auditor) with a conservative role-to-action map maintained in `src/lib/altinn/role-action-map.ts`. The response returns the raw Altinn role list AND the derived action tokens an agent may safely pass to /v1/actions/execute downstream (dry-run them first with the validate_action tool), with a per-action `legal_reference` citation pinned to lovdata.no (all 10 entries verified 2026-05-16 — aksjeloven, skatteforvaltningsloven, regnskapsførerloven, revisorloven). Inputs are an 11-digit Norwegian fødselsnummer or D-nummer (which is HMAC-SHA-256 hashed via RECEIPT_HMAC_SECRET before any storage; the raw value is NEVER persisted, NEVER logged, and NEVER returned in the response — the response echoes only `actor.fnr_hmac`) plus the 9-digit Norwegian organisasjonsnummer of the represented entity. Results are cached for up to 1 hour in `resolved_permissions` so repeat lookups within the cache window do not re-hit Altinn; `metadata.cached === true` indicates a cache hit. Required scope: `read:altinn`. PR-MCP-02b: when ALTINN_MODE=sandbox, returns deterministic fixture payloads for OEM evaluation; metadata.data_sources tags as 'altinn-sandbox' and _meta.is_sandbox=true. For your own consumer's delegation snapshot on the org, use check_authorization instead. For the company-level statutory signing authority — who can sign, with no actor input — use get_company_authority.

Use this to discover the Altinn 3 equivalent of an Altinn 2 service or role code. The 19 June 2026 Altinn 2 deprecation deadline has passed, so this now serves remediation for any integration still on Altinn 2 — not pre-deadline planning. Pass an Altinn 2 code in { altinn2_code } (alphanumeric, 1–10 characters, e.g. A0208) to resolve a single mapping, or omit it to retrieve the entire migration map. Every response also carries the deprecation status computed in Europe/Oslo — `deprecation_deadline` (the absolute 23:59:59 Oslo instant on 19 June 2026), `days_remaining` (whole Oslo calendar days, floored at 0 once the deadline passes — 0 now that it has, never negative), and `deadline_passed` (now `true`) — so an agent can sequence its migration work without doing the timezone math itself. Each map entry ships a `verified` flag: `true` means the mapping has been cross-checked against DigDir's authoritative documentation, `false` means it is a convenience reference only — gate any production migration action on `verified === true` and treat unverified entries as hints, not instructions. The underlying data is a deterministic static map (DigDir-sourced); no government system is contacted at call time, so the answer is stable and cache-friendly. Input: { altinn2_code? }. Failure modes the agent must handle: 404 not_found when a supplied code is not in the map (omit the code to see every known entry); VALIDATION_FAILED (INVALID_CODE) on a non-alphanumeric or over-length code. This tool has no sandbox mirror — under the sandbox bearer it returns SANDBOX_TOOL_UNAVAILABLE.

Return the authorisation snapshot for the calling consumer's delegation on a Norwegian organisation. The response carries: the current `status` enum (`full` / `partial` / `none`); the `missing_scopes` array (Altinn / Maskinporten scope tokens the delegation lacks — empty when status=`full`); the `granted_scopes` array (the scope tokens the delegation already covers); and the `delegation_chain` (ordered list of System-User and consumer-id breadcrumbs the auth gateway walked to derive the verdict). Agents that need to check whether a SPECIFIC regulatory action (submit_mva, file_a_melding, etc.) is permitted should fetch the snapshot via this tool and compare `granted_scopes` to the scopes their target action requires — the rulebook's action→scope mapping is in the openapi.json `x-action-scopes` extension. The evaluation always runs against the calling consumer — there is no per-action and no per-actor input at v1. (The PR-070-tools brief's proposed `action` and `actor_national_id` parameters were dropped to match the route exactly. The underlying /v1/auth/permissions/{org} route does not parse either today; both will land in future PRs once the route adds the parameters AND a canonical fnr validator + shared hashFnr helper extract from PR-MCP-02's inline implementation per SA-001 §3.) Failure modes: SCOPE_INSUFFICIENT if the API key is not scoped read:altinn; VALIDATION_FAILED on shape or mod-11. The underlying endpoint is always a 200 — when no delegation exists for the (consumer, org) pair the verdict is `status: "none"` with the missing scopes enumerated, NOT a 404. Required scope: `read:altinn`. For which actions a SPECIFIC person may perform for the org, use list_acting_capacity instead. This tool reports the CONSUMER-level snapshot — the delegation attached to the calling consumer's API key — and the preflight delegation check on /v1/actions/execute (dry-run it via the validate_action tool) enforces the same consumer-scoped live-delegation rule this verdict is computed from. For the per-agent-principal breakdown of the systembruker delegations brokered through Apier's Fullmakt Rails, use check_fullmakt; for the company's statutory signing authority as recorded in the register, use get_company_authority.

Use this to read Apier's cross-source change archive — detected created / updated / deleted events across the upstreams Apier polls: Brønnøysund ingestion plus the multi-source pollers for Altinn schemas, DigDir policies, and Norges Bank rates. It answers "what changed, where, and when?" so an agent can drive an incremental sync instead of re-fetching whole entities. NOT every row is a real-world change: each row carries a derived `observation_kind` — first_observation (the archive's first sighting of a field/entity, i.e. Apier's cache warming up) vs value_change (a genuine observed transition). Filter by { source } (brreg / altinn / digdir / norges_bank …), { entity_type }, { entity_id } (e.g. a specific org number), { change_type } (created / updated / deleted), and a { from }–{ to } detected_at date range (ISO 8601 with a timezone offset — bare `Z` or `+02:00`, never a bare local time; `from` must be ≤ `to`). Queries WITHOUT { entity_id } return non-personal rows only — role-holder field rows (board_members / signaturrett / prokura / innehaver) AND whole-entity company created/deleted rows (their full snapshots embed role-holder arrays) are withheld — intentionally, not an ingestion gap. The org-scoped form with { entity_id } returns everything, and the response says so via `personal_fields_withheld: true`. Results are keyset-paginated newest-first: pass { limit } (1–500, default 50) and carry the response's `next_cursor` back into { cursor } verbatim for the next page — cursors are HMAC-signed, so constructing or editing one is rejected as CURSOR_INVALID. The public projection strips the internal correlation_id but preserves `source_snapshot_id` (a consumer-facing receipt join). Input: { source?, entity_type?, entity_id?, change_type?, from?, to?, limit?, cursor? }. Failure modes the agent must handle: SCOPE_INSUFFICIENT if the key is not scoped read:changes; VALIDATION_FAILED on a malformed date, an out-of-range limit, or from > to; CURSOR_INVALID if the cursor was tampered or expired (start over without a cursor). This tool has no sandbox mirror — under the sandbox bearer it returns SANDBOX_TOOL_UNAVAILABLE; call it with a real read:changes key.

Resolve a Norwegian company NAME to its 9-digit organisasjonsnummer (organisation number). Use this as your FIRST call whenever you have a company's name but NOT its org_number — every other company tool (get_company_summary, get_company_context, get_company_obligations, get_company_deadlines) requires the 9-digit number up front, so guessing a MOD-11-valid number risks hitting the wrong company. This tool searches Brønnøysund's public Enhetsregisteret (Central Register of Legal Entities) by name and returns a deliberately token-efficient candidate list: up to ten matches, five fields each — name, org_number, org_form (AS / ENK / NUF …), municipality, and registry status (active / bankrupt / liquidating / forced_liquidation / deleted) — never the full registry payload. Follow-up pattern: read the candidates, pick the org_number of the right company (use org_form, municipality, and status to disambiguate — skip a deleted or bankrupt match unless you meant it), then call get_company_summary or get_company_context with that org_number. Input: { name } as 2–100 characters (trimmed; æ/ø/å supported). Guidance: if the search returns NOT_FOUND, broaden the name — use fewer or more distinctive words and drop the legal form (search `Nordic Widgets`, not `Nordic Widgets AS`); if several candidates look alike, prefer the active one in the expected municipality. Failure modes the agent must handle: VALIDATION_FAILED on a name shorter than 2 or longer than 100 characters; NOT_FOUND when nothing matches (broaden and retry, do not loop on the same name); SCOPE_INSUFFICIENT if the API key is not scoped read:brreg; UPSTREAM_TIMEOUT or UPSTREAM_UNAVAILABLE if Brønnøysund is slow or unreachable (retry after a short backoff).

Call this BEFORE a batch of metered calls to confirm the calling key's prepaid credit balance covers it, and AFTER a 402 INSUFFICIENT_CREDITS + human top-up to verify the funds landed before retrying. Requires the caller's own Bearer API key; the balance returned is ALWAYS the authenticated key's own — the tool takes no parameters and the underlying route ignores any input, so reading another key's balance is structurally impossible. Returns api_key_id (the key's non-secret UUID, the same id audit_log rows carry — never the key material), balance_ore (remaining prepaid balance in whole øre; 1 øre = NOK 0.01, always an integer, never a float), currency (always NOK), updated_at (timestamp of the last balance movement, null when the key has never been topped up — which reads as balance 0), and top_up_url (byte-identical to the 402 body's top_up_url — hand it to a human to fund the key; agents cannot pay directly). To compute affordability, multiply the per-call cost_ore from get_pricing by the planned call count and compare against balance_ore; the low-balance warning factor is also discoverable via get_pricing. This read is free (unmetered) and has zero side effects. Failure modes the agent must handle: 401 when no valid API key is presented (this tool is NOT keyless — use get_pricing for keyless price discovery); SCOPE_INSUFFICIENT when the key's scopes are narrower than read:credits and lack the read:* wildcard — the MCP layer rejects it, but that same key can still read its balance over the scope-exempt REST route GET /api/v1/account/credits/balance, so a 402 recovery is never stuck on a too-narrow key; CREDIT_BALANCE_UNAVAILABLE (503, retryable) when the credit store cannot be read — a money read is never fabricated, so retry shortly instead of assuming a number. Not available under a sandbox bearer (the sandbox sentinel holds no balance) — it returns SANDBOX_TOOL_UNAVAILABLE there.

Fetch the most recent Norges Bank (Norway's central bank, Norges Bank in Norwegian — the official issuer of the krone) exchange-rate reference for a currency against NOK. Norges Bank publishes the daily NOK reference rate at ~16:00 Oslo time and Norwegian tax + accounting authorities (Skatteetaten / Norwegian Tax Administration; Regnskapsloven / Accounting Act) accept it as the canonical conversion benchmark for obligations denominated in foreign currency — including annual accounts (Årsregnskap), MVA / VAT (Merverdiavgift) filings on cross-border transactions, and dividend reporting. Use this tool whenever an agent needs an authoritative NOK rate for a regulatory calculation. The response includes the rate value, the date the rate is valid for (Norges Bank publishes weekday rates only; weekends + Norwegian public holidays return the prior business day's rate), and the source attribution so the agent can cite it back to a user. This is one of the few tools that does NOT depend on Norwegian-company input; it is the currency-of-record lookup. Input: { base, quote, date? } — base and quote are ISO 4217 three-letter currency codes (case-insensitive, exactly 3 letters), and rates are NOK-ANCHORED: exactly one of base/quote MUST be 'NOK', the other side any currency Norges Bank publishes. A pair without a NOK side (e.g. EUR/USD) is rejected client-side as UNSUPPORTED_CURRENCY_PAIR before any request is sent — fetch both NOK legs and derive the cross rate yourself if you need one. date is an optional ISO 8601 day (YYYY-MM-DD); omit it for the latest published rate. Failure modes the agent must handle: VALIDATION_FAILED on a non-ISO-4217 input; UNSUPPORTED_CURRENCY_PAIR when neither or both sides are NOK; INVALID_DATE on a malformed or future date; UPSTREAM_TIMEOUT if Norges Bank is slow; NO_RATE_AVAILABLE (404) if Norges Bank does not publish the currency; SCOPE_INSUFFICIENT if the API key is not scoped read:norgesbank. For compliance obligations or filing deadlines rather than a currency rate, use get_company_summary instead.

Resolve a structured Apier compliance error code into a Norwegian-bokmål Explanation envelope sourced from the Apier Compliance Explainer (PR-049). The response carries a one-line summary, a 1–3 sentence why, an ordered list of fix_steps, an optional Apier / Altinn / Skatteetaten / Brønnøysund relevant documentation link, an optional Lovdata-style legal_basis citation when the error maps to a concrete regulatory provision, and an optional handover block (who / where / what / why) for errors a human must resolve (e.g. AUTH_INSUFFICIENT_ROLE, AUTH_NO_DELEGATION, SCOPE_MISSING). Errors agents can resolve themselves (VALIDATION_FAILED, RATE_LIMIT_EXCEEDED, NOT_FOUND, IDEMPOTENCY_KEY_MISMATCH, IDEMPOTENCY_IN_PROGRESS, UPSTREAM_UNAVAILABLE) ship `handover: null`. The full catalogue of supported error codes mirrors `EXPLAINER_ERROR_CODES` (40 codes today across auth, validation, scope, upstream, idempotency, action-execute, government, and reliability domains); pass any code an Apier endpoint returned in an error envelope. The optional `context` object carries placeholder values (org_number, role, scope, field, upstream_system) that the explainer interpolates into the bokmål text — missing values fall back to a Norwegian 'ukjent <noun>' rather than leaking placeholder syntax. Required scope: `read:rulebook`. For a company's live obligations rather than an error explanation, use get_company_obligations instead. No API key? Self-serve in the sandbox: authenticate tools/call with `Authorization: Bearer apier_sandbox_test_<suffix>` (ALWAYS append a unique random suffix, e.g. a fresh UUID, for session isolation) and this tool answers from deterministic synthetic fixtures with `_meta.is_sandbox: true` — use the reserved MOD-11-valid sandbox org numbers from GET /api/v1/sandbox/fixtures (e.g. 999660088).

Check your fullmakt state for a Norwegian company BEFORE acting on its behalf — the read leg of AGT-02 Fullmakt Rails and the natural follow-up to request_fullmakt. A fullmakt is a legally-grounded, scoped, revocable company→agent authority delegated through an Altinn systembruker; this tool tells you whether you actually hold one yet. Given a 9-digit customer org_number it returns, per agent principal of yours holding a live delegation there: the bound system_user_id, whether the delegation is `active` or still `pending` the company's signaturrett approval, the scopes it carries, and the scopes your tier's baseline still requires. `data.overall_status` is `full` (a principal is itself active AND holds an approved, scope-complete delegation — act now), `partial` (a delegation exists but something still blocks it: missing scopes, awaiting approval, or a suspended/revoked/not-yet-activated principal — `data.fix_steps` always names the specific blocker), or `none` (no principal of yours holds authority here). `none` is a VALID answer, NOT an error: a consumer with no principals, or none bound to this org, gets a 200 with an empty `data.principals` and Norwegian `data.fix_steps` pointing at request_fullmakt — never a 404. This reports the delegation state Apier RECORDED when it brokered the fullmakt; it is not a live Altinn PDP decision (no such call exists at v1), so the two can diverge if a delegation is revoked upstream without Apier observing it, and the expiry rule matches the execute enforcement path (a delegation execute would refuse is never reported here as authority). Input: { org_number } as plain 9 digits. Failure modes: SCOPE_INSUFFICIENT if the key is not scoped read:altinn; VALIDATION_FAILED on a non-9-digit input. Required scope: `read:altinn`. To BROKER a fullmakt use request_fullmakt; to withdraw one use revoke_fullmakt. This tool breaks the recorded delegation state down PER AGENT PRINCIPAL; the CONSUMER-level snapshot — the same consumer-scoped delegation state the preflight delegation check on /v1/actions/execute (dry-run it via the validate_action tool) enforces under a shared liveness rule — is reported by check_authorization.

Call this BEFORE metered work to check per-call cost and whether billing enforcement is live. Keyless: this is one of the few tools that executes WITHOUT an API key (it also works with one), so an agent can price a workflow before it holds any credential. Returns Apier's machine-readable price list: every credit-metered REST endpoint with its MCP tool name and cost in whole øre (1 øre = NOK 0.01 — every cost, balance, and top-up amount on this API is a whole-øre integer, never a float), the enforcement block (enforcement.live — whether credit metering is currently active; while false nothing is debited and a 402 is impossible, and the authoritative charging signal is always the metered response itself, never a previously fetched price list), the exact 402 INSUFFICIENT_CREDITS recovery-contract field list (retryable, fix_hint, docs_url, top_up_url, balance_ore, cost_ore), the top-up bounds (top_up.min_ore / top_up.max_ore) with the top_up_url a human uses to fund a key, the low-balance warning factor, and the how_to_pay_guide URL documenting the full agent payment loop. Prices are derived from the SAME pricing configuration the 402 meter debits — no parallel price table exists, so this surface cannot drift from enforcement, though a fetched list can go stale after a pricing deploy. Input: none — call with an empty arguments object {}. Failure modes the agent must handle: rate limiting (per-IP on keyless calls) and transient infrastructure errors; there is no auth failure mode because no credential is required. For the calling key's own remaining balance, use get_credit_balance (requires a Bearer API key) instead — this tool never returns balances or any authenticated state.

Call this to convert an owner-issued key-issuance token into your own API key — the headless onboarding step for an agent that holds no credential yet. Keyless: this tool executes WITHOUT an API key, because the one-time token you present IS the credential. Where tokens come from: a human account owner mints one in the Apier dashboard (Agent issuance tokens) and hands it to you out-of-band. There is deliberately NO tool to mint or revoke issuance tokens — minting and revocation are dashboard-only by design, so an agent can never self-issue authority; do not look for one. Redemption is strictly SINGLE-USE and atomic: on success (201) the token is consumed and the result carries {id, name, scopes, created_at, plaintext_key} — the plaintext_key is returned EXACTLY ONCE and is never retrievable again, so store it immediately and then authenticate every subsequent call with `Authorization: Bearer <plaintext_key>`. The issued key carries the default read:* scopes. Apier never persists the token or the key plaintext in any log. Failure modes: an expired, already-used, revoked, or unknown token yields ONE uniform failure with no reason detail (deliberately indistinguishable; the envelope's upstream_code is ISSUANCE_TOKEN_INVALID) — an identical retry fails identically, so ask the owner for a fresh token instead of retrying. MAX_KEYS_REACHED (409) means the account already holds 3 active keys; the token was NOT consumed — ask the owner to revoke a key, then retry with the SAME token. Redemption attempts are rate-limited (5 per hour per IP). After onboarding, use get_pricing (keyless) to price metered work and get_credit_balance (with your new key) to check the account's remaining balance.

Broker a fullmakt — a legally-grounded, scoped, revocable company→agent authority delegated through an Altinn systembruker (system user). Use this to turn an agent IDENTITY (an agent principal you created via PR-A1) into an ACTOR that may act on behalf of a specific Norwegian company. Given the agent principal, a 9-digit customer org_number, and the Altinn scopes to carry, the tool brokers a systembruker delegation, persists it, and binds the returned system_user_id onto the principal (write-once — a `pending` principal becomes `active`). Altinn returns a `delegation_url` the company's signing authority must approve before the delegation is usable, so a fresh delegation typically starts `pending`. The response `data` carries system_user_id, status, scopes, valid_until, delegation_url, the echoed label, an agent_principal snapshot, and a `warnings[]` array that is ALWAYS present (empty on the clean path): a non-empty array on a 201 means the delegation EXISTS upstream but a local follow-up write degraded — reconcile, never blind-retry. Retrying the IDENTICAL call is dedup-safe: the forward always sends a deterministic Idempotency-Key derived from the request, so an identical retry replays the stored response instead of brokering a duplicate delegation (change any argument and it is a new request). Inputs: { agent_principal_id (uuid, one of YOUR OWN principals), org_number (9 digits), scopes (non-empty string[]), validity_days? (1–3650), label? }. Failure modes: FULLMAKT_PRINCIPAL_NOT_FOUND (404 — wrong id or another consumer's principal; the two are deliberately indistinguishable), FULLMAKT_PRINCIPAL_NOT_ELIGIBLE (409 — a revoked/suspended principal cannot request), FULLMAKT_UPSTREAM_FAILED (502 — Altinn brokering failed; on the ack-unconfirmed variant do NOT blind-retry, reconcile in Altinn), SCOPE_INSUFFICIENT if the key is not scoped read:altinn, VALIDATION_FAILED on a malformed input. Required scope: `read:altinn` (the ACTIVE per-data-source Altinn scope — deliberately NOT the reserved delegate:* that keeps the raw system-user delegate route 403-gated). This tool is part of AGT-02 Fullmakt Rails; its read-side twin is check_fullmakt and its revocation leg is revoke_fullmakt. Mock-adapter-backed pending live partner validation; the response shape is identical in both modes.

Revoke a fullmakt — withdraw an agent's delegated authority for a Norwegian company and retire the agent principal. Part of AGT-02 Fullmakt Rails (the revocation leg; broker with request_fullmakt, inspect with check_fullmakt). A fullmakt is a legally-grounded, scoped, revocable company→agent authority delegated through an Altinn systembruker, and this is how you take it back. Given ONLY the agent_principal_id (the system_user_id and org_number are read server-side from the principal's write-once binding and the delegation row — a client cannot redirect the revoke at someone else's delegation), Apier revokes the delegation bound to that systembruker and flips the principal to terminal `revoked` (a revoked principal is never resurrected — create a new one to act again). Because the `delegations` table is append-only, revocation is revoke-by-insert: a `status='revoked'` marker row supersedes the original, and every Apier read + enforcement surface (permission state, fullmakt state, actions/execute) honours the marker immediately — LOCAL revocation is authoritative for Apier's own gating. Idempotent: revoking an already-revoked principal/delegation is a 200 no-op. `data.warnings` carries NAMED outcome tokens, each with its own meaning — `principal_revoke_failed` (the delegation IS revoked but the principal flip failed; re-inspect and retry), `delegation_not_found` (no live delegation existed behind the principal; the principal revocation still proceeded), `upstream_revoke_unconfirmed` (best-effort Altinn-side propagation returned no ack — expected while the upstream flow is pending live partner validation) — read the specific token rather than treating any non-empty array as a local failure. Input: { agent_principal_id (uuid), reason? (1–500 chars, audit-only) }. Failure modes: FULLMAKT_PRINCIPAL_NOT_FOUND (404); SCOPE_INSUFFICIENT if the key is not scoped read:altinn; VALIDATION_FAILED on a malformed input. Required scope: `read:altinn`. Supports Idempotency-Key on the underlying route.

Run the Apier dry-run validator against a proposed regulatory action without producing ANY upstream side effect — no Maskinporten call, no Altinn / Skatteetaten / NAV submission. The response is the structured verdict from `src/lib/actions/dry-run.ts` carrying: the five check slots (`company_exists`, `system_user_authorised`, `scopes_delegated`, `deadline_in_future`, `data_format_valid`) each with pass / fail / skipped status and a human-readable reason; the overall valid boolean; and the DRY_RUN_DISCLAIMER constant — a passing dry-run is NOT a guarantee of upstream success, only a strong-but-not-guaranteed signal that the local prerequisites are satisfied. The dry-run response also echoes `would_be_payload` — the exact upstream-shaped payload a live execute would submit — plus a `preview_notice`, so you can preview precisely what would be filed without submitting anything. Checks short-circuit deterministically: `scopes_delegated` is skipped when `system_user_authorised` fails (no delegation to inspect); each skipped check carries an explanation. Use this tool BEFORE calling the live execute path to catch missing delegations, expired scopes, deadline misses, and payload-shape errors with zero upstream cost. Inputs match the underlying /v1/actions/execute body schema exactly: { org_number, action_type, period, payload }. action_type is the closed enum `mva_melding` (VAT return) | `a_melding` (employer report). period encoding depends on action_type — for mva_melding accept `YYYY-T1..T6` (bimonthly), `YYYY-A` (annual), or `YYYY-MM` (monthly); for a_melding only `YYYY-MM`. payload is the upstream-shaped JSON for the action; the per-action discriminated Zod (in `src/lib/actions/payload-schemas.ts`) owns shape validation — this tool only caps size at 64 KiB UTF-8 bytes (PAYLOAD_TOO_LARGE on exceedance). Failure modes: SCOPE_INSUFFICIENT if the API key is not scoped read:actions; VALIDATION_FAILED on shape / mod-11 / action_type enum / period-regex / payload-size; the dry-run validator itself NEVER throws — every failed check is reported via valid=false plus the breakdown fields. Required scope: `read:actions` (matches the underlying /v1/actions/execute endpoint — dry-run shares the live-execute scope vocabulary). To actually file a (sandbox) VAT return rather than dry-run-validate, use submit_vat_return instead.