Skip to Content
ArchitectureReasoning serviceHTTP endpoints
Architecture · Reasoning

Every route, read from the code.

This is the full list of routes registered with @app in apps/reasoning/src/conway_reasoning/serve.py. The service is called by the web application, not directly by people. In the customer profileDeployment profileA setting that selects customer or development behaviour. Customer mode refuses development credentials and uses the signed-in session as the identity. every route except /health and /ready needs the x-conway-service-token header (see the overview). Most routes take viewer and org: query parameters for reads, JSONJSONJavaScript Object Notation: a text format for data, using named fields, lists and values. Configuration files and service messages use it. body fields for writes. The actor_map table links the viewer account to its role and organisation. Unknown viewers are refused.

The routes are grouped by what they do. Where a handler delegates to a module, the module is named so that you can follow it from the matching architecture page.

Remits and agent evidence form the largest group. The sections below list every route.

Health and readiness

MethodPathPurpose
GET/healthLiveness plus reachability of the database and the meshMeshA set of connected Mycelium services that exchange updates and keep the NovusLens log. gatewayGatewayA service that accepts requests and passes them into another system. The Mycelium gateway gives NovusLens access to the mesh.. 200 when both answer, 503 with the problems listed when either does not.
GET/readyHealth plus freshness of the projectionProjectionThe regular pass that brings the read model up to date with the canonical log. It runs every 30 seconds by default.. Returns the age of the latest projection pass per organisation and a status of ready, degraded, stale or failed. 503 for stale and failed. Takes org and max_age_s (default 90).

Questions and answers

MethodPathPurpose
POST/questionsSubmit a question to the retained queue, routed to Compass or Strategy, optionally scoped to the organisation or one team.
GET/questionsList the viewer’s retained questions.
GET/questions/{request_id}Read one retained question and its answer. The id must be a universally unique identifierUUIDUniversally unique identifier: a standard identifier intended to distinguish one record from other records, even across separate systems. (UUID).
POST/questions/{request_id}/stop-waitingStop waiting for a question. It does not cancel the model computation.
POST/compassAsk Compass directly, outside the queue. Bounded by the inferenceInferenceThe work a language model does to produce an answer from its instructions and input. slots.
POST/compass/groupThe board-level ask, based only on a group snapshot.
POST/strategyAsk the Strategy agent a broad what-ifWhat-ifA scenario that changes one or more dependencies in the model and reports the result. A what-if changes nothing in the records, and its result is indicative. over the graphGraphA model made of units and links between them. In NovusLens it records teams, services and their dependencies. and the meaning canonMeaning canonThe organisation’s supplied written descriptions of its operations, systems and terms. NovusLens stores these separately from records of teams, dependencies and measurements..
POST/tools/{name}Call one of the five reasoning tools directly: query_graph, query_meaning, simulate_scenario, retrieve_evidence, highlight. Unknown names return 404.
POST/evidence/viewThe evidence response behind a cellCellA box on the map that stands for a team, service, supplier or AI agent. It is a unit you can inspect, not necessarily a department or a person. or a findingFindingA difference in the records that needs a decision. It includes its sources and can describe a slow handoff, disputed fact or missing owner., for the drawer and the evidence page.
POST/disputeChallengeChallengeA recorded dispute of a value. Both the original and the disputed version are kept, and the challenge is listed under Findings. a value. The disputed value becomes a contested entry on the log, and humans resolve it.

Organisation import and operations

MethodPathPurpose
POST/operations/import-orgPropose an organisation from an org chart, transcript or structure upload. Nothing is committed.
GET/operations/import-progressTurn-by-turn progress of a proposal, polled by job_id.
GET/operations/pending-proposalThe viewer’s recoverable proposal, if one exists.
POST/operations/commit-orgCommit a proposal the human has reviewed.
POST/operations/discard-proposalDiscard a pending proposal.
POST/operations/fulfilAnswer an open artifactArtifactA stored source file or evidence body that a record can cite. Keeping the exact content lets a reader check what supported the record. request with a document.
POST/operations/resolve-findingResolve a finding through the accountable ownerAccountable ownerThe person recorded as answerable for a team, service or agent. NovusLens does not assume that this person is also the one who runs it day to day.. The divergence stays on the log.
GET/operations/export-orgchartThe organisation chart generated from current records, with sources, evidence levels and recorded disputes.

Live capture

MethodPathPurpose
POST/capture/startOpen a live capture session, optionally scoped to a cell.
POST/capture/answerSend one conversational turn; the agent reflects and asks the next question.
POST/capture/attachAttach a document mid-conversation.
POST/capture/discardAbandon a session without committing anything.
POST/capture/commitConfirm the session and commit what was captured.

Meaning canon and stewardship

MethodPathPurpose
POST/meaning/ingestIngestIngestRead supplied records or documents and add their information to NovusLens, after the required checks. a document into the meaning canon.
GET/meaning/queryQuery the meaning canon by text or cell.
POST/meaning/visibilityChange the visibility of a meaning entryMeaning entryA stored written account supplied by the organisation, such as a policy or definition. Answers can cite it without treating it as a measured fact.. An audited act.
POST/meaning/visibility-previewFor selected teams, show who would be able to see a meaning record, as roles and team owners.
POST/meaning/retractRetract a meaning entry. The record of who, when and why is kept.
POST/steward/retract-findingRetract a told fact or a finding raised in error.
POST/steward/retract-sessionRetract a whole capture session. Steward only.
POST/steward/purge-artifactRemove a document’s body. A tombstoneTombstoneA retained record that says content was removed, when it was removed and why. The removed content itself is no longer available. and the log entry remain. Steward only.
POST/steward/deep-sweepRun the on-demand model-assisted contradiction pass over the meaning canon.
GET/steward/auditThe query audit, filterable by person, role, organisation, action and time.

Notifications

MethodPathPurpose
POST/notify/subscribeDeclare who is told what. Operator only.
GET/notify/subscriptionsList subscriptions, optionally including disabled ones.
POST/notify/unsubscribeRemove a subscription.
POST/notify/pollRun one delivery pass.

Assurance

MethodPathPurpose
POST/assurance/bundleBuild an inputs bundle for one scopeScopeThe work, data, activity or access that a rule, statement or calculation covers. For access, it names the records an account can see. For team measures, “Own operations” covers the selected unit. “Including descendants” adds the units beneath it. and period, with coverage stated.
POST/assurance/acceptRecord an external party’s decision on an issued bundle.
GET/assurance/acceptancesList recorded acceptances.

Federation and groups

MethodPathPurpose
GET/.well-known/agent.jsonThe AgentCard generated from the reasoning tools. Public discovery metadata.
GET/.well-known/agent-facts.jsonA region’s signed AgentFactsAgentFactsA signed statement from an agent about its allowed work, its permissions and the person answerable for it. document. Takes region and viewer.
POST/federation/emitA region signs a cross-region dependencyDependencyA link where one unit needs something from another. A dependency is not a reporting line: it shows where work relies on something else. under its own identity.
POST/federation/ingestVerify a signed fact and admit it to a group, or refuse it.
POST/group/createCreate a group.
POST/group/add-memberAdd a member organisation to a group.
GET/group/snapshotThe group snapshot for a group_id.
GET/groupsList the groups the viewer may see.

Complexity, Agility and Recoverability (C/A/R)

MethodPathPurpose
GET/car/scoresThe current C/A/RC/A/RThree separate scores for a team or service: Complexity, Agility and Recoverability. Each uses current evidence and the customer’s stated scoring rules. scores for the organisation.
GET/car/assessmentThe assessment for one cell, over its subtree by default.
POST/car/evidencePublish a set of C/A/R evidence records.
POST/car/captureRecord a consumer-to-provider dependency at the told rungRungOne of three levels of support for a recorded value: told, shown or measured. The level appears beside the value.. Includes role (mandatory, optional or unknown) and review interval (1–365 days).
POST/car/retain-findingsAt a user’s request, record assessment findings for people to review and resolve.
GET/car/evidence-templateA template for a set of C/A/R evidence records.
POST/car/archiveArchive an assessment. Chief-executive, board and operator roles only.
GET/car/replayReplay a stored assessment record by artifact_id. Chief-executive, board and operator roles only.

Findings support

MethodPathPurpose
GET/findings/current-generatedThe tracked findings whose support is current for the viewer, and which kinds are tracked.
GET/findings/support-reviewNeutral review metadata about the support behind generated findings.

Catalogues

MethodPathPurpose
GET/cataloguesList catalogues.
POST/catalogues/revisionWrite a new catalogue revision.
POST/catalogues/approveApprove a catalogue revision.

Remits and agent evidence

MethodPathPurpose
GET/remits/product-sourceWhat the installation’s product source is, and whether it may carry a remitRemitA written list of an agent’s allowed actions, resources and destinations for information. The list states whether it is complete. declaration.
POST/remits/product-source/rotateReplace the installation’s product key. Operator only.
GET/remits/declarationsList remit declarations.
POST/remits/declareRecord a remit declaration for a subject.
POST/remits/approveApprove a declaration, optionally on behalf of another person.
POST/remits/withdrawWithdraw a declaration, with a reason.
POST/remits/templateDefine a remit template.
POST/remits/approve-templateApprove a template revision.
GET/remits/exportExport a declaration to a policy format, cedar by default. The export is generated and never deployed by NovusLens.
POST/agent-evidence/criteriaRecord the outcome criterion for an intervention case on the versioned policy. An operator act.
POST/agent-evidence/ingestIngest signed agent evidence.
POST/agent-evidence/refreshPublish pending agent-evidence batches through the twinTwinNovusLens’s model of one organisation, built from records about its teams, services and how they rely on one another. It is only as current as those records. writer, then update the read modelRead modelThe database tables used by the map, Ask and Find. NovusLens rebuilds these tables from its history of recorded changes.. Operator only.
GET/agent-evidence/caseRead one case, optionally as known at a time and in a policy mode.
GET/agent-evidence/requestsList evidence requestsEvidence requestA request for a document to support something somebody stated. The Findings tab lists it as Evidence requested..
GET/agent-evidence/activitiesThe remit panel: recorded remits and observed activities with comparator results. Case states, never verdicts.
GET/agent-evidence/deliveryStatus of the delivery worker.
POST/agent-evidence/policy/activateActivate the agent-evidence policy from the configured enrolmentEnrolmentThe operator's recorded permission for a source to send specified record types about named agents, using an identified signing key.. Operator only.
GET/agent-evidence/receiptThe receiptReceiptA recorded acknowledgement of a request or action, with its identity, time and result. An evidence intake receipt confirms storage. It does not establish acceptance or prove that an agent acted. for a batch_id from a source.
GET/agent-evidence/checkpointThe checkpoint for a stream from a source.
Last updated
Agent accountabilityOverview