Recipes

Steps

1. 1

   Call GET /api/v1/public/deadlines?year=YYYY and iterate the returned mappings sorted ascending by deadline.

   public.deadlines → JSON envelope with data.year, data.deadlines[] (sorted ascending), and _meta.served_from='static'.

Agent instructions

1. Call GET /api/v1/public/deadlines?year=<YYYY> (no authentication required).
2. Parse the response body at data.deadlines — it is sorted ascending by deadline.
3. For each entry, note obligation_id, deadline (ISO 8601 with Europe/Oslo offset), and adjusted_from (null unless the legal deadline fell on a weekend or holiday).
4. If data.deadlines is empty, the year is valid but outside our coverage window (2020-2100) — surface VALIDATION_FAILED explanation to the user.

Failure modes to plan for

• invalid_year
• upstream_timeout

Steps

1. 1

   Call GET /api/v1/company/{org}/context with the consumer API key; branch on data.data_tier.

   company.context → JSON envelope with data.company (tier-1 fields), optional data.tier_2 block, data.data_tier, and _meta with served_from + stale markers.

Agent instructions

1. Ensure you hold a consumer API key in the Authorization: Bearer header.
2. Call GET /api/v1/company/<ORG_NUMBER>/context with ORG_NUMBER as a 9-digit Norwegian organisation number.
3. Branch on data.data_tier — 'tier_1' means public-only Brønnøysund fields; 'tier_2' means the delegation is active and commercial metrics are included.
4. Read _meta.served_from ('cache' vs 'live') and _meta.stale (true when a within-limit cached row was served as an upstream-down fallback).
5. On 404 org_not_found: surface the explanation.why text (Norwegian) to the user.
6. On 503 with _meta.stale=true: the data is still usable but older than 24 hours — tell the user freshness is degraded.

Failure modes to plan for

• org_not_found
• tier2_data_missing
• upstream_timeout
• auth_missing
• auth_invalid_key

Steps

1. 1

   Call GET /api/v1/tools/exchange-rate?currency=<ISO>&date=<YYYY-MM-DD>.

   tools.exchange_rate → JSON envelope with data.rate (number), data.date, data.requested_date, data.cached, and _meta.served_from (cache/live).

Agent instructions

1. Call GET /api/v1/tools/exchange-rate?currency=<ISO>&date=<YYYY-MM-DD> (no authentication).
2. CURRENCY must be a 3-letter ISO 4217 code Norges Bank tracks (EUR, USD, GBP, SEK, DKK, etc.).
3. DATE is optional — omit to get today-in-Oslo; future dates are rejected with 400 INVALID_DATE.
4. Compare data.date to data.requested_date. If they differ, the requested date fell on a weekend / holiday / pre-publication window and the rate is from the most recent prior business day.
5. On 404 NO_RATE_AVAILABLE: Norges Bank does not track this currency — try EUR or USD as a fallback.
6. On 502 UPSTREAM_UNAVAILABLE: transient; retry in a few minutes.

Failure modes to plan for

• invalid_currency
• invalid_date
• no_rate_available
• upstream_unavailable

Steps

1. 1

   Call GET /api/v1/tools/altinn-migration?altinn2_code=<CODE>; inspect `verified` before trusting the mapping for production automation.

   tools.altinn_migration → JSON envelope with data.entry (MigrationEntry), data.deprecation_deadline, data.days_remaining, data.deadline_passed, and _meta.served_from='static'.

Agent instructions

1. Call GET /api/v1/tools/altinn-migration?altinn2_code=<CODE> (no authentication). CODE is alphanumeric, max 10 characters (e.g. A0208).
2. Read data.entry.verified — if false, the mapping is a best-effort reference and MUST NOT drive production migration without human review.
3. Read data.entry.altinn3_code — null means DigDir has not yet published the Altinn 3 equivalent.
4. The 19 June 2026 Altinn 2 cliff has passed, so data.deadline_passed is true and data.days_remaining is 0 — tell the user the cutoff is already behind them rather than presenting a countdown.
5. On 404 NOT_FOUND: the code is not in our static map — point the user at docs.altinn.studio.

Failure modes to plan for

• invalid_code
• not_found
• unverified_entry

Steps

1. 1

   Call GET /api/v1/public/obligations?entity_type=<AS|ENK|ANS|DA|NUF>. Use the `tier_2_required` flag to decide whether to plan a delegation flow next.

   public.obligations → JSON envelope with data.entity_type, data.obligations[] (may be empty for ANS/DA/NUF), data.notes[], and _meta.served_from='static'.

Agent instructions

1. Call GET /api/v1/public/obligations?entity_type=<AS|ENK|ANS|DA|NUF> (no authentication).
2. Iterate data.obligations — an array of obligation templates.
3. For each obligation with tier_2_required === true, plan ahead: the caller will need an Altinn delegation (workflow.request-delegation, not yet shipped) before the paid /v1/company/{org}/obligations endpoint can evaluate it per-company.
4. Obligations with required='never' are DELIBERATELY included so agents see they were considered and ruled out (e.g. revisor-plikt for ENK).
5. ANS, DA, and NUF currently return an empty obligations array with a notes entry — templates are not yet published.

Failure modes to plan for

• invalid_entity_type
• empty_template_set

Steps

1. 1

   Call GET /api/v1/company/{org}/audit with the consumer API key (read:audit scope). Iterate the page; if pagination.has_more, repeat with ?before=pagination.next_before&before_id=pagination.next_before_id.

   company.audit → JSON envelope with data.data[] (AuditLogEntry array), data.pagination.has_more, data.pagination.next_before (string or absent), data.pagination.next_before_id (string or absent), and _meta with response_timestamp + response_hash.

Agent instructions

1. Ensure your API key has the read:audit scope (operator-issued via /v1/admin/keys).
2. Call GET /api/v1/company/<ORG_NUMBER>/audit?since=<ISO_FROM>&until=<ISO_TO>&limit=200 with the consumer API key.
3. Iterate data.data — each row is an AuditLogEntry. correlation_id joins to provenance_log / evaluation_snapshots / compliance_state_events from the same originating request.
4. If pagination.has_more is true, pass pagination.next_before back as ?before=<value> AND pagination.next_before_id back as ?before_id=<value> to fetch the next page. Both are required together — the cursor is a tuple, not two independent fields.
5. To narrow further: ?action=<closed-enum> or ?initiated_by=<human|agent|cron|system|unknown>. Action enum is the closed list at src/lib/audit/types.ts AUDIT_ACTIONS — anything outside the list is rejected at 400.
6. details.* values matching token / secret / password / bearer / authorization / jwt / api_key / private_key / credential / client_secret / refresh_token are auto-redacted to the literal string [REDACTED] at BOTH write and read time.
7. An empty array (data.data === []) for a valid (consumer, org) pair is returned as 200, not 404 — that prevents existence-leak across consumers.

Failure modes to plan for

• auth_missing
• scope_insufficient
• validation_failed
• audit_query_failed

Steps

1. 1

   Call GET /api/v1/changes?source=brreg&entity_id={org_number}&from={iso_date} with the consumer API key (read:changes scope). Iterate the page; if pagination.has_more, repeat with ?cursor=pagination.next_cursor.

   changes.query → JSON envelope with data.data[] (PublicChangeRow array), data.pagination.has_more, data.pagination.next_cursor (string or null), and _meta with response_timestamp + response_hash.

Agent instructions

1. Ensure your API key has the read:changes scope (operator-issued via /v1/admin/keys).
2. Call GET /api/v1/changes with filters: source (brreg|altinn|digdir|norges_bank|nav|skatteetaten), entity_id, change_type (created|updated|deleted), from + to (RFC 3339).
3. Iterate data.data — each row is a created/updated/deleted event with before_value/after_value JSONB blobs, an RFC 6902 diff array, and a derived observation_kind (treat first_observation rows as the archive's first sighting of that field/entity, not a real-world change).
4. If pagination.has_more is true, pass pagination.next_cursor back as ?cursor=<value> to fetch the next page. Do NOT modify the cursor — it's HMAC-signed and tampered cursors return 400 CURSOR_INVALID.
5. correlation_id is intentionally not exposed; use source_snapshot_id to join back to provenance receipts.

Failure modes to plan for

• auth_missing
• scope_insufficient
• cursor_invalid
• validation_failed

Steps

1. 1

   Call POST /api/v1/actions/execute?dry_run=true with { org_number, action_type, period, payload }. The endpoint performs all five preflight checks, writes one evaluation_snapshots row + one audit_log row, and returns 200 with the structured DryRunOutcome.

   actions.execute_dry_run → JSON envelope with data.dry_run === true, data.outcome.all_passed (boolean), data.outcome.checks (5 entries, ordered), data.outcome.disclaimer (fixed string), and _meta with response_timestamp + response_hash.

Agent instructions

1. Ensure your API key has the read:actions scope (operator-issued via /v1/admin/keys).
2. Build the request body: { org_number (9 digits), action_type ("mva_melding" | "a_melding"), period (YYYY-Tn|YYYY-A|YYYY-MM for mva; YYYY-MM for a-melding), payload (per-action shape — see OpenAPI components MvaMeldingPayload / AMeldingPayload). Decimals as STRINGS, not numbers.
3. POST /api/v1/actions/execute?dry_run=true with the body. Note ?dry_run=true is what makes this call validate-only — omitting it (or sending any value other than "true") routes to the live-execute path for supported action types instead of a no-op (still mock-routed by default when ALTINN_MODE=mock, not necessarily a real government submission); see /docs/capability-status for the current live/gated status of each action type before relying on that path.
4. Read response data.outcome.all_passed. If true, the dry-run found no blockers; live submission uses the live-execute flow (Idempotency-Key + approval token) and is enabled per-operator once Maskinporten/Altinn grants are active.
5. If false, iterate data.outcome.checks: each row has check (name), passed (bool), error_code (string|null), explanation_summary (string|null). Fix the inputs against the failed checks and retry — the engine never short-circuits, so one call lists every problem.
6. Treat the disclaimer field as a hard contract: a passing dry-run is NOT a guarantee. Government systems may reject otherwise-valid submissions for reasons outside Apier's view.

Failure modes to plan for

• auth_missing
• scope_insufficient
• validation_failed
• execute_not_available
• payload_too_large

Steps

1. 1

   Call GET /api/v1/company/{org}/verify (optionally ?certificate=true) and gate the rest of the chain on data.verification_status — stop on 'fail'.

   company.verify → JSON envelope with data.verification_status (pass/warn/fail/unknown), data.signals (seven tri-state booleans), and _meta with response_hash; with ?certificate=true the data block is a detached-JWS certificate wrapping the same verdict.

2. 2

   Call GET /api/v1/company/{org}/authority (optionally ?certificate=true) to resolve who can legally commit the company before any binding onboarding step.

   company.authority → JSON envelope with data.classification (sole/joint/by_role/prokura_only/no_authority/unknown), data.signaturrett_holders, data.prokura_holders, and _meta with response_hash.

3. 3

   Call GET /api/v1/company/{org}/accounts for the filed annual-accounts snapshot — treat has_filed_annual_accounts null as unknown, never as 'not filed'.

   company.accounts → JSON envelope with data.has_filed_annual_accounts (tri-state), data.last_accounts_year, data.key_figures (with explicit currency), and _meta with response_hash.

4. 4

   Call GET /api/v1/company/{org}/obligations to evaluate every Rulebook obligation for the company — insufficient_data verdicts point at the Tier-2 delegation path.

   company.obligations → JSON envelope with data.obligations[] (one EvaluationResult per rule: applicable/not_applicable/insufficient_data), data.data_tier, and _meta with response_hash.

5. 5

   Call GET /api/v1/company/{org}/deadlines to expand the applicable obligations into the concrete weekend/holiday-adjusted deadline calendar.

   company.deadlines → JSON envelope with data.deadlines[] (DeadlineEntry rows, due_at ascending, Europe/Oslo offsets), data.data_tier, and _meta with response_hash.

Agent instructions

1. Ensure you hold a consumer API key (Authorization: Bearer) with the read:brreg scope; ORG_NUMBER below is a 9-digit Norwegian organisation number.
2. Call GET /api/v1/company/<ORG_NUMBER>/verify. Branch on data.verification_status: 'fail' means the company is not active — stop onboarding and surface data.summary; 'warn' means active but no signing authority is defined — continue, but flag it; 'pass' continues. Append ?certificate=true when you want the verdict wrapped in an offline-verifiable detached-JWS certificate.
3. Call GET /api/v1/company/<ORG_NUMBER>/authority. Read data.classification (sole / joint / by_role / prokura_only / no_authority / unknown) and data.signaturrett_holders + data.prokura_holders to know who must approve binding steps. ?certificate=true is available here too.
4. Call GET /api/v1/company/<ORG_NUMBER>/accounts. data.has_filed_annual_accounts is tri-state (true / false / null=unknown — never coerce null to false); data.key_figures carries the latest filed year's figures with an explicit currency.
5. Call GET /api/v1/company/<ORG_NUMBER>/obligations. Each EvaluationResult is applicable / not_applicable / insufficient_data — treat insufficient_data as 'needs a Tier-2 delegation', not as a no.
6. Call GET /api/v1/company/<ORG_NUMBER>/deadlines. Entries are already weekend/holiday-adjusted with Europe/Oslo offsets; sort order is due_at ascending.
7. Assemble the onboarding summary from the five data blocks. Keep each response's _meta.response_hash (and the step-2/3 certificates if requested) as the provenance trail for the decision.

Failure modes to plan for

• org_not_found
• auth_missing
• auth_invalid_key
• scope_insufficient
• upstream_timeout