HTTP API

ImandraX exposes its reasoning engine via a Twirp RPC API, a protobuf-based protocol over HTTP. Client libraries for Python, TypeScript, Rust, and OCaml are generated from the protobuf definitions in the imandrax-api repository.

Architecture

The API is session-based. You create a session, submit IML code for evaluation, run verification and decomposition commands, and retrieve results, all through typed RPC calls. Sessions maintain state: definitions submitted in one call are available for subsequent calls in the same session.

Services

The API is split into several protobuf services:

Simple: high-level API

The primary service for most use cases. Provides a streamlined interface for common operations:

MethodDescription
statusGet server status
shutdownAsk the server to exit
create_sessionCreate a new reasoning session
end_sessionTerminate a session
eval_srcEvaluate IML source code
verify_srcVerify a property given as source code
verify_nameVerify a named predicate already in the session
instance_srcFind a satisfying instance given source code
instance_nameFind a satisfying instance for a named predicate
qcheck_srcQuickCheck a property given as source code
qcheck_nameQuickCheck a named predicate
decomposeRun region decomposition on a named function
decompose_fullRegion decomposition with composition operators
typecheckTypecheck source code and return inferred types
get_declsRetrieve declarations by name
oneshotSessionless, self-contained request/response

Eval: low-level evaluation

For more fine-grained control over evaluation and artifact management:

MethodDescription
eval_code_snippetEvaluate a code snippet in a session
parse_termParse and typecheck a term, return as artifact
parse_typeParse and typecheck a type, return as artifact
list_artifactsList available artifact kinds for a task
get_artifactRetrieve an artifact from a task
get_artifact_zipRetrieve an artifact as a zip file

SessionManager: session lifecycle

MethodDescription
create_sessionCreate a new session (with optional proof obligation checking)
open_sessionReconnect to an existing session
end_sessionTerminate a session
keep_session_aliveKeep a session active

System: server information

MethodDescription
versionReturn the server version
gc_statsGet garbage collection statistics
release_memoryFree memory and return stats

Key message types

Verification results

Verification calls (verify_src, verify_name) return a VerifyRes with one of:

ResultMeaning
ProvedThe property holds for all inputs. May carry a pretty-printed proof.
RefutedA counterexample was found. Carries a Model with its IML source.
Verified_uptoVerified up to a bound, but not proved inductively.
unknownThe prover could not decide.
errAn error occurred.

Instance results

Instance calls return an InstanceRes with one of:

ResultMeaning
SatAn instance was found. Carries a Model.
UnsatNo satisfying instance exists.
unknownThe solver could not decide.

Decomposition

The decompose method takes:

ParameterDescription
nameFunction name to decompose
assumingOptional side-condition function name
basisList of function names to treat as atomic
rule_specsRewrite and forward-chaining rules to apply during decomposition
pruneRemove infeasible regions
ctx_simpEnable contextual simplification
lift_boolBoolean lifting strategy (Default, NestedEqualities, Equalities, All)
timeoutTimeout in seconds

For complex decompositions with composition operators (merge, compound merge, combine), use decompose_full with its recursive Decomp message type.

Tasks and artifacts

Many operations produce tasks: background computations whose results can be retrieved later. Each task has an ID and a kind (TASK_EVAL, TASK_CHECK_PO, TASK_PROOF_CHECK, TASK_DECOMP). Use list_artifacts and get_artifact to retrieve structured results from completed tasks.

Authentication

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer <your-api-key>

Place your API key in ~/.config/imandrax/api_key, or set one of the environment variables (IMANDRA_UNI_KEY, IMANDRAX_API_KEY, or IMANDRA_KEY).

Protocol details

The API uses Twirp v7 over HTTP with protobuf serialization. The default server path prefix is /api/v1. All requests include an x-api-version header for version compatibility.

Protobuf definitions

The canonical protobuf definitions are in the imandrax-api repository. Pre-built client libraries are available for Python, TypeScript, Rust, and OCaml.