{"openapi":"3.1.0","info":{"title":"Audit Log API","version":"0.1.0","description":"The account's auditable history: who did what, to what, and when. The service owns no journal and no commands — like accounting, it is a fold-only consumer. It reads the inventory, purchasing, fulfillment, CRM, onboarding and auth journals (and any app's it is pointed at) forward for the caller's tenant (forwarding the caller's token, so it can never see more than the caller can), folds each event into a uniform audit entry, and keeps the entries indexed by time, actor, action and entity so a page is a query, never a replay. Because the trail is derived from append-only logs, it cannot be tampered with through this API or any other: entries are never written, updated, or deleted here."},"paths":{"/audit":{"get":{"tags":["audit"],"operationId":"audit.list","parameters":[{"name":"actor","in":"query","schema":{"type":"string"},"required":false},{"name":"action","in":"query","schema":{"type":"string"},"required":false},{"name":"entityId","in":"query","schema":{"type":"string"},"required":false,"example":"psn_01a1588a-0c41-7d2e-9a10-3b5c6d7e8f90"},{"name":"service","in":"query","schema":{"type":"string"},"required":false},{"name":"from","in":"query","schema":{"type":"string"},"required":false,"example":"2026-10-20T00:00:00.000Z"},{"name":"to","in":"query","schema":{"type":"string"},"required":false,"example":"2026-10-20T09:10:00.000Z"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"50"},{"name":"cursor","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"AuditPage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditPageEncoded"},"examples":{"contract":{"summary":"audit.list","value":{"entries":[{"eventId":"evt_01a1588a-0c41-7d2e-9a10-000000000042","txId":"tx_01a1588a-0c41-7d2e-9a10-000000000042","tenantId":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d","service":"crm-manager","sequence":42,"action":"crm.company-contact-set","actor":{"_tag":"user","id":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"},"occurredAt":"2026-10-20T09:06:00.000Z","entity":{"kind":"person","id":"psn_01a1588a-0c41-7d2e-9a10-3b5c6d7e8f90"},"related":[{"kind":"company","id":"cmp_01a1588a-1f02-7a3b-8c4d-5e6f7a8b9c0d"}],"detail":{"companyId":"cmp_01a1588a-1f02-7a3b-8c4d-5e6f7a8b9c0d","personId":"psn_01a1588a-0c41-7d2e-9a10-3b5c6d7e8f90","title":"Purchasing manager","main":true}},{"eventId":"evt_01a1588a-0c41-7d2e-9a10-000000000041","txId":"tx_01a1588a-0c41-7d2e-9a10-000000000041","tenantId":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d","service":"crm-manager","sequence":41,"action":"crm.person-created","actor":{"_tag":"user","id":"usr_01a15889-fa80-7b11-8c22-3d4e5f6a7b8c"},"occurredAt":"2026-10-20T09:00:00.000Z","entity":{"kind":"person","id":"psn_01a1588a-0c41-7d2e-9a10-3b5c6d7e8f90"},"related":[],"detail":{"reference":"checkout:5521","personId":"psn_01a1588a-0c41-7d2e-9a10-3b5c6d7e8f90","emailKey":"593c82fc1f2944d758cdd3ba99d3846467ec3417f394e5f47c7410b939a0a83c","profile":"v1.QmFzZTY0IGNpcGhlcnRleHQgb2YgdGhlIHByb2ZpbGU=","tags":["trade"],"roles":["customer"],"taxExempt":false,"emailMarketing":"subscribed","smsMarketing":"not-subscribed"}}],"unavailable":[]}}}}}},"400":{"description":"AuditCursorInvalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditCursorInvalidEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Every recorded action on the caller's account, newest first — the audit trail. Each entry names the action (the event tag), the actor who caused it (`user` for a person, `system` for a worker such as webhook ingestion or the reconciliation sweep, `app` for an installed app acting under its own token), the entity it concerns, when it happened, and the originating service and journal sequence. Entries are derived from the services' append-only journals, so the trail is immutable by construction: nothing here can be edited or deleted, and a correction appears as a new entry. Filters (all optional, combined with AND): `actor` matches an actor id (or `user`/`system`/`app` for a whole class), `action` is an exact event tag or a prefix like `inventory.`, `entityId` is a document/SKU/party id (an order's facts match the parties the order named), `service` names a journal, `from`/`to` bound `occurredAt` as [from, to). The trail is paged, back to the account's first fact: `limit` is the page size (default 200, max 1000), and `next`, while older entries remain, is the `cursor` for the next page — a cursor rather than an offset, so facts landing mid-read never shift a page; 400 `AuditCursorInvalid` for a cursor this service did not issue. Every request first reads each journal forward from where the service last read it, with the caller's own token, so the trail is current and a journal that refuses the caller (or cannot be reached) is named in `unavailable` and its facts are left out. Scoped to the caller's tenant — there is no cross-tenant view.\n\nRequires `activity:read`.","x-mcp-tool":{"name":"audit_trail","title":"Audit: Activity trail","toolset":"audit","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["activity:read"],"x-example-source":{"origin":"contract"}}}},"components":{"schemas":{"EvtId":{"type":"string","pattern":"^evt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A evt-prefixed uuid, e.g. evt_9f8c1c2e-0000-4000-8000-000000000000"},"TxId":{"type":"string","pattern":"^tx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A tx-prefixed uuid, e.g. tx_9f8c1c2e-0000-4000-8000-000000000000"},"TenantId":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"An org-prefixed uuid, e.g. org_9f8c1c2e-0000-4000-8000-000000000000; a sandbox tenant is org_test_<uuid>"},"UsrId":{"type":"string","pattern":"^usr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A usr-prefixed uuid, e.g. usr_9f8c1c2e-0000-4000-8000-000000000000"},"AppId":{"type":"string","pattern":"^app_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A app-prefixed uuid, e.g. app_9f8c1c2e-0000-4000-8000-000000000000"},"InsId":{"type":"string","pattern":"^ins_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ins-prefixed uuid, e.g. ins_9f8c1c2e-0000-4000-8000-000000000000"},"CplId":{"type":"string","pattern":"^cpl_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cpl-prefixed uuid, e.g. cpl_9f8c1c2e-0000-4000-8000-000000000000"},"Actor":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/UsrId"},"impersonatedBy":{"type":"string","minLength":1},"viaPartner":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["app"]},"id":{"$ref":"#/components/schemas/AppId"},"installationId":{"$ref":"#/components/schemas/InsId"}},"required":["_tag","id","installationId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["customer"]},"id":{"$ref":"#/components/schemas/CplId"}},"required":["_tag","id"],"additionalProperties":false}]},"AuditEntityRef":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false},"AuditEntityRef_1":{"type":"object","properties":{"kind":{"type":"string","minLength":1},"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1}},"required":["kind","id"],"additionalProperties":false},"AuditEntryEncoded":{"type":"object","properties":{"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"service":{"type":"string","minLength":1},"sequence":{"type":"integer","minimum":0},"action":{"type":"string","minLength":1},"actor":{"$ref":"#/components/schemas/Actor"},"occurredAt":{"type":"string"},"entity":{"$ref":"#/components/schemas/AuditEntityRef"},"related":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntityRef_1"}},"detail":{"type":"object"}},"required":["eventId","txId","tenantId","service","sequence","action","actor","occurredAt"],"additionalProperties":false},"AuditPageEncoded":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntryEncoded"}},"next":{"type":"string","minLength":1},"unavailable":{"type":"array","items":{"type":"string","minLength":1}}},"required":["entries","unavailable"],"additionalProperties":false},"AuditCursorInvalidEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["AuditCursorInvalid"]},"cursor":{"type":"string"}},"required":["_tag","cursor"],"additionalProperties":false},"UnauthorizedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"TokenAlreadyUsedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TokenAlreadyUsed"]},"tokenId":{"type":"string"}},"required":["_tag","tokenId"],"additionalProperties":false},"RequestLogUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["RequestLogUnavailable"]},"tokenId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","tokenId","reason"],"additionalProperties":false},"TenantRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TenantRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"ScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ScopeRequired"]},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","required"],"additionalProperties":false},"PlatformAdminRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PlatformAdminRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"SubscriptionRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SubscriptionRequired"]},"status":{"type":"string"}},"required":["_tag","status"],"additionalProperties":false},"MirroredFromSourceEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MirroredFromSource"]},"source":{"type":"string"}},"required":["_tag","source"],"additionalProperties":false}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A tenant JWT: sign in through the auth service, choose the organization, then `GET /api/auth/token`. Tokens last 15 minutes."}}},"security":[],"tags":[{"name":"audit","description":"The tenant's auditable history, folded from every service's journal."}],"servers":[{"url":"https://audit.getmanifold.io","description":"Production"}]}