{ "openapi": "3.1.0", "info": { "title": "Audit logs", "version": "2026-10-18", "description": "An append-only evidence ledger for agents: what an agent attempted, who submitted the record, the authority that it claimed, its outcome and reported cost, and references to its evidence. Each batch adds leaves to an RFC 9162 Merkle tree, and Motor signs each new root with ECDSA P-256. Inclusion and consistency proofs verify offline. An NDJSON export has a line with the leaf hash of every sequence of its range, and its manifest has a range proof, so every line, complete or partial, rebuilds the signed root offline. Verifying an export’s hashes doesn’t prove that its filters found every matching event. A signed receipt proves that Motor committed particular bytes, not that their claims are true.\n\nCreation, append, seal, extension, and erasure requests require an `Idempotency-Key`; export cancellation does not replay responses. Sealing, extensions, and deletion need `If-Match` with the ledger's configuration revision. Sequences and sizes are decimal strings. Rates: $0.001 for each bounded work unit, such as a request or an export step; $0.000005 for each new event; and $1 per GB-month of retention, prepaid in whole days for 1 MiB per ledger and 8 KiB per event." }, "servers": [ { "url": "https://api.motor.dev/audit_logs" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Ledgers", "description": "Ledgers, their retention, sealing, and deletion." }, { "name": "Events", "description": "Atomic appends, bounded queries, and the feed." }, { "name": "Proofs", "description": "Signed checkpoints, inclusion and consistency proofs, and public keys." }, { "name": "Evidence", "description": "Artifacts that events retain." }, { "name": "Erasure", "description": "Payload erasure and cleanup operations." }, { "name": "Exports", "description": "Portable NDJSON exports in Artifact storage." } ], "paths": { "/ledgers": { "post": { "operationId": "createLedger", "tags": [ "Ledgers" ], "summary": "Create a ledger", "description": "Creates a ledger and signs its empty checkpoint. Every event in the ledger shares its expiry, so a late event gets the time that remains. Costs one work unit and 1 MiB of retention for each day: $0.002048576 for 30 days. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "201": { "description": "The ledger.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.002048576`: one work unit and 30 days of 1 MiB.", "schema": { "type": "string" } }, "ETag": { "description": "`\"{id}:{revision}\"`, for `If-Match`.", "schema": { "type": "string" } }, "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" }, "example": { "id": "ald_LrB528wYtd4M8VJwtZikAt", "object": "audit_ledger", "state": "open", "created_at": "2026-10-18T09:00:00.000000Z", "expires_at": "2026-11-17T09:00:00.000000Z", "remaining_seconds": "2592000", "remaining_days": "30", "revision": "1", "etag": "ald_LrB528wYtd4M8VJwtZikAt:1", "deletion": null, "name": "Agent actions", "metadata": { "team": "payments" }, "retention_days": "30", "sealed_at": null, "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "checkpoint": { "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "issued_at": "2026-10-18T09:00:00.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "events": "0", "billable_bytes": "1048576", "paid_through": "2026-11-17T09:00:00.000000Z", "erasure_generation": "0", "retained_artifacts": 0, "controls": { "used": 0, "remaining": 256 }, "bounds": { "max_event_bytes": 4096, "max_batch_events": 100, "max_targets": 8, "max_evidence": 8, "max_page_items": 100, "max_page_bytes": 131072, "max_candidates_per_page": "1000", "max_extension_horizon_days": "365", "max_controls": 256, "max_retained_artifacts": 100 }, "cost": { "rate_version": "2026-10-18", "charged_usd": "0.002048576" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "31457280", "charged_usd": "0.002048576" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerCreate" }, "example": { "name": "Agent actions", "retention_days": 30, "metadata": { "team": "payments" }, "max_cost_usd": "0.01" } } } } }, "get": { "operationId": "listLedgers", "tags": [ "Ledgers" ], "summary": "List ledgers", "description": "Returns the team's ledgers in creation order. Costs one work unit. Credentials: a secret key.", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "enum": [ "open", "sealed", "expired", "deleting", "deleted" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "A page of ledgers.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerList" }, "example": { "data": [ { "id": "ald_LrB528wYtd4M8VJwtZikAt", "object": "audit_ledger", "state": "open", "created_at": "2026-10-18T09:00:00.000000Z", "expires_at": "2026-11-17T09:00:00.000000Z", "remaining_seconds": "2592000", "remaining_days": "30", "revision": "1", "etag": "ald_LrB528wYtd4M8VJwtZikAt:1", "deletion": null, "name": "Agent actions", "metadata": { "team": "payments" }, "retention_days": "30", "sealed_at": null, "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "checkpoint": { "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "issued_at": "2026-10-18T09:00:00.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "events": "0", "billable_bytes": "1048576", "paid_through": "2026-11-17T09:00:00.000000Z", "erasure_generation": "0", "retained_artifacts": 0, "controls": { "used": 0, "remaining": 256 }, "bounds": { "max_event_bytes": 4096, "max_batch_events": 100, "max_targets": 8, "max_evidence": 8, "max_page_items": 100, "max_page_bytes": 131072, "max_candidates_per_page": "1000", "max_extension_horizon_days": "365", "max_controls": 256, "max_retained_artifacts": 100 }, "cost": { "rate_version": "2026-10-18", "charged_usd": "0.002048576" } } ], "has_more": false, "next_cursor": null, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}": { "get": { "operationId": "getLedger", "tags": [ "Ledgers" ], "summary": "Get a ledger", "description": "Returns the ledger, its configuration ETag, its tree size and root, its paid expiry, its bounds, and its billable bytes. A ledger that's being deleted shows its deletion. Costs one work unit. Credentials: a secret key or an audit_logs:read token for the ledger without a run restriction.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The ledger.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } }, "ETag": { "description": "`\"{id}:{revision}\"`, for `If-Match`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" }, "example": { "id": "ald_LrB528wYtd4M8VJwtZikAt", "object": "audit_ledger", "state": "open", "created_at": "2026-10-18T09:00:00.000000Z", "expires_at": "2026-11-17T09:00:00.000000Z", "remaining_seconds": "2592000", "remaining_days": "30", "revision": "1", "etag": "ald_LrB528wYtd4M8VJwtZikAt:1", "deletion": null, "name": "Agent actions", "metadata": { "team": "payments" }, "retention_days": "30", "sealed_at": null, "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "checkpoint": { "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "issued_at": "2026-10-18T09:00:00.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "events": "0", "billable_bytes": "1048576", "paid_through": "2026-11-17T09:00:00.000000Z", "erasure_generation": "0", "retained_artifacts": 0, "controls": { "used": 0, "remaining": 256 }, "bounds": { "max_event_bytes": 4096, "max_batch_events": 100, "max_targets": 8, "max_evidence": 8, "max_page_items": 100, "max_page_bytes": 131072, "max_candidates_per_page": "1000", "max_extension_horizon_days": "365", "max_controls": 256, "max_retained_artifacts": 100 }, "cost": { "rate_version": "2026-10-18", "charged_usd": "0.002048576" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "deleteLedger", "tags": [ "Ledgers" ], "summary": "Delete a ledger", "description": "Deletes the ledger and everything in it. Every read stops at once; the returned operation tracks background cleanup; poll it until it succeeds. Customers' retained artifacts stay in Artifact storage. Prepaid retention isn't refunded. Costs one work unit when the key can pay; otherwise the deletion is included. Credentials: a secret key. Erasure is irreversible and removes data from the live service. Encrypted historical database versions currently don't have a fixed deletion deadline. Download URLs already issued may remain usable until they expire; downloaded copies can't be recalled.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "202": { "description": "The deletion's operation.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The actual request charge in USD: `0.001` for one work unit, or `0` when included lifecycle work applies.", "schema": { "type": "string" } }, "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" }, "example": { "operation": { "id": "aop_HpWa3MCTWRzisojbcqWptL", "object": "audit_operation", "kind": "deletion", "state": "pending", "reason_code": "customer_request", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "event_ids": [], "phase": "exports", "counts": { "events": "0", "erased": "0", "removed_rows": "0" }, "retry": { "attempts": 0, "error_code": null }, "created_at": "2026-10-18T09:00:45.000000Z", "updated_at": "2026-10-18T09:00:45.000000Z", "finished_at": null, "deadline_at": "2026-10-19T09:00:45.000000Z" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "422": { "$ref": "#/components/responses/Invalid" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/ledgers/{ledger_id}/seal": { "post": { "operationId": "sealLedger", "tags": [ "Ledgers" ], "summary": "Seal a ledger", "description": "Stops appends for good and signs a control receipt. Reads, proofs, exports, and extensions continue until expiry. A sealed ledger answers with its state. Costs one work unit. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The sealed ledger.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } }, "ETag": { "description": "`\"{id}:{revision}\"`, for `If-Match`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" }, "example": { "id": "ald_LrB528wYtd4M8VJwtZikAt", "object": "audit_ledger", "state": "sealed", "created_at": "2026-10-18T09:00:00.000000Z", "expires_at": "2026-11-17T09:00:00.000000Z", "remaining_seconds": "2592000", "remaining_days": "30", "revision": "2", "etag": "ald_LrB528wYtd4M8VJwtZikAt:2", "deletion": null, "name": "Agent actions", "metadata": { "team": "payments" }, "retention_days": "30", "sealed_at": "2026-10-18T09:00:43.000000Z", "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "checkpoint": { "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "issued_at": "2026-10-18T09:00:00.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "events": "0", "billable_bytes": "1048576", "paid_through": "2026-11-17T09:00:00.000000Z", "erasure_generation": "0", "retained_artifacts": 0, "controls": { "used": 1, "remaining": 255 }, "bounds": { "max_event_bytes": 4096, "max_batch_events": 100, "max_targets": 8, "max_evidence": 8, "max_page_items": 100, "max_page_bytes": 131072, "max_candidates_per_page": "1000", "max_extension_horizon_days": "365", "max_controls": 256, "max_retained_artifacts": 100 }, "cost": { "rate_version": "2026-10-18", "charged_usd": "0.002048576" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" }, "control_receipt": { "kind": "seal", "index": 0, "issued_at": "2026-10-18T09:00:10.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"expires_at_after\":\"2026-11-17T09:00:00.000000Z\",\"expires_at_before\":\"2026-11-17T09:00:00.000000Z\",\"index\":\"0\",\"issued_at\":\"2026-10-18T09:00:10.000000Z\",\"key_id\":\"development-1\",\"kind\":\"seal\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"revision_after\":\"2\",\"revision_before\":\"1\",\"tree_size\":\"4\",\"version\":\"motor-audit-control-v1\"}", "signature": "KPPDcGesEqF-QcPLWlA4sNPi_0ZIf81Rv-t2rQpcpu_hrx88t0AoYKlJcG_pjnOURMwM6l3yyPb7i9ULKZz9xA" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } } } }, "/ledgers/{ledger_id}/extensions": { "post": { "operationId": "extendLedger", "tags": [ "Ledgers" ], "summary": "Extend a ledger's retention", "description": "Adds `days` to the ledger's expiry, at most 365 days from now, and signs a control receipt. It pays 1 MiB and 8 KiB for every retained event, tombstones included, for each added day. A retained artifact with an `expires_at` before the new expiry makes the extension refuse with `evidence_expiring`. Costs one work unit and the retention. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The extended ledger.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The work unit and the retention.", "schema": { "type": "string" } }, "ETag": { "description": "`\"{id}:{revision}\"`, for `If-Match`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ledger" }, "example": { "id": "ald_LrB528wYtd4M8VJwtZikAt", "object": "audit_ledger", "state": "open", "created_at": "2026-10-18T09:00:00.000000Z", "expires_at": "2026-11-27T09:00:00.000000Z", "remaining_seconds": "3455990", "remaining_days": "40", "revision": "2", "etag": "ald_LrB528wYtd4M8VJwtZikAt:2", "deletion": null, "name": "Agent actions", "metadata": { "team": "payments" }, "retention_days": "30", "sealed_at": null, "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "checkpoint": { "tree_size": "0", "root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "issued_at": "2026-10-18T09:00:00.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "events": "0", "billable_bytes": "1048576", "paid_through": "2026-11-27T09:00:00.000000Z", "erasure_generation": "0", "retained_artifacts": 0, "controls": { "used": 1, "remaining": 255 }, "bounds": { "max_event_bytes": 4096, "max_batch_events": 100, "max_targets": 8, "max_evidence": 8, "max_page_items": 100, "max_page_bytes": 131072, "max_candidates_per_page": "1000", "max_extension_horizon_days": "365", "max_controls": 256, "max_retained_artifacts": 100 }, "cost": { "rate_version": "2026-10-18", "charged_usd": "0.002048576" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "10731520", "charged_usd": "0.001357717333" }, "control_receipt": { "kind": "extension", "index": 0, "issued_at": "2026-10-18T09:00:10.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"expires_at_after\":\"2026-11-27T09:00:00.000000Z\",\"expires_at_before\":\"2026-11-17T09:00:00.000000Z\",\"index\":\"0\",\"issued_at\":\"2026-10-18T09:00:10.000000Z\",\"key_id\":\"development-1\",\"kind\":\"extension\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"revision_after\":\"2\",\"revision_before\":\"1\",\"tree_size\":\"4\",\"version\":\"motor-audit-control-v1\"}", "signature": "KPPDcGesEqF-QcPLWlA4sNPi_0ZIf81Rv-t2rQpcpu_hrx88t0AoYKlJcG_pjnOURMwM6l3yyPb7i9ULKZz9xA" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "428": { "$ref": "#/components/responses/PreconditionRequired" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Extension" }, "example": { "days": 10, "max_cost_usd": "0.1" } } } } } }, "/ledgers/{ledger_id}/events": { "post": { "operationId": "appendEvents", "tags": [ "Events" ], "summary": "Append events", "description": "Appends 1 to 100 events atomically: either all of them commit, or Motor doesn't commit any. Sequences follow the request's order, and Motor signs the new checkpoint before it answers. A repeated `client_event_id` with the same content and submitter returns its first receipt without another append or retention charge; a new request still costs one work unit. Different content or a different submitter returns `event_conflict`. Recover a lost response by retrying with the same `Idempotency-Key`. Costs one work unit, and for each new event $0.000005 and 8 KiB of retention until the ledger expires. Credentials: a secret key, or an append token of the ledger.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "201": { "description": "The receipts and the signed checkpoint.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The work unit, the appends, and the retention.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendReceipt" }, "example": { "object": "audit_append_receipt", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "receipts": [ { "event_id": "aev_4hya3wkMnJMhbAKFeiScRN", "sequence": "1", "leaf_hash": "c2660305f1b4886aac394ef391f29ab3f4ba66a659a7a5c35168f66a69ae9939", "duplicate": false, "payload_erased": false }, { "event_id": "aev_6edPveaagHj5aBDcfdUsps", "sequence": "2", "leaf_hash": "cb58d17147bd3276f0bf987fbb173e1015f2f8c7e584ef627d7f359e6927b4e6", "duplicate": false, "payload_erased": false } ], "tree_size": "2", "checkpoint": { "tree_size": "2", "root_hash": "abf3716c7edabb20fa0bd526cae3e4edd20a18964bcbc0fc8d14ce1414b00dab", "issued_at": "2026-10-18T09:00:02.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:02.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"abf3716c7edabb20fa0bd526cae3e4edd20a18964bcbc0fc8d14ce1414b00dab\",\"tree_size\":\"2\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "paid_through": "2026-11-17T09:00:00.000000Z", "remaining_seconds": "2591998", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "2", "retained_byte_days": "491520", "charged_usd": "0.001026384" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" }, "410": { "$ref": "#/components/responses/Gone" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppendRequest" }, "example": { "events": [ { "client_event_id": "e1", "action": "payment.submit", "actor": { "type": "agent", "id": "agent_7" }, "targets": [ { "type": "invoice", "id": "inv_9" } ], "outcome": "attempted", "occurred_at": "2026-10-18T08:59:00Z", "run_id": "run_1", "authority": { "kind": "approval", "reference": "apr_7", "scopes": [ "payments:submit" ] }, "cost": { "amount": "0.25", "currency": "USD", "kind": "estimated" }, "evidence": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "mode": "retain" }, { "uri": "https://example.com/receipt", "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } ], "attributes": { "attempt": 1 } }, { "client_event_id": "e2", "action": "payment.submit", "actor": { "type": "agent", "id": "agent_7" }, "targets": [ { "type": "invoice", "id": "inv_9" } ], "outcome": "succeeded", "occurred_at": "2026-10-18T08:59:30Z", "run_id": "run_1", "parent_client_event_id": "e1" } ], "max_cost_usd": "0.01" } } } } }, "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "description": "Returns a bounded page of the ledger's events in ascending sequence. Filters use exact matches, and an event must match every filter. Each page examines at most 1,000 candidates, so an empty page can still have a next cursor. The first page captures the tree size. An erasure in the ledger invalidates older cursors with `snapshot_invalidated`. The feed takes at most 2 requests a second for each ledger. Costs one work unit, even for an empty page. Credentials: a secret key, or a read token of the ledger.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "name": "actor_type", "in": "query", "required": false, "description": "With `actor_id`: `agent`, `user`, `service`, or `system`.", "schema": { "type": "string" } }, { "name": "actor_id", "in": "query", "required": false, "description": "With `actor_type`.", "schema": { "type": "string" } }, { "name": "target_type", "in": "query", "required": false, "description": "With `target_id`.", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "required": false, "description": "With `target_type`.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "An exact action.", "schema": { "type": "string" } }, { "name": "run_id", "in": "query", "required": false, "description": "An exact run.", "schema": { "type": "string" } }, { "name": "trace_id", "in": "query", "required": false, "description": "An exact trace.", "schema": { "type": "string" } }, { "name": "outcome", "in": "query", "required": false, "description": "`attempted`, `succeeded`, `failed`, `denied`, or `unknown`.", "schema": { "type": "string" } }, { "name": "source_kind", "in": "query", "required": false, "description": "`customer` or `motor`.", "schema": { "type": "string" } }, { "name": "received_from", "in": "query", "required": false, "description": "An inclusive lower bound of `received_at`.", "schema": { "type": "string" } }, { "name": "received_before", "in": "query", "required": false, "description": "An exclusive upper bound of `received_at`.", "schema": { "type": "string" } }, { "name": "occurred_from", "in": "query", "required": false, "description": "An inclusive lower bound of `occurred_at`.", "schema": { "type": "string" } }, { "name": "occurred_before", "in": "query", "required": false, "description": "An exclusive upper bound of `occurred_at`.", "schema": { "type": "string" } }, { "name": "after_sequence", "in": "query", "required": false, "description": "Start after this sequence.", "schema": { "type": "string" } }, { "name": "through_sequence", "in": "query", "required": false, "description": "Stop at this sequence.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IncludeCanonical" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "A page of events.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "data": [ { "id": "aev_4hya3wkMnJMhbAKFeiScRN", "object": "audit_event", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "sequence": "1", "leaf_hash": "c2660305f1b4886aac394ef391f29ab3f4ba66a659a7a5c35168f66a69ae9939", "received_at": "2026-10-18T09:00:02.000000Z", "source_kind": "customer", "payload_erased": false, "source": { "kind": "customer" }, "submitter": { "credential": "secret_key", "key_id": "key_NDxHjEB5ddPCBkhcm2SLP6", "principal_id": "user_WSJsCZHdzwgnV6LMCtKUqD" }, "parent_event_id": null, "evidence": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "digest_status": "verified", "mode": "retain", "sha256": "9e85aa95f04db5f108534e48b63e75e8045a7ecab59988405e70a9260300a0d6", "size_bytes": "13" } ], "event": { "action": "payment.submit", "actor": { "id": "agent_7", "type": "agent" }, "attributes": { "attempt": 1 }, "authority": { "kind": "approval", "reference": "apr_7", "scopes": [ "payments:submit" ] }, "client_event_id": "e1", "cost": { "amount": "0.25", "currency": "USD", "kind": "estimated" }, "evidence": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "mode": "retain" }, { "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "uri": "https://example.com/receipt" } ], "occurred_at": "2026-10-18T08:59:00.000000Z", "outcome": "attempted", "run_id": "run_1", "targets": [ { "id": "inv_9", "type": "invoice" } ] } } ], "has_more": true, "next_cursor": "eyJ2IjozLCJzIjoi...", "snapshot_tree_size": "4", "last_examined_sequence": "1", "scanned": "1", "access_path": "actor", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "409": { "$ref": "#/components/responses/Conflict" }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/events/{event_id}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "summary": "Get an event", "description": "Returns the event and its leaf hash, or its tombstone after an erasure. An erased field never appears. Costs one work unit. Credentials: a secret key, or a read token of the ledger.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/IncludeCanonical" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The event or its tombstone.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "aev_4hya3wkMnJMhbAKFeiScRN", "object": "audit_event", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "sequence": "1", "leaf_hash": "c2660305f1b4886aac394ef391f29ab3f4ba66a659a7a5c35168f66a69ae9939", "received_at": "2026-10-18T09:00:02.000000Z", "source_kind": "customer", "payload_erased": false, "source": { "kind": "customer" }, "submitter": { "credential": "secret_key", "key_id": "key_NDxHjEB5ddPCBkhcm2SLP6", "principal_id": "user_WSJsCZHdzwgnV6LMCtKUqD" }, "parent_event_id": null, "evidence": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "digest_status": "verified", "mode": "retain", "sha256": "9e85aa95f04db5f108534e48b63e75e8045a7ecab59988405e70a9260300a0d6", "size_bytes": "13" } ], "event": { "action": "payment.submit", "actor": { "id": "agent_7", "type": "agent" }, "attributes": { "attempt": 1 }, "authority": { "kind": "approval", "reference": "apr_7", "scopes": [ "payments:submit" ] }, "client_event_id": "e1", "cost": { "amount": "0.25", "currency": "USD", "kind": "estimated" }, "evidence": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "mode": "retain" }, { "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "uri": "https://example.com/receipt" } ], "occurred_at": "2026-10-18T08:59:00.000000Z", "outcome": "attempted", "run_id": "run_1", "targets": [ { "id": "inv_9", "type": "invoice" } ] }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/checkpoints/latest": { "get": { "operationId": "getLatestCheckpoint", "tags": [ "Proofs" ], "summary": "Get the latest checkpoint", "description": "Returns the newest signed checkpoint. An empty ledger has its signed size-zero checkpoint. Costs one work unit. Credentials: a secret key, or a read token without a run.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The checkpoint.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestCheckpoint" }, "example": { "object": "audit_checkpoint", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "tree_size": "4", "root_hash": "e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407", "issued_at": "2026-10-18T09:00:03.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:03.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407\",\"tree_size\":\"4\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/proofs/inclusion": { "get": { "operationId": "getInclusionProof", "tags": [ "Proofs" ], "summary": "Prove an event's inclusion", "description": "Returns the event's leaf hash, its audit path, and the signed checkpoint of `tree_size`, which must be a committed checkpoint that covers the event. Motor verifies the proof before it answers. Costs one work unit. Credentials: a secret key, or a read token without a run.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "name": "sequence", "in": "query", "required": true, "description": "The event's sequence.", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$" } }, { "name": "tree_size", "in": "query", "required": true, "description": "A tree size of a signed checkpoint, such as an append receipt's.", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The inclusion proof.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InclusionProof" }, "example": { "object": "audit_inclusion_proof", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "event_id": "aev_6edPveaagHj5aBDcfdUsps", "sequence": "2", "leaf_index": "1", "tree_size": "4", "leaf_hash": "fd179e7caf6945129e781dd0f960b4c185f6922826e9140110d71b8270a1ff2d", "path": [ "252db5297b35fac9da498ad9ad14cbf79454e2512065ead115861a080766b6ac", "d6b3b31c76acbfc2bb77d728f76b3e9c4c9183d4d2cd3990135167d846997d97" ], "checkpoint": { "tree_size": "4", "root_hash": "e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407", "issued_at": "2026-10-18T09:00:03.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:03.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407\",\"tree_size\":\"4\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/proofs/consistency": { "get": { "operationId": "getConsistencyProof", "tags": [ "Proofs" ], "summary": "Prove a ledger's consistency", "description": "Returns the proof that the tree of `from_size` is a prefix of the tree of `to_size`, and both signed checkpoints. Both sizes must be committed checkpoints; size zero is valid. Costs one work unit. Credentials: a secret key, or a read token without a run.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "name": "from_size", "in": "query", "required": true, "description": "The older tree size.", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$" } }, { "name": "to_size", "in": "query", "required": true, "description": "The newer tree size.", "schema": { "type": "string", "pattern": "^[0-9]{1,19}$" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The consistency proof.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsistencyProof" }, "example": { "object": "audit_consistency_proof", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "from_size": "3", "to_size": "4", "proof": [ "1d5a3c0a0981448737b02c141395c0b18d492fd6445787f253910017a13dde63", "32b5178fb60f75feadc8eb0d7d13eef0a169c31266a957b0e2783a5c64b3e27c", "e5c4af99d8f9105bd9762e6fb83e1d2147d7b284b13da2d0627f0e480e580a39" ], "from_checkpoint": { "tree_size": "3", "root_hash": "f3744b374cda1f2e104b47abf8f69e6a8469b1903fb9d63fd92c6a4894098d83", "issued_at": "2026-10-18T09:00:02.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:02.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"f3744b374cda1f2e104b47abf8f69e6a8469b1903fb9d63fd92c6a4894098d83\",\"tree_size\":\"3\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "to_checkpoint": { "tree_size": "4", "root_hash": "e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407", "issued_at": "2026-10-18T09:00:03.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"issued_at\":\"2026-10-18T09:00:03.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e08d9bbf3c09cbf9d5bb50746cc83bdea40554a41335f12de0308b9269754407\",\"tree_size\":\"4\",\"version\":\"motor-audit-checkpoint-v1\"}", "signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/evidence": { "get": { "operationId": "listEvidence", "tags": [ "Evidence" ], "summary": "List retained evidence", "description": "Returns the ledger's retained artifacts with their current state and paid retention. It never returns bytes or URLs; get download URLs from Artifact storage. Costs one work unit. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "name": "expires_before", "in": "query", "required": false, "description": "Only artifacts whose paid retention ends before this time.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "A page of retained evidence.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceList" }, "example": { "data": [ { "artifact_id": "art_Co8jNxhZn3uCz6ZmBLYx6w", "references": 1, "retained_until": "2026-11-17T09:00:00.000000Z", "artifact_status": "ready", "artifact_expires_at": "2027-01-15T09:00:00.000000Z", "created_at": "2026-10-18T09:00:02.000000Z" } ], "has_more": false, "next_cursor": null, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/erasures": { "post": { "operationId": "eraseEvents", "tags": [ "Erasure" ], "summary": "Erase event payloads", "description": "Erases the payloads of 1 to 100 events. They disappear at once, and the returned operation tracks background cleanup; poll it until it succeeds. Each event keeps its sequence, ID, and leaf hash, so proofs still verify. Older query and export snapshots stop, and earlier exports lose their artifacts. Copies that you already have can't be recalled. Prepaid retention isn't refunded. Costs one work unit when the key can pay; otherwise the erasure is included. Credentials: a secret key. Erasure is irreversible and removes data from the live service. Encrypted historical database versions currently don't have a fixed deletion deadline. Download URLs already issued may remain usable until they expire; downloaded copies can't be recalled.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "202": { "description": "The erasure's operation and its control receipt.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The actual request charge in USD: `0.001` for one work unit, or `0` when included lifecycle work applies.", "schema": { "type": "string" } }, "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationAccepted" }, "example": { "operation": { "id": "aop_N3d27GEhQsEkL4hmM72ZnZ", "object": "audit_operation", "kind": "erasure", "state": "pending", "reason_code": "sensitive_data", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "event_ids": [ "aev_4hya3wkMnJMhbAKFeiScRN" ], "phase": "events", "counts": { "events": "1", "erased": "0", "removed_rows": "0" }, "retry": { "attempts": 0, "error_code": null }, "created_at": "2026-10-18T09:00:45.000000Z", "updated_at": "2026-10-18T09:00:45.000000Z", "finished_at": null, "deadline_at": "2026-10-19T09:00:45.000000Z" }, "control_receipt": { "kind": "erasure", "index": 2, "issued_at": "2026-10-18T09:00:10.000000Z", "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "signed_body": "{\"event_ids\":[\"aev_4hya3wkMnJMhbAKFeiScRN\"],\"expires_at_after\":\"2026-11-17T09:00:00.000000Z\",\"expires_at_before\":\"2026-11-17T09:00:00.000000Z\",\"index\":\"2\",\"issued_at\":\"2026-10-18T09:00:10.000000Z\",\"key_id\":\"development-1\",\"kind\":\"erasure\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"reason_code\":\"sensitive_data\",\"revision_after\":\"1\",\"revision_before\":\"1\",\"tree_size\":\"4\",\"version\":\"motor-audit-control-v1\"}", "signature": "KPPDcGesEqF-QcPLWlA4sNPi_0ZIf81Rv-t2rQpcpu_hrx88t0AoYKlJcG_pjnOURMwM6l3yyPb7i9ULKZz9xA" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErasureCreate" }, "example": { "event_ids": [ "aev_4hya3wkMnJMhbAKFeiScRN" ], "reason_code": "sensitive_data" } } } } } }, "/operations/{operation_id}": { "get": { "operationId": "getOperation", "tags": [ "Erasure" ], "summary": "Get an operation", "description": "Returns the progress of an erasure or a deletion. Costs one work unit when the key can pay; otherwise the read is included. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/OperationId" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The operation.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The actual request charge in USD: `0.001` for one work unit, or `0` when included lifecycle work applies.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" }, "example": { "id": "aop_N3d27GEhQsEkL4hmM72ZnZ", "object": "audit_operation", "kind": "erasure", "state": "succeeded", "reason_code": "sensitive_data", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "event_ids": [ "aev_4hya3wkMnJMhbAKFeiScRN" ], "phase": "done", "counts": { "events": "1", "erased": "1", "removed_rows": "5" }, "retry": { "attempts": 0, "error_code": null }, "created_at": "2026-10-18T09:00:45.000000Z", "updated_at": "2026-10-18T09:00:47.000000Z", "finished_at": "2026-10-18T09:00:47.000000Z", "deadline_at": "2026-10-19T09:00:45.000000Z", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/ledgers/{ledger_id}/exports": { "post": { "operationId": "createExport", "tags": [ "Exports" ], "summary": "Export a ledger", "description": "Exports a range of the ledger's snapshot as NDJSON parts of at most 4 MiB and a manifest, each an artifact in Artifact storage. Every sequence of the range has a line with its leaf hash: a matching event's canonical bytes in Base64, a tombstone with `payload_erased: true`, or `omitted: true` for an event that the filters leave out. The manifest's `range_proof` lists the subtree hashes outside the range; with the lines' leaf hashes, it rebuilds the root of the signed `checkpoint`, which authenticates every line and its sequence. That doesn't prove that a tombstone's event was erased, or that an omitted event doesn't match the filters. Each step examines at most 1,000 candidates and costs one work unit, and Artifact storage charges for writes and prepaid retention of each part and the manifest. Downloads incur separate read and delivery charges outside the export cost cap. The export never exceeds `max_cost_usd`. Limits: 1,000,000 candidates, 8 GiB, and 2,048 parts. Costs one work unit at admission. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/LedgerId" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "202": { "description": "The queued export and its cost bound.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } }, "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportAccepted" }, "example": { "export": { "id": "aex_Jm7CidaYcuEm2rbDR4wQE3", "object": "audit_export", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "state": "queued", "from_sequence": "1", "through_sequence": "4", "snapshot_tree_size": "4", "filters": { "indexed": [], "occurred_before": null, "occurred_from": null, "outcome": null, "received_before": null, "received_from": null, "source_kind": null }, "complete_ledger": true, "artifact_retention_days": "2", "deadline_at": "2026-10-18T10:00:11.000000Z", "progress": { "last_examined_sequence": "0", "scanned": "0", "matched": "0", "parts": 0, "bytes": "0", "phase": "scan" }, "manifest_artifact_id": null, "cost": { "rate_version": "2026-10-18", "max_cost_usd": "1.00", "spent_usd": "0.001", "next_step_reserved_usd": "0.001", "work_units": "1" }, "error": null, "cancel_requested": false, "withdrawn_at": null, "created_at": "2026-10-18T09:00:11.000000Z", "finished_at": null }, "quote_usd": "2.104652677739", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "410": { "$ref": "#/components/responses/Gone" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/TooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "$ref": "#/components/responses/Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCreate" }, "example": { "from_sequence": "1", "through_sequence": "4", "artifact_retention_days": 2, "deadline_seconds": 3600, "max_cost_usd": "1" } } } } } }, "/exports": { "get": { "operationId": "listExports", "tags": [ "Exports" ], "summary": "List exports", "description": "Returns the team's exports in creation order. Costs one work unit. Credentials: a secret key.", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "enum": [ "queued", "running", "succeeded", "failed", "canceled", "expired" ] } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "A page of exports.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportList" }, "example": { "data": [ { "id": "aex_Jm7CidaYcuEm2rbDR4wQE3", "object": "audit_export", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "state": "succeeded", "from_sequence": "1", "through_sequence": "4", "snapshot_tree_size": "4", "filters": { "indexed": [], "occurred_before": null, "occurred_from": null, "outcome": null, "received_before": null, "received_from": null, "source_kind": null }, "complete_ledger": true, "artifact_retention_days": "2", "deadline_at": "2026-10-18T10:00:11.000000Z", "progress": { "last_examined_sequence": "4", "scanned": "4", "matched": "4", "parts": 1, "bytes": "4956", "phase": "done" }, "manifest_artifact_id": "art_CgCD4iV1RVTfPqQTSbepAm", "cost": { "rate_version": "2026-10-18", "max_cost_usd": "1.00", "spent_usd": "0.003030699052", "next_step_reserved_usd": "0.00", "work_units": "3" }, "error": null, "cancel_requested": false, "withdrawn_at": null, "created_at": "2026-10-18T09:00:11.000000Z", "finished_at": "2026-10-18T09:00:30.000000Z" } ], "has_more": false, "next_cursor": null, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{export_id}": { "get": { "operationId": "getExport", "tags": [ "Exports" ], "summary": "Get an export", "description": "Returns the export's state, progress, and cost. Only a `succeeded` export has a manifest; its committed parts stay until their artifacts expire. Costs one work unit. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/ExportId" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "The export.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" }, "example": { "id": "aex_Jm7CidaYcuEm2rbDR4wQE3", "object": "audit_export", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "state": "succeeded", "from_sequence": "1", "through_sequence": "4", "snapshot_tree_size": "4", "filters": { "indexed": [], "occurred_before": null, "occurred_from": null, "outcome": null, "received_before": null, "received_from": null, "source_kind": null }, "complete_ledger": true, "artifact_retention_days": "2", "deadline_at": "2026-10-18T10:00:11.000000Z", "progress": { "last_examined_sequence": "4", "scanned": "4", "matched": "4", "parts": 1, "bytes": "4956", "phase": "done" }, "manifest_artifact_id": "art_CgCD4iV1RVTfPqQTSbepAm", "cost": { "rate_version": "2026-10-18", "max_cost_usd": "1.00", "spent_usd": "0.003030699052", "next_step_reserved_usd": "0.00", "work_units": "3" }, "error": null, "cancel_requested": false, "withdrawn_at": null, "created_at": "2026-10-18T09:00:11.000000Z", "finished_at": "2026-10-18T09:00:30.000000Z", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{export_id}/parts": { "get": { "operationId": "listExportParts", "tags": [ "Exports" ], "summary": "List an export's parts", "description": "Returns a page of the export's parts: their artifact IDs, SHA-256 checksums, sizes, and ranges. Get download URLs from Artifact storage. Costs one work unit. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/ExportId" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "A page of parts.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "`0.001`: one work unit.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartList" }, "example": { "data": [ { "ordinal": 0, "artifact_id": "art_4QhaL5RPcXmVDSkqjWkeBH", "sha256": "3d431bd5b2ed25ea3dcea37c86a47a4a40ea15c872b7733e3d92b857bf303960", "size_bytes": "4956", "lines": 4, "first_sequence": "1", "last_sequence": "4", "state": "ready" } ], "has_more": false, "next_cursor": null, "manifest_artifact_id": "art_CgCD4iV1RVTfPqQTSbepAm", "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/exports/{export_id}/cancel": { "post": { "operationId": "cancelExport", "tags": [ "Exports" ], "summary": "Cancel an export", "description": "Stops the export's future work. A step that already started is paid, and committed parts stay until they expire. Canceling a finished export answers with its state. Costs one work unit when the key can pay; otherwise it's included. Credentials: a secret key. Cancellation doesn't replay responses: each successful request costs a work unit when the key can pay, even if the export already finished.", "parameters": [ { "$ref": "#/components/parameters/ExportId" }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "202": { "description": "The export.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Motor-Operation-Cost-USD": { "description": "The actual request charge in USD: `0.001` for one work unit, or `0` when included lifecycle work applies.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportCanceled" }, "example": { "export": { "id": "aex_Jm7CidaYcuEm2rbDR4wQE3", "object": "audit_export", "ledger_id": "ald_LrB528wYtd4M8VJwtZikAt", "state": "canceled", "from_sequence": "1", "through_sequence": "4", "snapshot_tree_size": "4", "filters": { "indexed": [], "occurred_before": null, "occurred_from": null, "outcome": null, "received_before": null, "received_from": null, "source_kind": null }, "complete_ledger": true, "artifact_retention_days": "2", "deadline_at": "2026-10-18T10:00:11.000000Z", "progress": { "last_examined_sequence": "4", "scanned": "4", "matched": "4", "parts": 1, "bytes": "4956", "phase": "done" }, "manifest_artifact_id": null, "cost": { "rate_version": "2026-10-18", "max_cost_usd": "1.00", "spent_usd": "0.003030699052", "next_step_reserved_usd": "0.00", "work_units": "3" }, "error": { "code": "canceled", "message": "The export was canceled.", "retryable": false }, "cancel_requested": true, "withdrawn_at": null, "created_at": "2026-10-18T09:00:11.000000Z", "finished_at": "2026-10-18T09:00:30.000000Z" }, "usage": { "rate_version": "2026-10-18", "work_units": "1", "new_events": "0", "retained_byte_days": "0", "charged_usd": "0.001" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/Invalid" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" }, "example": {} } } } } }, "/keys": { "get": { "operationId": "listSigningKeys", "tags": [ "Proofs" ], "summary": "List the public signing keys", "description": "Returns every public key that ever signed a checkpoint or a control receipt, with its status and any compromise notice. It doesn't need a credential and it's free, so verifiers can fetch it without an account. Signatures under a compromised key may be untrustworthy.", "security": [], "parameters": [], "responses": { "200": { "description": "The public keys.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningKeys" }, "example": { "object": "audit_signing_keys", "data": [ { "key_id": "development-1", "algorithm": "ecdsa-p256-sha256", "public_key": "BOq_0Q-Pa7o46XwtfLCle4nFPCnHodhWlzROQCJi14sFQ3O2iHMYCbOYK2yU65yKrTUgsZFHgoWJYLOu5HB3SrI", "public_key_encoding": "sec1_uncompressed_base64url", "status": "active", "created_at": "2026-10-18T09:00:00.000000Z", "retired_at": null, "compromised_at": null } ], "checkpoint_prefix": "motor.audit.checkpoint.v1\n", "control_prefix": "motor.audit.control.v1\n", "signature_encoding": "base64url of the 64 bytes of r || s", "canonicalization": "motor-exact-json-v1" } } } } } } }, "/verifier": { "get": { "operationId": "getVerifier", "tags": [ "Proofs" ], "summary": "Download the offline verifier", "description": "Returns `audit_verify.py`, Motor's offline verifier of checkpoints, controls, canonical bytes, inclusion and consistency proofs, and exports. It needs Python 3 and the `cryptography` package, and it doesn't make network requests. Give it a public key file from `GET /keys` that you trust. It doesn't need a credential, and it's free.", "security": [], "parameters": [], "responses": { "200": { "description": "The verifier script.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment; filename=\"audit_verify.py\"`.", "schema": { "type": "string" } } }, "content": { "text/x-python": { "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A secret key, `motor_sk_...`, that may use Audit logs, or a client token, `motor_ct_...`, with an `audit_logs:append` or `audit_logs:read` scope." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 to 128 printable ASCII characters: a new value for each operation, and the same value when you retry it. A retry with the same credential replays the first response for 35 days.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "The ledger's ETag in quotes, such as `\"ald_...:2\"`. It names the configuration revision, which appends don't change.", "schema": { "type": "string" } }, "MotorMode": { "name": "Motor-Mode", "in": "header", "required": false, "description": "Audit logs is live-only: omit it or send `live`.", "schema": { "enum": [ "live" ] } }, "Limit": { "name": "limit", "in": "query", "required": false, "description": "1 to 100 items, 50 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, "Cursor": { "name": "cursor", "in": "query", "required": false, "description": "`next_cursor` of the previous page. It works for 15 minutes, with the same filters and credential.", "schema": { "type": "string" } }, "LedgerId": { "name": "ledger_id", "in": "path", "required": true, "schema": { "type": "string" } }, "EventId": { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string" } }, "ExportId": { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string" } }, "OperationId": { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string" } }, "IncludeCanonical": { "name": "include_canonical", "in": "query", "required": false, "description": "`true` adds `canonical_base64`, which counts against the page's 128 KiB.", "schema": { "enum": [ "true", "false" ] } } }, "responses": { "BadRequest": { "description": "The body isn't a JSON object, or an `Idempotency-Key` is missing.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "invalid_json", "message": "The request body isn't valid JSON. Expected a JSON value at byte 0.", "retryable": false } } } } }, "Unauthorized": { "description": "The key or the client token is missing, invalid, expired, or revoked.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked.", "retryable": false } } } } }, "PaymentRequired": { "description": "The team doesn't have a payment card, the key or the token reached its spending limit, or the work would pass `max_cost_usd`. Codes: `billing_required`, `spending_limit`, `max_cost_exceeded`, `token_budget_exceeded`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "max_cost_exceeded", "message": "This operation costs 0.002048576 USD, more than max_cost_usd allows (0.0001 USD). Raise max_cost_usd, or ask for less.", "retryable": false, "cost_usd": "0.002048576" } } } } }, "Forbidden": { "description": "The credential can't do this: a publishable key, a key without Audit logs, a client token outside its grant, or a suspended team.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "forbidden", "message": "Creating a ledger requires a secret API key (motor_sk_...) of the team, not a client token.", "retryable": false } } } } }, "NotFound": { "description": "The resource doesn't exist for your team or your token's grant. A missing checkpoint is `checkpoint_not_found`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "not_found", "message": "The ledger doesn't exist.", "retryable": false } } } } }, "Conflict": { "description": "A conflict. Codes: `ledger_sealed`, `event_conflict`, `evidence_expiring`, `evidence_unavailable`, `snapshot_invalidated`, `capacity_exceeded`, `idempotency_conflict`, `request_in_progress`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "ledger_sealed", "message": "The ledger is sealed, so it accepts no more events. Create another ledger for new events.", "retryable": false, "resource_id": "ald_LrB528wYtd4M8VJwtZikAt" } } } } }, "Gone": { "description": "The ledger's paid retention ended: `ledger_expired`. Read the ledger for its deletion status.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "ledger_expired", "message": "The ledger's paid retention ended at 2026-11-17T09:00:00.000Z, so its events can't be read, proven, exported, or appended. Read the ledger for its deletion status.", "retryable": false, "resource_id": "ald_LrB528wYtd4M8VJwtZikAt" } } } } }, "PreconditionFailed": { "description": "The `If-Match` revision is stale: `stale_revision`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "stale_revision", "message": "The ledger's configuration changed since you read it. Read it again and retry with its new ETag.", "retryable": false, "resource_id": "ald_LrB528wYtd4M8VJwtZikAt" } } } } }, "TooLarge": { "description": "The body is too large: 512 KiB for an append, and 64 KiB otherwise.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "body_too_large", "message": "The request body must be at most 524288 bytes.", "retryable": false } } } } }, "UnsupportedMediaType": { "description": "The body isn't `application/json`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "unsupported_media_type", "message": "Send the request body as application/json.", "retryable": false } } } } }, "Invalid": { "description": "A field, a query parameter, the cursor (`invalid_cursor`), or `Motor-Mode` (`unsupported_mode`) isn't valid.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "invalid_field", "message": "`events[0].outcome` must be one of attempted, succeeded, failed, denied, unknown.", "retryable": false } } } } }, "PreconditionRequired": { "description": "The request needs `If-Match`: `precondition_required`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "precondition_required", "message": "Send the ETag of the resource in the If-Match header, such as If-Match: \"ff:ffe_...:7\". Read the resource to get its current ETag.", "retryable": false } } } } }, "RateLimited": { "description": "Too many requests: the team's requests or appended events, or 2 feed reads a second for each ledger. Retry after `Retry-After`.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests. Retry after 1 seconds.", "retryable": true, "retry_after_seconds": 1 } } } } }, "Unavailable": { "description": "Motor can't sign checkpoints (`signing_unavailable`), a ledger is under an integrity check (`integrity_check`), or the billing month is closing. Retry later.", "headers": { "Request-Id": { "description": "Motor's ID of the request, for support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "error": { "code": "signing_unavailable", "message": "Motor can't sign checkpoints right now, so it doesn't accept new events. Motor didn't append or charge anything. Retry later.", "retryable": true, "retry_after_seconds": 60 } } } } } }, "schemas": { "Time": { "type": "string", "description": "A time in RFC 3339, UTC, to the microsecond, such as `2026-10-18T09:00:00.000000Z`.", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z$" }, "Money": { "type": "string", "description": "An exact amount of US dollars as a decimal string, such as `0.001048576`.", "pattern": "^\\d+\\.\\d{2,12}$" }, "Count": { "type": "string", "description": "An unsigned integer returned as a decimal string, such as `1024`, to avoid loss of precision in JSON clients.", "pattern": "^(0|[1-9][0-9]*)$" }, "Hash": { "type": "string", "description": "A SHA-256 hash in lowercase hexadecimal.", "pattern": "^[0-9a-f]{64}$" }, "Metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 256 }, "maxProperties": 16, "description": "At most 16 string pairs: keys of 1 to 64 UTF-8 bytes, values of at most 256, and at most 2 KiB in all. Metadata never changes." }, "Problem": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A stable code for programs, such as `ledger_sealed`." }, "message": { "type": "string", "description": "What happened and what to do, for people. It never contains an event's content." }, "retryable": { "type": "boolean", "description": "Whether the same request can work later. A `429` or `503` is retryable." }, "retry_after_seconds": { "type": "integer", "description": "The seconds to wait before a retry, when Motor knows them.", "minimum": 0 }, "resource_id": { "type": "string", "description": "The resource that the problem concerns." }, "limit": { "type": "string", "description": "The capacity limit reached, such as `max_events`." }, "field": { "type": "string", "description": "The request field that caused the error, such as `cursor`." }, "cost_usd": { "$ref": "#/components/schemas/Money", "description": "For `max_cost_exceeded`: what the operation costs." }, "references": { "type": "array", "items": { "type": "object", "properties": { "artifact_id": { "type": "string" } }, "additionalProperties": false, "required": [ "artifact_id" ] }, "description": "For `evidence_expiring`: at most 10 retained artifacts that expire before the new expiry." } }, "additionalProperties": true, "required": [ "code", "message", "retryable" ] } }, "additionalProperties": false, "required": [ "error" ], "description": "An error. The `error` object may have more members, such as `cost_usd` of `max_cost_exceeded` or `references` of `evidence_expiring`." }, "Usage": { "type": "object", "properties": { "rate_version": { "type": "string", "description": "The rates that priced the request." }, "work_units": { "$ref": "#/components/schemas/Count", "description": "Work units: $0.001 each." }, "new_events": { "$ref": "#/components/schemas/Count", "description": "New customer events: $0.000005 each. Duplicates don't count." }, "retained_byte_days": { "$ref": "#/components/schemas/Count", "description": "Prepaid retention in byte-days: $1 per GB-month of 30 days." }, "charged_usd": { "$ref": "#/components/schemas/Money", "description": "What the request charged in all." } }, "additionalProperties": false, "required": [ "rate_version", "work_units", "new_events", "retained_byte_days", "charged_usd" ], "description": "The meters that the request used, and its exact charge." }, "Checkpoint": { "type": "object", "properties": { "tree_size": { "$ref": "#/components/schemas/Count" }, "root_hash": { "$ref": "#/components/schemas/Hash" }, "issued_at": { "$ref": "#/components/schemas/Time" }, "key_id": { "type": "string", "description": "The ID of the signing key. Get its public key from `GET /keys`." }, "algorithm": { "const": "ecdsa-p256-sha256" }, "signed_body": { "type": "string", "description": "The exact canonical JSON that Motor signed: `{version, ledger_id, tree_size, root_hash, issued_at, key_id}` in `motor-exact-json-v1`. The signed message is `motor.audit.checkpoint.v1\\n` followed by these bytes." }, "signature": { "type": "string", "description": "The base64url of the 64 bytes of `r || s`, not DER." } }, "additionalProperties": false, "required": [ "tree_size", "root_hash", "issued_at", "key_id", "algorithm", "signed_body", "signature" ], "description": "A signed checkpoint: the root of the ledger's tree at a size." }, "ControlReceipt": { "type": "object", "properties": { "kind": { "enum": [ "seal", "extension", "erasure", "deletion", "expiry" ] }, "index": { "type": "integer", "description": "The receipt's index in the ledger, from 0 to 255.", "minimum": 0, "maximum": 255 }, "issued_at": { "$ref": "#/components/schemas/Time" }, "key_id": { "type": "string" }, "algorithm": { "const": "ecdsa-p256-sha256" }, "signed_body": { "type": "string", "description": "The exact canonical JSON that Motor signed, after the prefix `motor.audit.control.v1\\n`. It names the ledger, the revisions and expiries before and after, the tree size, the operation's ID, and for an erasure the reason code, `event_count`, and `event_ids_sha256`: the SHA-256 of the canonical JSON array of the operation's `event_ids`, in order." }, "signature": { "type": "string", "description": "The base64url of the 64 bytes of `r || s`." } }, "additionalProperties": false, "required": [ "kind", "index", "issued_at", "key_id", "algorithm", "signed_body", "signature" ], "description": "A signed receipt of a change to the ledger's configuration or contents." }, "Bounds": { "type": "object", "properties": { "max_event_bytes": { "type": "integer" }, "max_batch_events": { "type": "integer" }, "max_targets": { "type": "integer" }, "max_evidence": { "type": "integer" }, "max_page_items": { "type": "integer" }, "max_page_bytes": { "type": "integer" }, "max_candidates_per_page": { "$ref": "#/components/schemas/Count" }, "max_extension_horizon_days": { "$ref": "#/components/schemas/Count" }, "max_controls": { "type": "integer" }, "max_retained_artifacts": { "type": "integer" } }, "additionalProperties": false, "required": [ "max_event_bytes", "max_batch_events", "max_targets", "max_evidence", "max_page_items", "max_page_bytes", "max_candidates_per_page", "max_extension_horizon_days", "max_controls", "max_retained_artifacts" ], "description": "Fixed protocol limits. Support cannot raise them." }, "Deletion": { "anyOf": [ { "type": "object", "properties": { "reason_code": { "enum": [ "customer_request", "expired", "account_closure" ] }, "requested_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "operation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deleted_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "reason_code", "requested_at", "operation_id", "deleted_at" ] }, { "type": "null" } ] }, "Ledger": { "type": "object", "properties": { "id": { "type": "string", "description": "The ledger's ID, `ald_...`." }, "object": { "const": "audit_ledger" }, "state": { "enum": [ "open", "sealed", "expired", "deleting", "deleted" ] }, "created_at": { "$ref": "#/components/schemas/Time" }, "expires_at": { "$ref": "#/components/schemas/Time", "description": "The end of the paid retention of the ledger and of every event in it." }, "remaining_seconds": { "$ref": "#/components/schemas/Count" }, "remaining_days": { "$ref": "#/components/schemas/Count", "description": "The whole days that remain, rounded up." }, "revision": { "$ref": "#/components/schemas/Count", "description": "The configuration revision. Seals and extensions advance it; appends don't." }, "etag": { "type": "string", "description": "`{id}:{revision}`, for `If-Match`." }, "deletion": { "$ref": "#/components/schemas/Deletion" }, "name": { "type": "string", "minLength": 0, "maxLength": 128 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "retention_days": { "$ref": "#/components/schemas/Count", "description": "The days that the creation paid." }, "sealed_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "tree_size": { "$ref": "#/components/schemas/Count", "description": "The sequence of the newest event." }, "root_hash": { "$ref": "#/components/schemas/Hash" }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/Checkpoint" }, { "type": "null" } ] }, "events": { "$ref": "#/components/schemas/Count", "description": "Retained events, erased tombstones included." }, "billable_bytes": { "$ref": "#/components/schemas/Count", "description": "1 MiB for the ledger and 8 KiB for each retained event." }, "paid_through": { "$ref": "#/components/schemas/Time" }, "erasure_generation": { "$ref": "#/components/schemas/Count", "description": "One more for each erasure. Older query and export snapshots stop working." }, "retained_artifacts": { "type": "integer", "description": "Distinct artifacts that the ledger's events retain: at most 100.", "minimum": 0 }, "controls": { "type": "object", "properties": { "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 } }, "additionalProperties": false, "required": [ "used", "remaining" ], "description": "Control receipts: 256 for each ledger. The last one is for its deletion." }, "bounds": { "$ref": "#/components/schemas/Bounds" }, "cost": { "type": "object", "properties": { "rate_version": { "type": "string" }, "charged_usd": { "$ref": "#/components/schemas/Money" } }, "additionalProperties": false, "required": [ "rate_version", "charged_usd" ], "description": "What the ledger's own operations charged." }, "usage": { "$ref": "#/components/schemas/Usage" }, "control_receipt": { "$ref": "#/components/schemas/ControlReceipt" } }, "additionalProperties": false, "required": [ "id", "object", "state", "created_at", "expires_at", "remaining_seconds", "remaining_days", "revision", "etag", "deletion" ], "description": "A ledger. A ledger that's being deleted shows only its state and its deletion. Responses add `usage`, and seals and extensions add `control_receipt`." }, "LedgerCreate": { "type": "object", "properties": { "name": { "type": "string", "description": "1 to 128 UTF-8 bytes. It never changes.", "minLength": 1, "maxLength": 128 }, "retention_days": { "type": "integer", "description": "1 to 365, 30 by default. Every event in the ledger shares its expiry.", "minimum": 1, "maximum": 365 }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "max_cost_usd": { "type": "string", "description": "The most that the creation may cost, such as `\"0.01\"`." } }, "additionalProperties": false, "required": [ "name" ] }, "LedgerList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ledger" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "data", "has_more", "next_cursor", "usage" ] }, "EventInput": { "type": "object", "properties": { "client_event_id": { "type": "string", "description": "Your ID of the event: 1 to 128 printable ASCII characters, unique in the ledger for its whole life. A repeat with the same content returns the first receipt.", "minLength": 1, "maxLength": 128 }, "action": { "type": "string", "description": "What the actor did, such as `payment.submit`: 1 to 128 of `A-Z`, `a-z`, `0-9`, `_`, `.`, `:`, and `-`.", "pattern": "^[A-Za-z0-9_.:-]{1,128}$" }, "actor": { "type": "object", "properties": { "type": { "enum": [ "agent", "user", "service", "system" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 }, "on_behalf_of": { "type": "object", "properties": { "type": { "enum": [ "agent", "user", "service", "system" ] }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false, "required": [ "type", "id" ] } }, "additionalProperties": false, "required": [ "type", "id" ], "description": "Who acted, and for whom. An assertion: Motor authenticates only the submitter." }, "targets": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1, "maxLength": 128 }, "id": { "type": "string", "minLength": 1, "maxLength": 128 } }, "additionalProperties": false, "required": [ "type", "id" ], "description": "A resource that the action concerns." }, "minItems": 1, "maxItems": 8 }, "outcome": { "enum": [ "attempted", "succeeded", "failed", "denied", "unknown" ], "description": "A later outcome is another event with `parent_event_id`, not an edit." }, "occurred_at": { "type": "string", "description": "When the action happened, in RFC 3339. Motor stores it in UTC microseconds, from 1970 through 5 minutes after it received the event." }, "run_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "trace_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "span_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "parent_event_id": { "type": "string", "description": "An existing event of the ledger.", "minLength": 1, "maxLength": 128 }, "parent_client_event_id": { "type": "string", "description": "An earlier event of the same request, by its `client_event_id`. Send it or `parent_event_id`, not both.", "minLength": 1, "maxLength": 128 }, "authority": { "type": "object", "properties": { "kind": { "enum": [ "key", "delegation", "approval", "policy", "external" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 256 }, "policy_version": { "type": "string", "minLength": 1, "maxLength": 128 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 16 } }, "additionalProperties": false, "required": [ "kind", "reference" ], "description": "The authority that the actor claimed. A claim, never a bearer token or a verified approval." }, "cost": { "type": "object", "properties": { "amount": { "type": "string", "description": "A nonnegative decimal string: at most 12 fractional digits and 18 digits in all.", "pattern": "^\\d+(\\.\\d+)?$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "kind": { "enum": [ "estimated", "actual" ] } }, "additionalProperties": false, "required": [ "amount", "currency", "kind" ], "description": "The cost that the customer reported. Audit logs never invoices or converts it." }, "evidence": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "artifact_id": { "type": "string" }, "mode": { "enum": [ "pointer", "retain" ] } }, "additionalProperties": false, "required": [ "artifact_id", "mode" ], "description": "A Motor artifact of your team. `retain` keeps it from deletion until the ledger expires." }, { "type": "object", "properties": { "uri": { "type": "string", "description": "An `https` URI of at most 1,024 bytes, without credentials or a fragment. Motor never fetches it.", "maxLength": 1024 }, "sha256": { "$ref": "#/components/schemas/Hash" } }, "additionalProperties": false, "required": [ "uri" ] } ] }, "maxItems": 8 }, "attributes": { "type": "object", "description": "Your JSON object. Numbers must be JSON-safe integers, and nulls and credential fields, such as `password` or `api_key`, are refused at any depth. Motor doesn't index attributes." } }, "additionalProperties": false, "required": [ "client_event_id", "action", "actor", "targets", "outcome", "occurred_at" ], "description": "A customer event. The normalized event can be at most 4,096 bytes in `motor-exact-json-v1`, and nest at most 8 deep." }, "AppendRequest": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventInput" }, "minItems": 1, "maxItems": 100 }, "max_cost_usd": { "type": "string", "description": "The most that the append may cost. The default is the cost of the request if every event is new." } }, "additionalProperties": false, "required": [ "events" ] }, "Receipt": { "type": "object", "properties": { "event_id": { "type": "string" }, "sequence": { "$ref": "#/components/schemas/Count" }, "leaf_hash": { "$ref": "#/components/schemas/Hash" }, "duplicate": { "type": "boolean", "description": "Whether the event already existed with the same content. A duplicate isn't appended again." }, "payload_erased": { "type": "boolean", "description": "Whether an erasure removed the existing event's payload." } }, "additionalProperties": false, "required": [ "event_id", "sequence", "leaf_hash", "duplicate", "payload_erased" ] }, "AppendReceipt": { "type": "object", "properties": { "object": { "const": "audit_append_receipt" }, "ledger_id": { "type": "string" }, "receipts": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" }, "description": "One receipt for each event, in request order." }, "tree_size": { "$ref": "#/components/schemas/Count" }, "checkpoint": { "anyOf": [ { "$ref": "#/components/schemas/Checkpoint" }, { "type": "null" } ], "description": "The signed checkpoint that covers the batch." }, "paid_through": { "$ref": "#/components/schemas/Time" }, "remaining_seconds": { "$ref": "#/components/schemas/Count" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "object", "ledger_id", "receipts", "tree_size", "checkpoint", "paid_through", "remaining_seconds", "usage" ] }, "Snapshot": { "type": "object", "properties": { "artifact_id": { "type": "string" }, "mode": { "enum": [ "pointer", "retain" ] }, "sha256": { "anyOf": [ { "$ref": "#/components/schemas/Hash" }, { "type": "null" } ] }, "digest_status": { "enum": [ "verified", "unavailable" ], "description": "`unavailable` for a multipart artifact, whose composite checksum isn't a digest of the whole object." }, "size_bytes": { "$ref": "#/components/schemas/Count" } }, "additionalProperties": false, "required": [ "artifact_id", "mode", "sha256", "digest_status", "size_bytes" ], "description": "Artifact metadata recorded with the event. Audit logs does not read the file contents." }, "Source": { "type": "object", "properties": { "kind": { "enum": [ "customer", "motor" ] }, "service": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "operation": { "type": "string" } }, "additionalProperties": false, "required": [ "kind" ], "description": "Who recorded the event. Only Motor's own services can record `motor`." }, "Submitter": { "type": "object", "properties": { "key_id": { "type": "string" }, "credential": { "enum": [ "secret_key", "client_token", "motor_service" ] }, "token_id": { "type": "string" }, "principal_id": { "type": "string", "description": "The stable ID of the key's service account or person." } }, "additionalProperties": false, "required": [ "key_id", "credential" ], "description": "The authenticated submitter, by stable IDs." }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "audit_event" }, "ledger_id": { "type": "string" }, "sequence": { "$ref": "#/components/schemas/Count" }, "leaf_hash": { "$ref": "#/components/schemas/Hash" }, "received_at": { "$ref": "#/components/schemas/Time" }, "source_kind": { "enum": [ "customer", "motor" ] }, "payload_erased": { "type": "boolean", "description": "Whether an erasure removed the payload. A tombstone keeps only its sequence, ID, leaf hash, and receipt time." }, "source": { "$ref": "#/components/schemas/Source" }, "submitter": { "$ref": "#/components/schemas/Submitter" }, "parent_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } }, "event": { "type": "object", "description": "The normalized customer event." }, "canonical_base64": { "type": "string", "description": "The canonical envelope's exact bytes in Base64, with `include_canonical=true`. Its leaf hash is `SHA-256(0x00 || bytes)`." }, "erased_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "erasure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "id", "object", "ledger_id", "sequence", "leaf_hash", "received_at", "source_kind", "payload_erased" ], "description": "An event, or its tombstone after an erasure. Every claim in `event` is the customer's assertion." }, "EventList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string", "description": "Works for 15 minutes from the first page, with the same filters and credential." }, { "type": "null" } ] }, "snapshot_tree_size": { "$ref": "#/components/schemas/Count", "description": "The tree size that the first page captured. Later pages don't see later appends." }, "last_examined_sequence": { "$ref": "#/components/schemas/Count", "description": "The next page starts after it. It's never past a match that the page didn't return." }, "scanned": { "$ref": "#/components/schemas/Count", "description": "The candidates that the page examined: at most 1,000." }, "access_path": { "enum": [ "run", "trace", "actor", "target", "action", "sequence" ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "data", "has_more", "next_cursor", "snapshot_tree_size", "last_examined_sequence", "scanned", "access_path", "usage" ] }, "LatestCheckpoint": { "type": "object", "properties": { "object": { "const": "audit_checkpoint" }, "ledger_id": { "type": "string" }, "tree_size": { "$ref": "#/components/schemas/Count" }, "root_hash": { "$ref": "#/components/schemas/Hash" }, "issued_at": { "$ref": "#/components/schemas/Time" }, "key_id": { "type": "string", "description": "The ID of the signing key. Get its public key from `GET /keys`." }, "algorithm": { "const": "ecdsa-p256-sha256" }, "signed_body": { "type": "string", "description": "The exact canonical JSON that Motor signed: `{version, ledger_id, tree_size, root_hash, issued_at, key_id}` in `motor-exact-json-v1`. The signed message is `motor.audit.checkpoint.v1\\n` followed by these bytes." }, "signature": { "type": "string", "description": "The base64url of the 64 bytes of `r || s`, not DER." }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "object", "ledger_id", "tree_size", "root_hash", "issued_at", "key_id", "algorithm", "signed_body", "signature", "usage" ] }, "InclusionProof": { "type": "object", "properties": { "object": { "const": "audit_inclusion_proof" }, "ledger_id": { "type": "string" }, "event_id": { "type": "string" }, "sequence": { "$ref": "#/components/schemas/Count" }, "leaf_index": { "$ref": "#/components/schemas/Count", "description": "The sequence minus one." }, "tree_size": { "$ref": "#/components/schemas/Count" }, "leaf_hash": { "$ref": "#/components/schemas/Hash" }, "path": { "type": "array", "items": { "$ref": "#/components/schemas/Hash" }, "description": "The audit path of RFC 9162, section 2.1.3, bottom first." }, "checkpoint": { "$ref": "#/components/schemas/Checkpoint" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "object", "ledger_id", "event_id", "sequence", "leaf_index", "tree_size", "leaf_hash", "path", "checkpoint", "usage" ] }, "ConsistencyProof": { "type": "object", "properties": { "object": { "const": "audit_consistency_proof" }, "ledger_id": { "type": "string" }, "from_size": { "$ref": "#/components/schemas/Count" }, "to_size": { "$ref": "#/components/schemas/Count" }, "proof": { "type": "array", "items": { "$ref": "#/components/schemas/Hash" }, "description": "The consistency proof of RFC 9162, section 2.1.4. It's empty when `from_size` is 0 or equals `to_size`." }, "from_checkpoint": { "$ref": "#/components/schemas/Checkpoint" }, "to_checkpoint": { "$ref": "#/components/schemas/Checkpoint" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "object", "ledger_id", "from_size", "to_size", "proof", "from_checkpoint", "to_checkpoint", "usage" ] }, "Evidence": { "type": "object", "properties": { "artifact_id": { "type": "string" }, "references": { "type": "integer", "description": "The live events that retain it.", "minimum": 1 }, "retained_until": { "$ref": "#/components/schemas/Time" }, "artifact_status": { "type": "string", "description": "The artifact's state in Artifact storage, such as `ready`." }, "artifact_expires_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ], "description": "When Artifact storage deletes the artifact, or `null` if it doesn't expire." }, "created_at": { "$ref": "#/components/schemas/Time" } }, "additionalProperties": false, "required": [ "artifact_id", "references", "retained_until", "artifact_status", "artifact_expires_at", "created_at" ] }, "EvidenceList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "data", "has_more", "next_cursor", "usage" ] }, "Empty": { "type": "object", "properties": {}, "additionalProperties": false, "required": [], "description": "An empty object." }, "Extension": { "type": "object", "properties": { "days": { "type": "integer", "description": "Days to add: 1 to 365, ending at most 365 days from now.", "minimum": 1, "maximum": 365 }, "max_cost_usd": { "type": "string", "description": "Required: the most that the extension may cost." } }, "additionalProperties": false, "required": [ "days", "max_cost_usd" ] }, "ErasureCreate": { "type": "object", "properties": { "event_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "reason_code": { "enum": [ "customer_request", "sensitive_data" ] } }, "additionalProperties": false, "required": [ "event_ids", "reason_code" ] }, "Operation": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "audit_operation" }, "kind": { "enum": [ "erasure", "deletion", "expiry" ] }, "state": { "enum": [ "pending", "running", "succeeded", "failed" ] }, "reason_code": { "type": "string" }, "ledger_id": { "type": "string" }, "event_ids": { "type": "array", "items": { "type": "string" }, "description": "The random IDs of an erasure's events." }, "phase": { "type": "string" }, "counts": { "type": "object", "properties": { "events": { "$ref": "#/components/schemas/Count" }, "erased": { "$ref": "#/components/schemas/Count" }, "removed_rows": { "$ref": "#/components/schemas/Count" } }, "additionalProperties": false, "required": [ "events", "erased", "removed_rows" ] }, "retry": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "attempts", "error_code" ] }, "created_at": { "$ref": "#/components/schemas/Time" }, "updated_at": { "$ref": "#/components/schemas/Time" }, "finished_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "deadline_at": { "$ref": "#/components/schemas/Time" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "id", "object", "kind", "state", "reason_code", "ledger_id", "event_ids", "phase", "counts", "retry", "created_at", "updated_at", "finished_at", "deadline_at" ], "description": "Accepted cleanup: an erasure or a deletion. It never shows erased content." }, "OperationAccepted": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/Operation" }, "control_receipt": { "$ref": "#/components/schemas/ControlReceipt" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "operation", "usage" ] }, "ExportFilters": { "type": "object", "properties": { "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "target_type": { "type": "string" }, "target_id": { "type": "string" }, "action": { "type": "string" }, "run_id": { "type": "string" }, "trace_id": { "type": "string" }, "outcome": { "type": "string" }, "source_kind": { "type": "string" }, "received_from": { "type": "string" }, "received_before": { "type": "string" }, "occurred_from": { "type": "string" }, "occurred_before": { "type": "string" } }, "additionalProperties": false, "description": "The same filters used to list events. Send actor_type with actor_id, and target_type with target_id." }, "ExportCreate": { "type": "object", "properties": { "from_sequence": { "$ref": "#/components/schemas/Count", "description": "1 by default." }, "through_sequence": { "$ref": "#/components/schemas/Count", "description": "The tree size by default." }, "filters": { "$ref": "#/components/schemas/ExportFilters" }, "artifact_retention_days": { "type": "integer", "description": "1 to 30, 1 by default. It can't outlast the ledger's expiry.", "minimum": 1, "maximum": 30 }, "max_cost_usd": { "type": "string", "description": "Required: the most that the export's work and artifacts may cost." }, "deadline_seconds": { "type": "integer", "description": "60 to 86,400, 3,600 by default.", "minimum": 60, "maximum": 86400 } }, "additionalProperties": false, "required": [ "max_cost_usd" ] }, "StoredFilters": { "type": "object", "properties": { "indexed": { "type": "array", "items": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 } }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_kind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "received_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occurred_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "occurred_before": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "indexed", "outcome", "source_kind", "received_from", "received_before", "occurred_from", "occurred_before" ], "description": "The export's normalized filters." }, "Export": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "audit_export" }, "ledger_id": { "type": "string" }, "state": { "enum": [ "queued", "running", "succeeded", "failed", "canceled", "expired" ] }, "from_sequence": { "$ref": "#/components/schemas/Count" }, "through_sequence": { "$ref": "#/components/schemas/Count" }, "snapshot_tree_size": { "$ref": "#/components/schemas/Count" }, "filters": { "$ref": "#/components/schemas/StoredFilters" }, "complete_ledger": { "type": "boolean", "description": "Whether the export covers the whole ledger, unfiltered, from 1 to its snapshot. Then the lines rebuild the signed root with an empty range proof. A filtered export makes no completeness claim about matches; its lines still authenticate." }, "artifact_retention_days": { "$ref": "#/components/schemas/Count" }, "deadline_at": { "$ref": "#/components/schemas/Time" }, "progress": { "type": "object", "properties": { "last_examined_sequence": { "$ref": "#/components/schemas/Count" }, "scanned": { "$ref": "#/components/schemas/Count" }, "matched": { "$ref": "#/components/schemas/Count" }, "parts": { "type": "integer", "minimum": 0 }, "bytes": { "$ref": "#/components/schemas/Count" }, "phase": { "type": "string" } }, "additionalProperties": false, "required": [ "last_examined_sequence", "scanned", "matched", "parts", "bytes", "phase" ] }, "manifest_artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cost": { "type": "object", "properties": { "rate_version": { "type": "string" }, "max_cost_usd": { "$ref": "#/components/schemas/Money" }, "spent_usd": { "$ref": "#/components/schemas/Money" }, "next_step_reserved_usd": { "$ref": "#/components/schemas/Money" }, "work_units": { "$ref": "#/components/schemas/Count" } }, "additionalProperties": false, "required": [ "rate_version", "max_cost_usd", "spent_usd", "next_step_reserved_usd", "work_units" ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "additionalProperties": false, "required": [ "code", "message", "retryable" ] }, { "type": "null" } ] }, "cancel_requested": { "type": "boolean" }, "withdrawn_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "created_at": { "$ref": "#/components/schemas/Time" }, "finished_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "id", "object", "ledger_id", "state", "from_sequence", "through_sequence", "snapshot_tree_size", "filters", "complete_ledger", "artifact_retention_days", "deadline_at", "progress", "manifest_artifact_id", "cost", "error", "cancel_requested", "withdrawn_at", "created_at", "finished_at" ] }, "ExportAccepted": { "type": "object", "properties": { "export": { "$ref": "#/components/schemas/Export" }, "quote_usd": { "$ref": "#/components/schemas/Money", "description": "The upper bound of the export's cost at its limits." }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "export", "quote_usd", "usage" ] }, "ExportCanceled": { "type": "object", "properties": { "export": { "$ref": "#/components/schemas/Export" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "export", "usage" ] }, "ExportList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Export" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "data", "has_more", "next_cursor", "usage" ] }, "Part": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0 }, "artifact_id": { "type": "string" }, "sha256": { "$ref": "#/components/schemas/Hash" }, "size_bytes": { "$ref": "#/components/schemas/Count" }, "lines": { "type": "integer", "minimum": 0 }, "first_sequence": { "$ref": "#/components/schemas/Count" }, "last_sequence": { "$ref": "#/components/schemas/Count" }, "state": { "enum": [ "prepared", "written", "verifying", "ready", "withdrawn" ] } }, "additionalProperties": false, "required": [ "ordinal", "artifact_id", "sha256", "size_bytes", "lines", "first_sequence", "last_sequence", "state" ], "description": "A part: an NDJSON artifact of at most 4 MiB." }, "PartList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Part" } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manifest_artifact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "usage": { "$ref": "#/components/schemas/Usage" } }, "additionalProperties": false, "required": [ "data", "has_more", "next_cursor", "manifest_artifact_id", "usage" ] }, "SigningKey": { "type": "object", "properties": { "key_id": { "type": "string" }, "algorithm": { "const": "ecdsa-p256-sha256" }, "public_key": { "type": "string", "description": "The uncompressed SEC 1 point in base64url." }, "public_key_encoding": { "const": "sec1_uncompressed_base64url" }, "status": { "enum": [ "active", "retired", "compromised" ] }, "created_at": { "$ref": "#/components/schemas/Time" }, "retired_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "compromised_at": { "anyOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] } }, "additionalProperties": false, "required": [ "key_id", "algorithm", "public_key", "public_key_encoding", "status", "created_at", "retired_at", "compromised_at" ] }, "SigningKeys": { "type": "object", "properties": { "object": { "const": "audit_signing_keys" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SigningKey" } }, "checkpoint_prefix": { "const": "motor.audit.checkpoint.v1\n" }, "control_prefix": { "const": "motor.audit.control.v1\n" }, "signature_encoding": { "type": "string" }, "canonicalization": { "const": "motor-exact-json-v1" } }, "additionalProperties": false, "required": [ "object", "data", "checkpoint_prefix", "control_prefix", "signature_encoding", "canonicalization" ] } } } }