{ "contract": "AMDUATD/API/2", "base_path": "/v2", "notes": "Draft v2: PEL-only write surface. Direct artifact write endpoint removed.", "endpoints": [ {"method": "GET", "path": "/v2/meta"}, {"method": "HEAD", "path": "/v2/meta"}, {"method": "GET", "path": "/v2/contract"}, {"method": "GET", "path": "/v2/healthz"}, {"method": "GET", "path": "/v2/readyz"}, {"method": "GET", "path": "/v2/metrics"}, {"method": "GET", "path": "/v2/artifacts/{ref}"}, {"method": "HEAD", "path": "/v2/artifacts/{ref}"}, {"method": "GET", "path": "/v2/artifacts/{ref}?format=info"}, {"method": "POST", "path": "/v2/pel/execute"}, {"method": "POST", "path": "/v2/ops/put"}, {"method": "POST", "path": "/v2/ops/concat"}, {"method": "POST", "path": "/v2/ops/slice"}, {"method": "GET", "path": "/v2/jobs/{id}"}, {"method": "GET", "path": "/v2/get/{ref}"}, {"method": "POST", "path": "/v2/graph/nodes"}, {"method": "POST", "path": "/v2/graph/nodes/{name}/versions"}, {"method": "POST", "path": "/v2/graph/nodes/{name}/versions/tombstone"}, {"method": "GET", "path": "/v2/graph/nodes/{name}/versions"}, {"method": "GET", "path": "/v2/graph/nodes/{name}/neighbors"}, {"method": "GET", "path": "/v2/graph/search"}, {"method": "GET", "path": "/v2/graph/paths"}, {"method": "GET", "path": "/v2/graph/subgraph"}, {"method": "POST", "path": "/v2/graph/edges"}, {"method": "POST", "path": "/v2/graph/edges/tombstone"}, {"method": "POST", "path": "/v2/graph/batch"}, {"method": "POST", "path": "/v2/graph/query"}, {"method": "POST", "path": "/v2/graph/retrieve"}, {"method": "POST", "path": "/v2/graph/export"}, {"method": "POST", "path": "/v2/graph/import"}, {"method": "GET", "path": "/v2/graph/schema/predicates"}, {"method": "POST", "path": "/v2/graph/schema/predicates"}, {"method": "GET", "path": "/v2/graph/stats"}, {"method": "GET", "path": "/v2/graph/capabilities"}, {"method": "GET", "path": "/v2/graph/changes"}, {"method": "GET", "path": "/v2/graph/edges"}, {"method": "GET", "path": "/v2/graph/nodes/{name}"}, {"method": "GET", "path": "/v2/graph/history/{name}"} ], "schemas": { "job_enqueue_response": { "type": "object", "required": ["job_id", "status"], "properties": { "job_id": {"type": "integer"}, "status": {"type": "string"} } }, "job_status_response": { "type": "object", "required": ["job_id", "kind", "status", "created_at_ms"], "properties": { "job_id": {"type": "integer"}, "kind": {"type": "string"}, "status": {"type": "string"}, "created_at_ms": {"type": "integer"}, "started_at_ms": {"type": ["integer", "null"]}, "completed_at_ms": {"type": ["integer", "null"]}, "result_ref": {"type": ["string", "null"]}, "error": {"type": ["string", "null"]} } }, "healthz_response": { "type": "object", "required": ["ok", "status", "time_ms"], "properties": { "ok": {"type": "boolean"}, "status": {"type": "string"}, "time_ms": {"type": "integer"} } }, "readyz_response": { "type": "object", "required": ["ok", "status", "components"], "properties": { "ok": {"type": "boolean"}, "status": {"type": "string"}, "components": { "type": "object", "required": ["graph_index", "federation"], "properties": { "graph_index": {"type": "boolean"}, "federation": {"type": "boolean"} } } } }, "put_request": { "type": "object", "required": ["body_hex"], "properties": { "body_hex": {"type": "string"}, "type_tag": {"type": "string"} } }, "concat_request": { "type": "object", "required": ["left_ref", "right_ref"], "properties": { "left_ref": {"type": "string"}, "right_ref": {"type": "string"} } }, "slice_request": { "type": "object", "required": ["ref", "offset", "length"], "properties": { "ref": {"type": "string"}, "offset": {"type": "integer"}, "length": {"type": "integer"} } }, "graph_node_create_request": { "type": "object", "required": ["name"], "properties": { "name": {"type": "string"}, "ref": {"type": "string", "description": "optional initial published ref"} } }, "graph_node_create_response": { "type": "object", "required": ["name", "concept_ref"], "properties": { "name": {"type": "string"}, "concept_ref": {"type": "string"} } }, "graph_provenance": { "type": "object", "required": ["source_uri", "extractor", "observed_at", "ingested_at", "trace_id"], "properties": { "source_uri": {"type": "string"}, "extractor": {"type": "string"}, "confidence": {"type": ["string", "number", "integer"]}, "observed_at": {"type": "integer"}, "ingested_at": {"type": "integer"}, "license": {"type": "string"}, "trace_id": {"type": "string"} } }, "graph_edge_create_request": { "type": "object", "required": ["subject", "predicate", "object"], "properties": { "subject": {"type": "string", "description": "concept name or hex ref"}, "predicate": {"type": "string", "description": "relation alias/name or hex ref"}, "object": {"type": "string", "description": "concept name or hex ref"}, "metadata_ref": {"type": "string", "description": "optional artifact ref"}, "provenance": {"$ref": "#/schemas/graph_provenance"} } }, "graph_edge_create_response": { "type": "object", "required": ["subject_ref", "predicate_ref", "object_ref", "edge_ref"], "properties": { "subject_ref": {"type": "string"}, "predicate_ref": {"type": "string"}, "object_ref": {"type": "string"}, "edge_ref": {"type": "string"}, "metadata_ref": {"type": "string"} } }, "graph_edge_tombstone_request": { "type": "object", "required": ["edge_ref"], "properties": { "edge_ref": {"type": "string"}, "metadata_ref": {"type": "string"}, "provenance": {"$ref": "#/schemas/graph_provenance"} } }, "graph_edge_tombstone_response": { "type": "object", "required": ["ok", "target_edge_ref", "tombstone_edge_ref"], "properties": { "ok": {"type": "boolean"}, "target_edge_ref": {"type": "string"}, "tombstone_edge_ref": {"type": "string"}, "metadata_ref": {"type": "string"} } }, "graph_node_version_tombstone_request": { "type": "object", "required": ["ref"], "properties": { "ref": {"type": "string"}, "metadata_ref": {"type": "string"}, "provenance": {"$ref": "#/schemas/graph_provenance"} } }, "graph_node_version_tombstone_response": { "type": "object", "required": ["ok", "name", "ref", "target_edge_ref", "tombstone_edge_ref"], "properties": { "ok": {"type": "boolean"}, "name": {"type": "string"}, "ref": {"type": "string"}, "target_edge_ref": {"type": "string"}, "tombstone_edge_ref": {"type": "string"}, "metadata_ref": {"type": "string"} } }, "graph_batch_request": { "type": "object", "properties": { "idempotency_key": {"type": "string"}, "mode": {"type": "string", "enum": ["fail_fast", "continue_on_error"]}, "nodes": { "type": "array", "items": { "type": "object", "required": ["name"], "properties": { "name": {"type": "string"}, "ref": {"type": "string"} } } }, "versions": { "type": "array", "items": { "type": "object", "required": ["name", "ref"], "properties": { "name": {"type": "string"}, "ref": {"type": "string"}, "metadata_ref": {"type": "string"}, "provenance": {"$ref": "#/schemas/graph_provenance"} } } }, "edges": { "type": "array", "items": { "type": "object", "required": ["subject", "predicate", "object"], "properties": { "subject": {"type": "string"}, "predicate": {"type": "string"}, "object": {"type": "string"}, "metadata_ref": {"type": "string"}, "provenance": {"$ref": "#/schemas/graph_provenance"} } } } } }, "graph_batch_response": { "type": "object", "required": ["ok", "applied", "results"], "properties": { "ok": {"type": "boolean"}, "idempotency_key": {"type": "string"}, "mode": {"type": "string", "enum": ["fail_fast", "continue_on_error"]}, "applied": { "type": "object", "required": ["nodes", "versions", "edges"], "properties": { "nodes": {"type": "integer"}, "versions": {"type": "integer"}, "edges": {"type": "integer"} } }, "results": { "type": "array", "items": { "type": "object", "required": ["kind", "index", "status", "code", "error"], "properties": { "kind": {"type": "string", "enum": ["node", "version", "edge"]}, "index": {"type": "integer"}, "status": {"type": "string", "enum": ["applied", "error"]}, "code": {"type": "integer"}, "error": {"type": ["string", "null"]} } } } } }, "graph_query_request": { "type": "object", "properties": { "where": { "type": "object", "properties": { "subject": {"type": "string"}, "object": {"type": "string"}, "node": {"type": "string"}, "provenance_ref": {"type": "string"} } }, "predicates": {"type": "array", "items": {"type": "string"}}, "direction": {"type": "string", "enum": ["any", "outgoing", "incoming"]}, "include_versions": {"type": "boolean"}, "include_tombstoned": {"type": "boolean"}, "include_stats": {"type": "boolean"}, "max_result_bytes": {"type": "integer"}, "as_of": {"type": ["string", "integer"]}, "limit": {"type": "integer"}, "cursor": {"type": ["string", "integer"]} } }, "graph_query_response": { "type": "object", "required": ["nodes", "edges", "paging"], "properties": { "nodes": { "type": "array", "items": { "type": "object", "required": ["concept_ref", "name", "latest_ref"], "properties": { "concept_ref": {"type": "string"}, "name": {"type": ["string", "null"]}, "latest_ref": {"type": ["string", "null"]}, "versions": { "type": "array", "items": { "type": "object", "required": ["edge_ref", "ref"], "properties": { "edge_ref": {"type": "string"}, "ref": {"type": "string"} } } } } } }, "edges": { "type": "array", "items": { "type": "object", "required": ["subject_ref", "predicate_ref", "object_ref", "edge_ref"], "properties": { "subject_ref": {"type": "string"}, "predicate_ref": {"type": "string"}, "object_ref": {"type": "string"}, "edge_ref": {"type": "string"} } } }, "paging": { "type": "object", "required": ["next_cursor", "has_more"], "properties": { "next_cursor": {"type": ["string", "null"]}, "has_more": {"type": "boolean"} } }, "stats": { "type": "object", "properties": { "scanned_edges": {"type": "integer"}, "returned_edges": {"type": "integer"} } } } }, "graph_retrieve_request": { "type": "object", "required": ["roots"], "properties": { "roots": {"type": "array", "items": {"type": "string"}}, "goal_predicates": {"type": "array", "items": {"type": "string"}}, "max_depth": {"type": "integer"}, "max_fanout": {"type": "integer"}, "include_versions": {"type": "boolean"}, "include_tombstoned": {"type": "boolean"}, "as_of": {"type": ["string", "integer"]}, "provenance_min_confidence": {"type": ["string", "number", "integer"]}, "limit_nodes": {"type": "integer"}, "limit_edges": {"type": "integer"}, "max_result_bytes": {"type": "integer"} } }, "graph_retrieve_response": { "type": "object", "required": ["nodes", "edges", "explanations", "truncated", "stats"], "properties": { "nodes": { "type": "array", "items": { "type": "object", "required": ["concept_ref", "name", "latest_ref"], "properties": { "concept_ref": {"type": "string"}, "name": {"type": ["string", "null"]}, "latest_ref": {"type": ["string", "null"]}, "versions": { "type": "array", "items": { "type": "object", "required": ["edge_ref", "ref"], "properties": { "edge_ref": {"type": "string"}, "ref": {"type": "string"} } } } } } }, "edges": { "type": "array", "items": { "type": "object", "required": ["subject_ref", "predicate_ref", "object_ref", "edge_ref"], "properties": { "subject_ref": {"type": "string"}, "predicate_ref": {"type": "string"}, "object_ref": {"type": "string"}, "edge_ref": {"type": "string"} } } }, "explanations": { "type": "array", "items": { "type": "object", "required": ["edge_ref", "depth", "reasons"], "properties": { "edge_ref": {"type": "string"}, "depth": {"type": "integer"}, "reasons": {"type": "array", "items": {"type": "string"}}, "confidence": {"type": ["number", "null"]} } } }, "truncated": {"type": "boolean"}, "stats": { "type": "object", "properties": { "scanned_edges": {"type": "integer"}, "traversed_edges": {"type": "integer"}, "returned_nodes": {"type": "integer"}, "returned_edges": {"type": "integer"} } } } }, "graph_export_request": { "type": "object", "properties": { "as_of": {"type": ["string", "integer"]}, "cursor": {"type": ["string", "integer"]}, "limit": {"type": "integer"}, "predicates": {"type": "array", "items": {"type": "string"}}, "roots": {"type": "array", "items": {"type": "string"}}, "include_tombstoned": {"type": "boolean"}, "max_result_bytes": {"type": "integer"} } }, "graph_export_response": { "type": "object", "required": ["items", "next_cursor", "has_more", "snapshot_as_of", "stats"], "properties": { "items": { "type": "array", "items": { "type": "object", "required": ["seq", "edge_ref", "subject_ref", "predicate_ref", "predicate", "object_ref", "tombstoned"], "properties": { "seq": {"type": "integer"}, "edge_ref": {"type": "string"}, "subject_ref": {"type": "string"}, "predicate_ref": {"type": "string"}, "predicate": {"type": "string"}, "object_ref": {"type": "string"}, "tombstoned": {"type": "boolean"}, "metadata_ref": {"type": ["string", "null"]} } } }, "next_cursor": {"type": ["string", "null"]}, "has_more": {"type": "boolean"}, "snapshot_as_of": {"type": "string"}, "stats": { "type": "object", "properties": { "scanned_edges": {"type": "integer"}, "exported_items": {"type": "integer"} } } } }, "graph_import_request": { "type": "object", "required": ["items"], "properties": { "mode": {"type": "string", "enum": ["fail_fast", "continue_on_error"]}, "items": { "type": "array", "items": { "type": "object", "properties": { "subject_ref": {"type": "string"}, "subject": {"type": "string"}, "predicate_ref": {"type": "string"}, "predicate": {"type": "string"}, "object_ref": {"type": "string"}, "object": {"type": "string"}, "metadata_ref": {"type": "string"} } } } } }, "graph_import_response": { "type": "object", "required": ["ok", "applied", "results"], "properties": { "ok": {"type": "boolean"}, "applied": {"type": "integer"}, "results": { "type": "array", "items": { "type": "object", "required": ["index", "status", "code", "error", "edge_ref"], "properties": { "index": {"type": "integer"}, "status": {"type": "string", "enum": ["applied", "error"]}, "code": {"type": "integer"}, "error": {"type": ["string", "null"]}, "edge_ref": {"type": ["string", "null"]} } } } } }, "graph_schema_predicates_request": { "type": "object", "properties": { "mode": {"type": "string", "enum": ["strict", "warn", "off"]}, "provenance_mode": {"type": "string", "enum": ["optional", "required"]}, "predicates": { "type": "array", "items": { "type": "object", "properties": { "predicate_ref": {"type": "string"}, "predicate": {"type": "string"}, "domain": {"type": "string"}, "range": {"type": "string"} } } } } }, "graph_schema_predicates_response": { "type": "object", "required": ["mode", "provenance_mode", "predicates"], "properties": { "mode": {"type": "string", "enum": ["strict", "warn", "off"]}, "provenance_mode": {"type": "string", "enum": ["optional", "required"]}, "predicates": { "type": "array", "items": { "type": "object", "required": ["predicate_ref", "domain", "range"], "properties": { "predicate_ref": {"type": "string"}, "domain": {"type": ["string", "null"]}, "range": {"type": ["string", "null"]} } } } } }, "graph_stats_response": { "type": "object", "required": ["edges_total", "aliases_total", "index", "tombstones"], "properties": { "edges_total": {"type": "integer"}, "aliases_total": {"type": "integer"}, "index": { "type": "object", "required": ["built_for_edges", "src_buckets", "dst_buckets", "predicate_buckets", "src_predicate_buckets", "dst_predicate_buckets", "healthy"], "properties": { "built_for_edges": {"type": "integer"}, "src_buckets": {"type": "integer"}, "dst_buckets": {"type": "integer"}, "predicate_buckets": {"type": "integer"}, "src_predicate_buckets": {"type": "integer"}, "dst_predicate_buckets": {"type": "integer"}, "healthy": {"type": "boolean"} } }, "tombstones": { "type": "object", "required": ["edges", "ratio"], "properties": { "edges": {"type": "integer"}, "ratio": {"type": "number"} } } } }, "graph_capabilities_response": { "type": "object", "required": ["contract", "graph", "runtime"], "properties": { "contract": {"type": "string"}, "graph": { "type": "object", "required": ["version", "features", "limits", "modes"], "properties": { "version": {"type": "string"}, "features": {"type": "array", "items": {"type": "string"}}, "limits": {"type": "object"}, "modes": {"type": "object"} } }, "runtime": {"type": "object"} } }, "graph_changes_response": { "type": "object", "required": ["events", "next_cursor", "has_more"], "properties": { "events": { "type": "array", "items": { "type": "object", "required": ["event", "cursor", "edge_ref", "subject_ref", "predicate_ref", "object_ref"], "properties": { "event": {"type": "string", "enum": ["edge_appended", "version_published", "tombstone_applied"]}, "cursor": {"type": "string"}, "edge_ref": {"type": "string"}, "subject_ref": {"type": "string"}, "predicate_ref": {"type": "string"}, "object_ref": {"type": "string"}, "concept_ref": {"type": "string"}, "ref": {"type": "string"}, "tombstoned_edge_ref": {"type": "string"} } } }, "next_cursor": {"type": ["string", "null"]}, "has_more": {"type": "boolean"} } }, "graph_node_response": { "type": "object", "required": ["name", "concept_ref", "latest_ref", "versions", "outgoing", "incoming"], "properties": { "name": {"type": "string"}, "concept_ref": {"type": "string"}, "latest_ref": {"type": ["string", "null"]}, "versions": {"type": "array", "items": {"type": "string"}}, "outgoing": { "type": "array", "items": { "type": "object", "required": ["predicate_ref", "object_ref"], "properties": { "predicate_ref": {"type": "string"}, "object_ref": {"type": "string"}, "edge_ref": {"type": "string"}, "metadata_ref": {"type": ["string", "null"]} } } }, "incoming": { "type": "array", "items": { "type": "object", "required": ["predicate_ref", "subject_ref"], "properties": { "predicate_ref": {"type": "string"}, "subject_ref": {"type": "string"}, "edge_ref": {"type": "string"}, "metadata_ref": {"type": ["string", "null"]} } } } } }, "graph_history_response": { "type": "object", "required": ["name", "events"], "properties": { "name": {"type": "string"}, "events": { "type": "array", "items": { "type": "object", "required": ["event", "at_ms"], "properties": { "event": {"type": "string"}, "at_ms": {"type": "integer"}, "ref": {"type": ["string", "null"]}, "edge_ref": {"type": ["string", "null"]}, "details": {"type": "object"} } } } } }, "pel_execute_request": { "type": "object", "required": ["program_ref", "inputs", "receipt"], "properties": { "program_ref": {"type": "string", "description": "hex ref or concept name"}, "scheme_ref": {"type": "string", "description": "hex ref or 'dag'"}, "params_ref": {"type": "string", "description": "hex ref or concept name"}, "inputs": { "type": "object", "properties": { "refs": { "type": "array", "items": {"type": "string", "description": "hex ref or concept name"} }, "inline_artifacts": { "type": "array", "items": { "type": "object", "required": ["body_hex"], "properties": { "content_type": {"type": "string"}, "type_tag": {"type": "string", "description": "hex tag id, optional"}, "body_hex": {"type": "string"} } } } } }, "receipt": { "type": "object", "required": [ "input_manifest_ref", "environment_ref", "evaluator_id", "executor_ref", "started_at", "completed_at" ], "properties": { "input_manifest_ref": {"type": "string", "description": "hex ref or concept name"}, "environment_ref": {"type": "string", "description": "hex ref or concept name"}, "evaluator_id": {"type": "string"}, "executor_ref": {"type": "string", "description": "hex ref or concept name"}, "sbom_ref": {"type": "string", "description": "hex ref or concept name"}, "parity_digest_hex": {"type": "string"}, "executor_fingerprint_ref": {"type": "string", "description": "hex ref or concept name"}, "run_id_hex": {"type": "string"}, "limits": { "type": "object", "required": ["cpu_ms", "wall_ms", "max_rss_kib", "io_reads", "io_writes"], "properties": { "cpu_ms": {"type": "integer"}, "wall_ms": {"type": "integer"}, "max_rss_kib": {"type": "integer"}, "io_reads": {"type": "integer"}, "io_writes": {"type": "integer"} } }, "logs": { "type": "array", "items": { "type": "object", "required": ["kind", "log_ref", "sha256_hex"], "properties": { "kind": {"type": "integer"}, "log_ref": {"type": "string", "description": "hex ref or concept name"}, "sha256_hex": {"type": "string"} } } }, "determinism_level": {"type": "integer", "description": "0-255"}, "rng_seed_hex": {"type": "string"}, "signature_hex": {"type": "string"}, "started_at": {"type": "integer"}, "completed_at": {"type": "integer"} } }, "effects": { "type": "object", "properties": { "publish_outputs": {"type": "boolean"}, "append_fed_log": {"type": "boolean"} } } } }, "pel_execute_response": { "type": "object", "required": ["run_ref", "receipt_ref", "stored_input_refs", "output_refs", "status"], "properties": { "run_ref": {"type": "string", "description": "hex ref"}, "trace_ref": {"type": "string", "description": "hex ref"}, "receipt_ref": {"type": "string", "description": "hex ref"}, "stored_input_refs": {"type": "array", "items": {"type": "string", "description": "hex ref"}}, "output_refs": {"type": "array", "items": {"type": "string", "description": "hex ref"}}, "status": {"type": "string"} } }, "error_response": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "retryable"], "properties": { "code": {"type": "string"}, "message": {"type": "string"}, "retryable": {"type": "boolean"} } } } } } }