Public Contract¶
This page is the v1 public contract of Genesis Mesh: every HTTP route of the
Network Authority, every CLI command, the public Python API, every signed
artifact and every API error code, each classified as stable, beta or
internal. The source of truth is contract/public-surface.json;
genesis_mesh/tests/test_public_contract.py fails when the code exposes
anything the contract does not classify, or when a listed item changes or
disappears. Compatibility rules are in DEPRECATION_POLICY.md.
Level |
Meaning |
|---|---|
stable |
Will not break within 1.x. Removed or changed incompatibly only after the deprecation cycle in |
beta |
Shipped and supported; may change in a minor version with a CHANGELOG notice. |
internal |
No compatibility promise. Operator UI pages and implementation details. |
Packages¶
Package |
Level |
Support |
|---|---|---|
genesis-mesh (PyPI) ( |
stable |
The Network Authority, CLI and Python API as classified on this page. Supported deployment profiles: single instance on SQLite, and one or more instances on PostgreSQL (HA). Security fixes for the latest minor version line. |
genesis-mesh-sdk (npm) ( |
stable |
Every stable HTTP route, the governed secret lifecycle (attestation evaluation, policy lifecycle, evidence store, governedAction), HA failover, and offline verification of decisions, agreements, policies, data-usage records and evidence exports. Node.js 22 or newer. |
github.com/GenesisMeshLabs/sdk-go ( |
stable |
Stable for its clients (agreement, boundary decide and verify, evidence, attestation, disclosure, consensus, data usage, raw admin calls) and offline verification of agreements, boundary decisions, license policies and data access intents. It does not wrap the policy lifecycle, attestation evaluation or the evidence store; call those routes with raw admin calls. |
genesismesh-sdk-dotnet (NuGet) ( |
stable |
Same scope as the Go SDK: its clients and OfflineVerifier are stable; the policy lifecycle, attestation evaluation and evidence store are reached with raw admin calls. .NET 8. |
genesis-mesh-sdk (Rust crate, Git) ( |
beta |
Embeddable portable-trust primitives distributed as a Git dependency, not on crates.io. Not a leg of the interoperability scenario yet. |
genesis-mesh-gateway ( |
beta |
Release binaries on GitHub. Not part of the v1 stable contract. |
PHP SDK ( |
unsupported |
Not on the release train (last version 0.56.0); no support or compatibility promise. |
HTTP routes¶
Method |
Path |
Level |
|---|---|---|
GET |
|
internal |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET, POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
beta |
POST |
|
stable |
POST |
|
beta |
POST |
|
beta |
POST |
|
stable |
POST |
|
stable |
POST |
|
beta |
POST |
|
beta |
GET |
|
stable |
GET, POST |
|
stable |
POST |
|
stable |
GET |
|
stable |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
GET |
|
stable |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
beta |
GET, POST |
|
beta |
DELETE, GET |
|
beta |
POST |
|
stable |
GET |
|
internal |
GET |
|
internal |
GET |
|
beta |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET |
|
internal |
GET |
|
internal |
GET |
|
stable |
GET |
|
beta |
POST |
|
beta |
GET |
|
stable |
GET |
|
internal |
GET |
|
internal |
GET |
|
stable |
POST |
|
stable |
POST |
|
beta |
POST |
|
beta |
POST |
|
stable |
GET |
|
internal |
GET |
|
internal |
GET |
|
stable |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET |
|
beta |
GET |
|
stable |
GET |
|
internal |
GET |
|
internal |
GET |
|
internal |
GET |
|
stable |
GET |
|
stable |
GET |
|
beta |
GET |
|
stable |
GET |
|
stable |
GET |
|
stable |
POST |
|
stable |
POST |
|
stable |
GET |
|
stable |
GET |
|
stable |
GET |
|
internal |
GET |
|
internal |
POST |
|
beta |
Error codes¶
Every error response is {“error”: {“code”, “message”, “details”, “request_id”}}. code is stable; message and details are for people and may change. Errors derived from a plain HTTP status (not_found, method_not_allowed, request_entity_too_large and other werkzeug status names) use the status name in snake case and are stable. Every code below is stable: it is never removed or given a new meaning.
accept_rejected, admin_auth_failed, agent_not_registered, ambiguous_basis, asset_not_found, attestation_not_found, bad_request, boundary_eval_failed, boundary_policy_activation_conflict, boundary_policy_activation_refused, boundary_policy_integrity_failed, boundary_policy_invalid, boundary_policy_not_active, boundary_policy_not_found, boundary_policy_required, boundary_policy_version_conflict, certificate_key_mismatch, certificate_not_found, certificate_revoked, commit_failed, conflict, counter_rejected, crl_publish_contention, delete_signature_required, descriptor_expired, descriptor_network_mismatch, descriptor_signature_required, empty_subject_public_keys, evidence_build_failed, evidence_store_disabled, evidence_store_unavailable, executor_key_exists, executor_key_not_found, executor_key_retired, forbidden, insufficient_operator_tier, intent_create_failed, internal_server_error, invalid_agent_descriptor, invalid_agreement, invalid_attestation_id, invalid_attestation_or_policy, invalid_attestation_or_treaty, invalid_boundary_policy, invalid_commitment, invalid_context, invalid_decision, invalid_evidence, invalid_input, invalid_invite_token, invalid_json, invalid_json_object, invalid_justification, invalid_max_validity_hours, invalid_offer, invalid_page, invalid_policy, invalid_policy_version, invalid_proof, invalid_public_key, invalid_public_keys, invalid_recipient_public_key, invalid_recognition_policy, invalid_recognition_treaty, invalid_retention, invalid_revocation_reason, invalid_role, invalid_signature, invalid_signed_at, invalid_source, invalid_sovereign_revocation_feed, invalid_timestamp_order, invalid_timestamps, invalid_token_expiry_hours, invalid_treaty_scope, invalid_validity_hours, invalid_verdict, invalid_vote_type, last_active_operator_key, missing_accept_fields, missing_agreement, missing_attestation_subject, missing_boundary_fields, missing_cert_id, missing_certificate_identity, missing_commit_fields, missing_counter_fields, missing_decision, missing_evidence, missing_executor_key_fields, missing_intent_fields, missing_invite_token, missing_issuer_public_keys, missing_node_public_key, missing_offer_fields, missing_policy, missing_policy_fields, missing_policy_id, missing_proof, missing_proof_fields, missing_prove_fields, missing_recognition_policy, missing_signature, missing_treaty_subject, missing_trust_path_parameters, missing_validator_public_keys, missing_validity_window, missing_verify_fields, missing_vote_fields, no_policy, node_auth_failed, node_has_no_active_certificate, node_key_compromised, node_key_revoked, not_found, nullifier_failed, offer_rejected, policy_not_found, policy_sign_failed, proof_assembly_failed, prove_failed, rate_limit_exceeded, recognition_policy_not_configured, renewal_role_change_forbidden, request_validation_failed, resource_not_found, retention_in_progress, service_not_ready, service_unavailable, signed_at_outside_window, stale_sequence, treaty_not_found, unauthorized, unexpected_field, unknown_operator_key, validation_failed, vendor_not_found, vote_failed, wrong_issuer
Signed artifacts¶
Each is signed over its canonical form without the signature field (see
RFC-001, Canonical JSON and signatures, and DEPRECATION_POLICY.md for how
signed formats evolve).
Model |
Signature field |
Level |
|---|---|---|
|
|
stable |
|
|
stable |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
stable |
|
|
stable |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
beta |
|
|
stable |
|
|
stable |
|
|
stable |
CLI commands¶
Command |
Level |
|---|---|
|
stable |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
stable |
|
beta |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
stable |
|
beta |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
beta |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
stable |
|
stable |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
stable |
|
stable |
|
stable |
|
beta |
|
stable |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
beta |
|
stable |
|
stable |
|
stable |
|
stable |
Python API¶
Symbols not listed are internal. Parameters are listed in order;
* marks keyword-only parameters and ? optional ones.
Symbol |
Parameters |
Level |
|---|---|---|
|
(none) |
stable |
|
model, private_key, key_id |
stable |
|
model, signature, public_key |
stable |
|
data, private_key |
stable |
|
data, signature_b64, public_key |
stable |
|
path |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
treaty, issuer_public_keys, *expected_issuer_sovereign_id?, *expected_subject_sovereign_id?, *revoked_treaty_ids?, *current_time? |
stable |
|
attestation, treaty, treaty_issuer_public_keys, *revoked_treaty_ids?, *revoked_attestation_ids?, *current_time? |
stable |
|
feed, issuer_public_keys, *expected_issuer_sovereign_id?, *min_sequence? |
stable |
|
attestation, policy, current_time? |
stable |
|
graph, source_sovereign_id, target_sovereign_id, *requested_roles?, *now? |
stable |
|
model |
stable |
|
offerer_sovereign_id, responder_sovereign_id, requested_terms, graph, signing_key, *issued_by, *expires_at, *now? |
stable |
|
offer, offered_terms, graph, signing_key, *issued_by, *now? |
stable |
|
offer, graph, signing_key, *issued_by, *now? |
stable |
|
counter, original_offer, signing_key, *issued_by, *now? |
stable |
|
record, signing_key, *issued_by |
stable |
|
record, offerer_public_keys, responder_public_keys, *expected_graph_digest? |
stable |
|
decision, operator_public_keys, *freshness_proof_issuer_keys?, *now?, *expected_policies?, *expected_attestation? |
stable |
|
policy, signing_key, issued_by |
stable |
|
policy, public_keys |
stable |
|
policy, registry |
stable |
|
events, *na_public_keys, *executor_keys, *contiguous?, *checkpoint? |
stable |
|
evidence |
stable |
|
model |
stable |
|
model |
stable |
|
model |
stable |
|
agent_sovereign_id, decision_id, sources, access_types, signing_key, *estimated_volume_bytes?, *valid_for_seconds?, *now? |
stable |
|
intent, policy, agent_public_keys, *at_time? |
stable |
|
operator_sovereign_id, *decision_valid_seconds?, *require_freshness_proof? |
beta |
|
(none) |
beta |
|
active, context, registry, public_keys, now, *integrity_failures? |
beta |
|
attestation_id, attestation, *issuer_public_keys, *stored_status, *feed_revoked, *revocation_seq_checked, *requester_id |
beta |
|
agreement, bearer_sovereign_id, capabilities, signing_key, *issued_by, *valid_for_seconds?, *max_invocations?, *policy_constraints?, *delegation?, *now? |
beta |
|
token, issuer_public_keys, *requested_capability, *bearer_sovereign_id, *use_records?, *at_time? |
beta |
|
agent_sovereign_id, model_id, model_version_tag, system_prompt, tool_ids, signing_key, *token_id?, *valid_for_seconds?, *now? |
beta |
|
attestation, policy, agent_public_keys, *at_time? |
beta |
|
decision, issuer_sovereign_id, graph_digest, issued_by, signing_key, *metadata?, *now? |
beta |
|
evidence, issuer_public_keys, *expected_graph_digest? |
beta |
|
capabilities, agreement, signing_key, *issued_by, *now? |
beta |
|
capability, capabilities, commitment, prover_sovereign_id, *now? |
beta |
|
proof, commitment, issuer_public_keys, *nullifier?, *used_nullifiers?, *now? |
beta |
|
proof, signing_key, *issued_by, *valid_for_seconds?, *now? |
beta |
|
justification_proof, validator_sovereign_id, vote, signing_key, *reason?, *context_digest?, *now? |
beta |
|
justification_proof, votes, required_threshold, validator_sovereign_ids, assembler_signing_key, *issued_by, *valid_for_seconds?, *cascade_threshold?, *expected_deliberation_seconds?, *now? |
beta |
|
proof, validator_public_keys, assembler_public_keys, *justification_proof?, *cascade_threshold?, *expected_deliberation_seconds?, *at_time? |
beta |
|
graph |
beta |
|
from_sovereign_id, to_sovereign_id, signing_key, *initial_signal?, *alpha?, *decay_lambda?, *now? |
beta |
|
signal, evidence, signing_key, *history?, *anomaly_sigma_threshold?, *now? |
beta |
|
signal, signing_key, *now? |
beta |
|
signing_key, key_id, provider |
beta |
|
config, *http_get?, *environ? |
beta |
|
provider?, key_id?, key_file?, seed_env_var?, vault_url?, secret_name? |
beta |
|
db, na_public_key? |
beta |
|
sqlite_path, database_url, *na_public_key? |
beta |