{"openapi":"3.1.0","info":{"title":"Otto LMS communications API proof","version":"1.39.0","description":"Local proof contract generated from Zod schemas for Phase 16 Ticket 139. Write and webhook endpoints validate payloads but do not persist records or deliver webhooks."},"paths":{"/api/v1/communications/events":{"get":{"summary":"List local communication events","operationId":"listCommunicationEvents","responses":{"200":{"description":"Local communication event list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationEventListResponse"}}}}}},"post":{"summary":"Validate communication event append without writing","operationId":"previewCreateCommunicationEvent","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommunicationEventRequest"}}}},"responses":{"200":{"description":"Validated event preview; no write accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommunicationEventPreviewResponse"}}}}}}},"/api/v1/communications/webhook-subscriptions":{"get":{"summary":"List outgoing webhook subscriptions","operationId":"listCommunicationWebhookSubscriptions","responses":{"200":{"description":"Local outgoing webhook subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionListResponse"}}}}}}},"/api/v1/communications/webhook-subscriptions/{id}/test":{"post":{"summary":"Preview a signed outgoing webhook delivery","operationId":"previewCommunicationWebhookDelivery","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestOutgoingWebhookRequest"}}}},"responses":{"200":{"description":"Webhook delivery preview; no network call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryPreviewResponse"}}}}}}},"/api/v1/communications/openapi":{"get":{"summary":"Return the local communications OpenAPI proof document","operationId":"getCommunicationsOpenApiProof","responses":{"200":{"description":"OpenAPI 3.1 proof generated from Zod schemas."}}}}},"components":{"schemas":{"CommunicationEvent":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"occurredAt":{"type":"string"},"type":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"channel":{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},"direction":{"type":"string","enum":["inbound","outbound","internal","system"]},"personId":{"type":"string"},"personName":{"type":"string"},"sourceModule":{"type":"string"},"sourceRecordId":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string"},"deliveryStatus":{"type":"string","enum":["delivered","read","opened","bounced","failed","acknowledged","signed","submitted","staff_only"]},"visibility":{"type":"string","enum":["student_visible","staff_only","restricted_hidden"]},"hiddenItemCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false}},"required":["id","occurredAt","type","channel","direction","personId","personName","sourceModule","sourceRecordId","subject","preview","deliveryStatus","visibility","hiddenItemCount","localOnly","databaseBacked"],"additionalProperties":false},"WebhookSubscription":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"eventTypes":{"minItems":1,"type":"array","items":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]}},"status":{"type":"string","enum":["active","paused","proof_only"]},"signingAlgorithm":{"type":"string","const":"hmac_sha256"},"secretState":{"type":"string","enum":["configured","missing","rotating"]},"retryPolicy":{"type":"string"},"lastDeliveryLabel":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false}},"required":["id","label","endpointUrl","eventTypes","status","signingAlgorithm","secretState","retryPolicy","lastDeliveryLabel","localOnly","databaseBacked"],"additionalProperties":false},"ListCommunicationEventsQuery":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"personId":{"type":"string","minLength":1},"channel":{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},"limit":{"default":25,"type":"integer","minimum":1,"maximum":50},"cursor":{"type":"string","minLength":1}},"required":["limit"],"additionalProperties":false},"CreateCommunicationEventRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"personId":{"type":"string","minLength":3,"maxLength":80},"type":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"channel":{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},"direction":{"type":"string","enum":["inbound","outbound","internal","system"]},"sourceModule":{"type":"string","minLength":2,"maxLength":80},"sourceRecordId":{"type":"string","minLength":3,"maxLength":120},"bodyPreview":{"type":"string","minLength":5,"maxLength":240},"idempotencyKey":{"type":"string","minLength":8,"maxLength":120},"dryRun":{"default":true,"type":"boolean","const":true},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["personId","type","channel","direction","sourceModule","sourceRecordId","bodyPreview","dryRun"],"additionalProperties":false},"TestOutgoingWebhookRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"eventType":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"sampleEventId":{"type":"string","minLength":3,"maxLength":120},"idempotencyKey":{"type":"string","minLength":8,"maxLength":120},"dryRun":{"default":true,"type":"boolean","const":true}},"required":["eventType","sampleEventId","dryRun"],"additionalProperties":false},"CommunicationEventListResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiVersion":{"type":"string","const":"v1"},"requestId":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false},"productionWrites":{"type":"boolean","const":false},"data":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"occurredAt":{"type":"string"},"type":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"channel":{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},"direction":{"type":"string","enum":["inbound","outbound","internal","system"]},"personId":{"type":"string"},"personName":{"type":"string"},"sourceModule":{"type":"string"},"sourceRecordId":{"type":"string"},"subject":{"type":"string"},"preview":{"type":"string"},"deliveryStatus":{"type":"string","enum":["delivered","read","opened","bounced","failed","acknowledged","signed","submitted","staff_only"]},"visibility":{"type":"string","enum":["student_visible","staff_only","restricted_hidden"]},"hiddenItemCount":{"type":"integer","minimum":0,"maximum":9007199254740991},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false}},"required":["id","occurredAt","type","channel","direction","personId","personName","sourceModule","sourceRecordId","subject","preview","deliveryStatus","visibility","hiddenItemCount","localOnly","databaseBacked"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"nextCursor":{"type":["string","null"]},"returned":{"type":"integer","minimum":0,"maximum":9007199254740991},"totalAvailable":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["limit","nextCursor","returned","totalAvailable"],"additionalProperties":false},"filters":{"type":"object","properties":{"personId":{"type":["string","null"]},"channel":{"anyOf":[{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},{"type":"null"}]}},"required":["personId","channel"],"additionalProperties":false}},"required":["events","pagination","filters"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"},"openapi":{"type":"string","const":"/api/v1/communications/openapi"}},"required":["self","openapi"],"additionalProperties":false}},"required":["apiVersion","requestId","localOnly","databaseBacked","productionWrites","data","links"],"additionalProperties":false},"CommunicationEventPreviewResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiVersion":{"type":"string","const":"v1"},"requestId":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false},"productionWrites":{"type":"boolean","const":false},"data":{"type":"object","properties":{"accepted":{"type":"boolean","const":false},"dryRun":{"type":"boolean","const":true},"wouldWriteEvent":{"type":"boolean","const":false},"writeAccepted":{"type":"boolean","const":false},"normalizedEvent":{"type":"object","properties":{"personId":{"type":"string","minLength":3,"maxLength":80},"type":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"channel":{"type":"string","enum":["in_app","email","sms","phone","document","announcement","form","note"]},"direction":{"type":"string","enum":["inbound","outbound","internal","system"]},"sourceModule":{"type":"string","minLength":2,"maxLength":80},"sourceRecordId":{"type":"string","minLength":3,"maxLength":120},"bodyPreview":{"type":"string","minLength":5,"maxLength":240},"idempotencyKey":{"type":"string","minLength":8,"maxLength":120},"dryRun":{"default":true,"type":"boolean","const":true},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"previewEventId":{"type":"string"},"appendOnlyStoreLabel":{"type":"string"}},"required":["personId","type","channel","direction","sourceModule","sourceRecordId","bodyPreview","dryRun","previewEventId","appendOnlyStoreLabel"],"additionalProperties":false},"proofBoundary":{"type":"string"}},"required":["accepted","dryRun","wouldWriteEvent","writeAccepted","normalizedEvent","proofBoundary"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"},"openapi":{"type":"string","const":"/api/v1/communications/openapi"}},"required":["self","openapi"],"additionalProperties":false}},"required":["apiVersion","requestId","localOnly","databaseBacked","productionWrites","data","links"],"additionalProperties":false},"WebhookSubscriptionListResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiVersion":{"type":"string","const":"v1"},"requestId":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false},"productionWrites":{"type":"boolean","const":false},"data":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"endpointUrl":{"type":"string","format":"uri"},"eventTypes":{"minItems":1,"type":"array","items":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]}},"status":{"type":"string","enum":["active","paused","proof_only"]},"signingAlgorithm":{"type":"string","const":"hmac_sha256"},"secretState":{"type":"string","enum":["configured","missing","rotating"]},"retryPolicy":{"type":"string"},"lastDeliveryLabel":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false}},"required":["id","label","endpointUrl","eventTypes","status","signingAlgorithm","secretState","retryPolicy","lastDeliveryLabel","localOnly","databaseBacked"],"additionalProperties":false}}},"required":["subscriptions"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"},"openapi":{"type":"string","const":"/api/v1/communications/openapi"}},"required":["self","openapi"],"additionalProperties":false}},"required":["apiVersion","requestId","localOnly","databaseBacked","productionWrites","data","links"],"additionalProperties":false},"WebhookDeliveryPreviewResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"apiVersion":{"type":"string","const":"v1"},"requestId":{"type":"string"},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false},"productionWrites":{"type":"boolean","const":false},"data":{"type":"object","properties":{"accepted":{"type":"boolean","const":false},"dryRun":{"type":"boolean","const":true},"wouldDeliverWebhook":{"type":"boolean","const":false},"signatureHeader":{"type":"string"},"retrySchedule":{"type":"array","items":{"type":"string"}},"payloadPreview":{"type":"object","properties":{"id":{"type":"string"},"eventType":{"type":"string","enum":["communication.event_created","communication.message_sent","communication.delivery_failed","communication.reply_received","announcement.acknowledged","document.signed","form.submitted","staff_note.created"]},"subscriptionId":{"type":"string"},"eventId":{"type":"string"},"schoolId":{"type":"string"},"createdAt":{"type":"string"}},"required":["id","eventType","subscriptionId","eventId","schoolId","createdAt"],"additionalProperties":false},"proofBoundary":{"type":"string"}},"required":["accepted","dryRun","wouldDeliverWebhook","signatureHeader","retrySchedule","payloadPreview","proofBoundary"],"additionalProperties":false},"links":{"type":"object","properties":{"self":{"type":"string"},"openapi":{"type":"string","const":"/api/v1/communications/openapi"}},"required":["self","openapi"],"additionalProperties":false}},"required":["apiVersion","requestId","localOnly","databaseBacked","productionWrites","data","links"],"additionalProperties":false},"CommunicationsApiErrorEnvelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["COMMUNICATIONS_EVENT_NOT_FOUND","COMMUNICATIONS_VALIDATION_FAILED","COMMUNICATIONS_WEBHOOK_NOT_FOUND"]},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","request_id","details"],"additionalProperties":false},"localOnly":{"type":"boolean","const":true},"databaseBacked":{"type":"boolean","const":false},"productionWrites":{"type":"boolean","const":false}},"required":["error","localOnly","databaseBacked","productionWrites"],"additionalProperties":false}}},"x-local-proof":true,"x-production-writes":false,"x-webhook-delivery":"disabled-preview-only"}