Archigov · docs
  1. Docs
  2. Reference

HTTP API Reference

The JSON API behind the Archigov UI — authentication, conventions, errors, and every endpoint grouped by domain.

The web UI is a client of this API and has no private endpoints: anything you can do in the product you can automate, with the same rights.

#Conventions

  • Base path: /api. Requests and responses are JSON unless noted (CSV and XML exports).
  • Identifiers: UUIDs in paths; human codes (ADR-0001, REV-0001, STD-001, SES-0001) in responses. Many detail endpoints accept either.
  • Timestamps: ISO 8601, UTC.
  • Every mutation is audited under the calling user.

#Authentication

ModeHow to call
AUTH_MODE=entraSign in through the browser flow (/api/auth/login); the API uses the session cookie. Unauthenticated calls get 401 {"error":"sign_in_required","login_url":"…"}
AUTH_MODE=localThe session cookie (from POST /api/auth/local) or, without one, an x-user: <user id> header. An unknown user is treated as a platform admin with no governance rights
Shell
# local mode: act as the demo decision maker
curl -s http://localhost:8080/api/me/work -H 'x-user: m.hughes'

Caution

The x-user header is honoured only in local mode, which is a trusted-network convenience. Under Entra it is ignored.

#Errors

StatusMeaning
400Invalid input; error explains what
401Not signed in (Entra mode)
403The capability is missing ({"error","capability"}) or a board check refused ({"error","reason"})
404Unknown item
409A state conflict, e.g. accepting a decision under review, an AI feature that is disabled, changing frozen positions
502An upstream provider (Azure, DevOps, AI) failed; the message never contains a secret

#Endpoints

#System

MethodPathPurpose
GET/healthLiveness; no auth
GET/overviewDashboard figures, pipeline, and the caller's awaiting count
GET/me/workThe caller's work queue: positions, declare, resolve, sessions, conditions, circulations, assessments, resubmit, changed, no_decision
GET/search?q=Search across items
GET, POST/settingsRead or change settings (POST: platform admin)
POST/backupBack up now (platform admin)
GET/ai/featuresWhich AI features are enabled
POST/ai/testProvider round-trip test (platform admin)
GET/auditAudit rows with item codes; filters and facets
GET/audit/verifyRe-verify the hash chain

#Authentication and Users

MethodPathPurpose
GET/auth/meThe caller, roles, seats and capabilities
GET/auth/login, /auth/callbackEntra sign-in flow
POST/auth/localSign in as a user (local mode)
POST/auth/logoutSign out
GET, POST/auth/rolesRole assignments (POST: platform admin)
GET, POST/users; GET, PUT /users/:idUsers, system roles and the admin flag (writes: platform admin)

#Model

MethodPathPurpose
GET/applications, /applications/:idApplications with resources, provenance, verification
GET/applications/:id/viewsGenerated ArchiMate views as JSON and XML, with annotations
POST/applications/:id/verify-allVerify an application and its members
POST/applications/:id/annotations; PUT, DELETE /annotations/:idNotes on a view or element (author-only edit)
GET/shared-servicesShared services
POST/elements/:id/verifyVerify an element
POST/resources/:id/moveMove a resource to another application

#Governance Catalogue

MethodPathPurpose
GET/artefacts, /artefacts/:id, /artefacts/kindsList, read, kinds
POST/artefacts; PUT /artefacts/:idCreate or edit a draft
POST/artefacts/:id/submit, /retire, /verifyLifecycle actions
GET/artefacts/:id/dry-runEvaluate a draft's rule without storing anything
POST/artefacts/draft-rule, /artefacts/suggest-referencesAI drafting (409 when off)
GET/standards/packs; POST /standards/packs/:id/importPacks
POST/import/artefacts, /import/artefacts/csvImport artefacts as drafts
—/standards/*Aliases of /artefacts/* for older clients

#Decisions

MethodPathPurpose
GET/decisions, /decisions/:idList and read, with links and the review in flight
POST/decisions; PUT /decisions/:idCreate and edit (authors)
POST/decisions/:id/statusChange status (chair); 409 while under review for accepted/rejected
POST/decisions/:id/verifyVerify
POST/decisions/review-draftAI decision review (409 when off)
POST/decisions/:id/assessments, /decisions/:id/assessments/provideEvidence on a draft decision

#Reviews, Positions and Assessments

MethodPathPurpose
GET/reviews, /reviews/:idList (filters by stage, type, board, session) and read, with progress and can
POST/reviewsSubmit a review
POST/reviews/:id/pre-review, /comment, /resubmitPre-review, comment, resubmit
PUT/reviews/:id/areasCorrect the touched areas
POST/reviews/:id/positionsRecord a position: {area?, areas?, position, text?}
POST/reviews/:id/approvalsCount-mode alias: approve / request changes
POST/positions/:id/resolveChair resolves a conditional
POST/reviews/:id/dependenciesLink or create a dependent decision
POST/reviews/:id/decideDeclare an outcome: {outcome, rationale?, conditions?, circulation_due?, board_id?}
POST/conditions/:id/closeMark a condition met
POST/review-events/:id/verifyVerify an AI or rules pre-review
GET/assessments/typesTypes and their templates
POST/reviews/:id/assessmentsRequest an assessment (board seat)
POST/reviews/:id/assessments/provide; PUT /assessments/:id/providedProvide / update (submitter)
PUT/assessments/:idReassign or move the due date
POST/assessments/:id/result, /assessments/:id/waiveRecord (assignee) or waive (chair)
POST/reviews/:id/assessments/draftAI summary draft (409 when off)

#Boards and Sessions

MethodPathPurpose
GET/boards, /boards/:id, /boards/routeBoards, detail, and which board a review would route to
POST/boards; PUT, DELETE /boards/:idCreate (platform admin), edit, remove
POST, PUT, DELETE/boards/:id/members…, /routing…, /policies…Seats and areas, routing, approval policies
GET, POST/boards/:id/sessionsList or plan sessions
GET/sessions, /sessions/:id, /sessions/:id/minutesSessions, detail with agenda and quorum, minutes
POST/sessions/:id/open, /closeOpen and close (chair)
POST, PUT/sessions/:id/agenda/refresh, /sessions/:id/agendaRefresh or reorder the agenda
POST/sessions/:id/attendance, /delegations; DELETE /delegations/:didAttendance and delegation
POST/sessions/:id/items/:reviewId/call, /nominate, /pull, /defer, /declareRun an item
POST/sessions/:id/consent/declareDeclare the consent agenda
PUT/sessions/:id/notes; POST /sessions/:id/draft-notesNotes; AI draft

#Conformance and Evidence

MethodPathPurpose
GET/conformanceFindings, exceptions, conditions, runs
POST/evaluateRun an evaluation now
POST/findings/:id/resolveClose a finding with a reason (chair)
POST/exceptionsGrant an exception (chair)
GET/evidence, /evidence/summaryImported evidence
POST/evidence/importImport evidence (platform admin)
POST/evidence/suggest-mappingAI mapping suggestions (platform admin)
GET/evidence-pack, /evidence-pack/verify?hash=Export and verify the signed pack

#Sources and Planned Change

MethodPathPurpose
GET/sourcesSources and their last runs
POST/sources/azure/test, /sources/azure/sync, /sources/defender/sync, /sources/policy/syncAzure collection
POST/sources/ado/test, /sources/ado/syncAzure DevOps backfill
POST/sources/demo/load, /resync, /perturbDemo tools
POST/hooks/adoService hook receiver (own secret)
POST/import/csv, /import/archimate; GET /import/templates/csvModel imports
GET, POST/work-items; PUT /work-items/:idPlanned changes; manual ones by authors
POST/work-items/:id/link, /acknowledge-change, /draft-decisionLink, acknowledge, draft a decision

#Exports

MethodPathPurpose
GET/exports/oscal[?application=]OSCAL assessment results
GET/exports/dora-roi.csvDORA register of information (simplified)
GET/exports/archimate[?application=]ArchiMate Open Exchange XML
GET/runs/:idOne evaluation or sync run

See Exports for formats.