{ "openapi": "3.1.0", "info": { "title": "AllSign Public API", "version": "0.1.0", "summary": "Canonical bearer-token REST API for public integrations." }, "servers": [ { "url": "/api" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Actors" }, { "name": "Agreements" }, { "name": "Attachments" }, { "name": "Comments" }, { "name": "Contacts" }, { "name": "Imports" }, { "name": "Participants" }, { "name": "Settings" }, { "name": "Signing" }, { "name": "Templates" } ], "paths": { "/actors/self": { "get": { "tags": [ "Actors" ], "summary": "Get the authenticated actor", "operationId": "getActorSelf", "description": "Returns the bearer-authenticated actor identity resolved for the current API request.", "responses": { "200": { "description": "Authenticated actor summary.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "actor" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/contacts": { "get": { "tags": [ "Contacts" ], "summary": "List contacts", "operationId": "listContacts", "description": "Returns a paginated canonical contact collection owned by the authenticated actor.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "search", "in": "query", "required": false, "description": "Filters contacts by canonical searchable fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated contact list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "contacts" ], "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "operationId": "createContact", "description": "Creates a canonical contact owned by the authenticated actor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactCreate" } } } }, "responses": { "201": { "description": "Contact created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements": { "get": { "tags": [ "Agreements" ], "summary": "List agreements", "operationId": "listAgreements", "description": "Returns a paginated canonical agreement collection visible to the authenticated actor.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "search", "in": "query", "required": false, "description": "Filters agreements by canonical searchable fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated agreement list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "agreements" ], "properties": { "agreements": { "type": "array", "items": { "$ref": "#/components/schemas/AgreementPartial" } } } } ] } } }, "examples": { "example": { "summary": "Paginated list of agreements", "value": { "data": { "page": 1, "page_size": 20, "total_pages": 1, "total_records": 1, "agreements": [ { "ref": "a1b2c3d4-0001-4000-8000-000000000001", "name": "PRD: Enterprise Data Export v1", "description": null, "intent": "binding", "status": "executed" } ] } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Agreements" ], "summary": "Create an agreement", "operationId": "createAgreement", "description": "Creates a canonical agreement owned by the authenticated actor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementCreate" }, "examples": { "example": { "summary": "Create a binding agreement", "value": { "name": "PRD: Enterprise Data Export v1", "intent": "binding", "priority": "high" } } } } } }, "responses": { "201": { "description": "Agreement created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } }, "examples": { "example": { "summary": "Agreement created", "value": { "data": { "agreement": { "ref": "a1b2c3d4-0001-4000-8000-000000000001", "name": "PRD: Enterprise Data Export v1", "description": null, "intent": "binding", "priority": "high", "status": "draft", "executed_at": null, "rejected_at": null, "rejected_reason": null, "requires_2fa": false, "requires_rcp": false, "sections": [], "terms": [] } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}": { "get": { "tags": [ "Agreements" ], "summary": "Get an agreement", "operationId": "getAgreement", "description": "Returns a canonical agreement identified by agreement reference.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "200": { "description": "Agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } }, "examples": { "example": { "summary": "Executed agreement", "value": { "data": { "agreement": { "ref": "a1b2c3d4-0001-4000-8000-000000000001", "name": "PRD: Enterprise Data Export v1", "description": null, "intent": "binding", "priority": "high", "status": "executed", "executed_at": "2026-06-27T15:30:00Z", "rejected_at": null, "rejected_reason": null, "requires_2fa": false, "requires_rcp": false, "sections": [ { "ref": "a1b2c3d4-0011-4000-8000-000000000001", "name": "Problem Statement", "description": null, "position": 1, "terms": [] }, { "ref": "a1b2c3d4-0013-4000-8000-000000000001", "name": "v1 Scope", "description": null, "position": 3, "terms": [ { "ref": "a1b2c3d4-0031-4000-8000-000000000001", "name": "Export Formats", "description": "Export formats at launch: CSV and JSON. PDF export deferred to v2.", "negotiable": true, "locked": true, "pending_counter_proposal": false, "has_review_history": true, "priority": "medium", "position": 1 } ] } ], "terms": [ { "ref": "a1b2c3d4-0031-4000-8000-000000000001", "name": "Export Formats", "description": "Export formats at launch: CSV and JSON. PDF export deferred to v2.", "negotiable": true, "locked": true, "pending_counter_proposal": false, "has_review_history": true, "priority": "medium", "position": 1 }, { "ref": "a1b2c3d4-0034-4000-8000-000000000001", "name": "Link Validity", "description": "Download links valid for 14 days from generation.", "negotiable": true, "locked": true, "pending_counter_proposal": false, "has_review_history": true, "priority": "medium", "position": 2 }, { "ref": "a1b2c3d4-0063-4000-8000-000000000001", "name": "Completion Notification", "description": "In-app notification only for v1; email after notification redesign ships.", "negotiable": true, "locked": true, "pending_counter_proposal": false, "has_review_history": true, "priority": "medium", "position": 3 } ] } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "tags": [ "Agreements" ], "summary": "Update an agreement", "operationId": "updateAgreement", "description": "Updates a canonical agreement identified by agreement reference.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementUpdate" } } } }, "responses": { "200": { "description": "Updated agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Agreements" ], "summary": "Delete an agreement", "operationId": "deleteAgreement", "description": "Deletes a canonical agreement and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "200": { "description": "Deleted agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/rejections": { "post": { "tags": [ "Agreements" ], "summary": "Reject an agreement", "operationId": "createAgreementRejection", "description": "Records a rejection event for the referenced agreement and returns the final agreement representation.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTermination" } } } }, "responses": { "200": { "description": "Rejected agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/cancellations": { "post": { "tags": [ "Agreements" ], "summary": "Cancel an agreement", "operationId": "createAgreementCancellation", "description": "Records a cancellation event for the referenced agreement and returns the final agreement representation.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementTermination" } } } }, "responses": { "200": { "description": "Cancelled agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/copies": { "post": { "tags": [ "Agreements" ], "summary": "Create an agreement copy", "operationId": "createAgreementCopy", "description": "Creates a canonical agreement copy from the referenced agreement and returns the copied agreement representation.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "201": { "description": "Copied agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/contacts/{contact_ref}": { "get": { "tags": [ "Contacts" ], "summary": "Get a contact", "operationId": "getContact", "description": "Returns a canonical contact identified by contact reference.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "responses": { "200": { "description": "Contact representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "tags": [ "Contacts" ], "summary": "Update a contact", "operationId": "updateContact", "description": "Updates a canonical contact identified by contact reference.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactUpdate" } } } }, "responses": { "200": { "description": "Updated contact representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact", "operationId": "deleteContact", "description": "Deletes a canonical contact and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "responses": { "200": { "description": "Deleted contact representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "listTemplates", "description": "Returns a paginated canonical template collection owned by the authenticated actor.", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "search", "in": "query", "required": false, "description": "Filters templates by canonical searchable fields.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated template list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "templates" ], "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/TemplatePartial" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Templates" ], "summary": "Create a template", "operationId": "createTemplate", "description": "Creates a canonical template owned by the authenticated actor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateCreate" } } } }, "responses": { "201": { "description": "Template created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a template from an agreement", "operationId": "createTemplateFromAgreement", "description": "Creates a canonical template from the referenced agreement and returns the new template representation.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "201": { "description": "Created template representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "operationId": "getTemplate", "description": "Returns a canonical template identified by template reference.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "200": { "description": "Template representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "put": { "tags": [ "Templates" ], "summary": "Update a template", "operationId": "updateTemplate", "description": "Updates a canonical template identified by template reference.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateUpdate" } } } }, "responses": { "200": { "description": "Updated template representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "operationId": "deleteTemplate", "description": "Deletes a canonical template and returns a success confirmation.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "200": { "description": "Deleted template confirmation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted", "ref" ], "properties": { "deleted": { "type": "boolean", "enum": [ true ] }, "ref": { "type": "string" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/copies": { "post": { "tags": [ "Templates" ], "summary": "Create a template copy", "operationId": "createTemplateCopy", "description": "Creates a canonical template copy from the referenced template and returns the copied template representation.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "201": { "description": "Copied template representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/agreements": { "post": { "tags": [ "Agreements" ], "summary": "Create an agreement from a template", "operationId": "createAgreementFromTemplate", "description": "Creates a canonical agreement from the referenced template and returns the new agreement representation.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "201": { "description": "Created agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/participants": { "get": { "tags": [ "Participants" ], "summary": "List participants", "operationId": "listAgreementParticipants", "description": "Returns a paginated canonical participant collection for an agreement visible to the authenticated actor.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated participant list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "participants" ], "properties": { "participants": { "type": "array", "items": { "$ref": "#/components/schemas/Participant" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Participants" ], "summary": "Create a participant", "operationId": "createAgreementParticipant", "description": "Creates an agreement participant invitation or an active agent participant for the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantCreate" }, "examples": { "example": { "summary": "Invite a participant as signer", "value": { "email": "marcus.webb@lumen.app", "name": "Marcus Webb", "type": "signer" } } } } } }, "responses": { "201": { "description": "Participant created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "invitation", "participant" ], "properties": { "invitation": { "anyOf": [ { "$ref": "#/components/schemas/InvitationPartial" }, { "type": "null" } ] }, "participant": { "$ref": "#/components/schemas/Participant" } } } } }, "examples": { "example": { "summary": "Participant invited as signer", "value": { "data": { "participant": { "ref": "a1b2c3d4-0102-4000-8000-000000000001", "name": "Marcus Webb", "email": "marcus.webb@lumen.app", "type": "signer", "active": false, "avatar_url": null, "actor": null }, "invitation": { "ref": "a1b2c3d4-0501-4000-8000-000000000001", "email": "marcus.webb@lumen.app", "type": "signer" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/participants/self": { "post": { "tags": [ "Participants" ], "summary": "Create a self-join participant", "operationId": "createAgreementParticipantSelf", "description": "Creates a canonical active participant for the authenticated actor on the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantSelfJoinCreate" } } } }, "responses": { "201": { "description": "Participant created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "participant" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/participants/{participant_ref}": { "put": { "tags": [ "Participants" ], "summary": "Update a participant", "operationId": "updateParticipant", "description": "Updates the canonical role assignment for an identified agreement participant.", "parameters": [ { "$ref": "#/components/parameters/ParticipantRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParticipantUpdate" } } } }, "responses": { "200": { "description": "Updated participant representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "participant" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Participants" ], "summary": "Delete a participant", "operationId": "deleteParticipant", "description": "Deletes a canonical participant and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/ParticipantRef" } ], "responses": { "200": { "description": "Deleted participant representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "participant" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/invitations/{invitation_ref}/accepts": { "post": { "tags": [ "Participants" ], "summary": "Create an invitation accept", "operationId": "createInvitationAccept", "description": "Accepts the identified invitation and returns the activated participant representation.", "parameters": [ { "$ref": "#/components/parameters/InvitationRef" } ], "responses": { "200": { "description": "Accepted participant representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "participant" ], "properties": { "participant": { "$ref": "#/components/schemas/Participant" } } } } }, "examples": { "example": { "summary": "Accepted participant invitation", "value": { "data": { "participant": { "ref": "a1b2c3d4-0102-4000-8000-000000000001", "name": "Marcus Webb", "email": "marcus.webb@lumen.app", "type": "signer", "active": true, "avatar_url": null, "actor": { "ref": "a1b2c3d4-0602-4000-8000-000000000001", "kind": "user" } } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/invitations/{invitation_ref}/rejects": { "post": { "tags": [ "Participants" ], "summary": "Create an invitation reject", "operationId": "createInvitationReject", "description": "Rejects the identified invitation and returns the rejected invitation reference.", "parameters": [ { "$ref": "#/components/parameters/InvitationRef" } ], "responses": { "200": { "description": "Rejected invitation reference.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "invitation" ], "properties": { "invitation": { "$ref": "#/components/schemas/InvitationReference" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/sections": { "post": { "tags": [ "Agreements" ], "summary": "Create a section", "operationId": "createAgreementSection", "description": "Creates a canonical section under the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionCreate" }, "examples": { "example": { "summary": "Create a section", "value": { "name": "v1 Scope", "position": 3 } } } } } }, "responses": { "201": { "description": "Section created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } }, "examples": { "example": { "summary": "Section created", "value": { "data": { "section": { "ref": "a1b2c3d4-0013-4000-8000-000000000001", "name": "v1 Scope", "description": null, "position": 3, "terms": [] } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/sections": { "post": { "tags": [ "Templates" ], "summary": "Create a section", "operationId": "createTemplateSection", "description": "Creates a canonical section under the identified template.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionCreate" } } } }, "responses": { "201": { "description": "Section created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/sections/{section_ref}": { "put": { "tags": [ "Agreements" ], "summary": "Update a section", "operationId": "updateSection", "description": "Updates a canonical section identified by section reference.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SectionUpdate" } } } }, "responses": { "200": { "description": "Updated section representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/sections/{section_ref}/copies": { "post": { "tags": [ "Agreements" ], "summary": "Create a section copy", "operationId": "createSectionCopy", "description": "Creates a canonical copy of the identified section and returns the copied section representation.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" } ], "responses": { "201": { "description": "Copied section representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/sections/{section_ref}/placements": { "post": { "tags": [ "Agreements" ], "summary": "Create a section placement", "operationId": "createSectionPlacement", "description": "Repositions a canonical section and returns the updated section representation.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementCreate" } } } }, "responses": { "200": { "description": "Repositioned section representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Agreements" ], "summary": "Delete a section", "operationId": "deleteSection", "description": "Deletes a canonical section and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" } ], "responses": { "200": { "description": "Deleted section representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "section" ], "properties": { "section": { "$ref": "#/components/schemas/Section" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/terms": { "post": { "tags": [ "Agreements" ], "summary": "Create a term", "operationId": "createAgreementTerm", "description": "Creates a canonical term under the identified agreement, optionally nested under a section.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermCreate" }, "examples": { "example": { "summary": "Create a term within a section", "value": { "name": "Export Formats", "description": "Export formats supported at launch: CSV, JSON, and PDF.", "negotiable": true, "section": { "ref": "a1b2c3d4-0013-4000-8000-000000000001" }, "priority": "medium", "position": 1 } } } } } }, "responses": { "201": { "description": "Term created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } }, "examples": { "example": { "summary": "Term created within a section", "value": { "data": { "term": { "ref": "a1b2c3d4-0031-4000-8000-000000000001", "name": "Export Formats", "description": "Export formats supported at launch: CSV, JSON, and PDF.", "negotiable": true, "locked": false, "pending_counter_proposal": false, "has_review_history": false, "priority": "medium", "position": 1 } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/terms": { "post": { "tags": [ "Templates" ], "summary": "Create a term", "operationId": "createTemplateTerm", "description": "Creates a canonical term under the identified template, optionally nested under a section.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermCreate" } } } }, "responses": { "201": { "description": "Term created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}": { "put": { "tags": [ "Agreements" ], "summary": "Update a term", "operationId": "updateTerm", "description": "Updates a canonical term identified by term reference.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermUpdate" } } } }, "responses": { "200": { "description": "Updated term representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Agreements" ], "summary": "Delete a term", "operationId": "deleteTerm", "description": "Deletes a canonical term and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "responses": { "200": { "description": "Deleted term representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/copies": { "post": { "tags": [ "Agreements" ], "summary": "Create a term copy", "operationId": "createTermCopy", "description": "Creates a canonical copy of the identified term and returns the copied term representation.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "responses": { "201": { "description": "Copied term representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/conditions": { "post": { "tags": [ "Agreements" ], "summary": "Create a term condition", "operationId": "createTermCondition", "description": "Updates the canonical negotiability condition of a term and returns the updated term representation.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermConditionChange" } } } }, "responses": { "200": { "description": "Updated term representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/placements": { "post": { "tags": [ "Agreements" ], "summary": "Create a term placement", "operationId": "createTermPlacement", "description": "Repositions a canonical term and returns the updated term representation.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacementCreate" } } } }, "responses": { "200": { "description": "Repositioned term representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "term" ], "properties": { "term": { "$ref": "#/components/schemas/Term" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/decisions": { "get": { "tags": [ "Decisions" ], "summary": "List term decisions", "operationId": "listTermDecisions", "description": "Returns a paginated canonical decision collection scoped to a term.", "parameters": [ { "$ref": "#/components/parameters/TermRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated term decision list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "decisions" ], "properties": { "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Decisions" ], "summary": "Create a term decision", "operationId": "createTermDecision", "description": "Creates a canonical decision for the current revision of the identified term.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecisionCreate" }, "examples": { "example": { "summary": "Accept the current term revision", "value": { "status": "accepted", "remarks": "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline." } } } } } }, "responses": { "201": { "description": "Decision created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "decision", "proposal_decision", "revision" ], "properties": { "decision": { "$ref": "#/components/schemas/Decision" }, "proposal_decision": { "anyOf": [ { "$ref": "#/components/schemas/Decision" }, { "type": "null" } ] }, "revision": { "anyOf": [ { "$ref": "#/components/schemas/Revision" }, { "type": "null" } ] } } } } }, "examples": { "example": { "summary": "Term revision accepted", "value": { "data": { "decision": { "ref": "a1b2c3d4-0401-4000-8000-000000000001", "status": "accepted", "remarks": "Agreed. Scoping to CSV and JSON aligns with v1 delivery timeline.", "created_at": "2026-06-27T11:00:00Z", "actor": { "ref": "a1b2c3d4-0601-4000-8000-000000000001", "name": "Priya Nair", "avatar_url": null }, "revision": { "ref": "a1b2c3d4-0301-4000-8000-000000000001" } }, "proposal_decision": null, "revision": null } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/revisions": { "get": { "tags": [ "Revisions" ], "summary": "List term revisions", "operationId": "listTermRevisions", "description": "Returns a paginated canonical revision collection scoped to a term.", "parameters": [ { "$ref": "#/components/parameters/TermRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated term revision list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "revisions" ], "properties": { "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Revisions" ], "summary": "Create a term revision", "operationId": "createTermRevision", "description": "Creates a canonical revision proposal for the identified term and records its accepting decision.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionProposal" }, "examples": { "example": { "summary": "Propose a term revision", "value": { "description": "Export formats at launch: CSV and JSON. PDF export deferred to v2.", "remarks": "PDF export is out of scope for v1; deferring to reduce launch risk." } } } } } }, "responses": { "201": { "description": "Revision created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "decision", "revision" ], "properties": { "decision": { "$ref": "#/components/schemas/Decision" }, "revision": { "$ref": "#/components/schemas/Revision" } } } } }, "examples": { "example": { "summary": "Term revision recorded", "value": { "data": { "revision": { "ref": "a1b2c3d4-0301-4000-8000-000000000001", "number": 1, "description": "Export formats at launch: CSV and JSON. PDF export deferred to v2.", "name": null, "latest": true, "created_at": "2026-06-27T10:30:00Z", "actor": { "ref": "a1b2c3d4-0602-4000-8000-000000000001", "name": "Marcus Webb" }, "decisions": [] }, "decision": { "ref": "a1b2c3d4-0401-4000-8000-000000000001", "status": "accepted", "remarks": "PDF export is out of scope for v1; deferring to reduce launch risk.", "created_at": "2026-06-27T10:30:00Z", "actor": { "ref": "a1b2c3d4-0602-4000-8000-000000000001", "name": "Marcus Webb", "avatar_url": null }, "revision": { "ref": "a1b2c3d4-0301-4000-8000-000000000001" } } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/comments": { "get": { "tags": [ "Comments" ], "summary": "List agreement comments", "operationId": "listAgreementComments", "description": "Returns a paginated canonical comment collection scoped to an agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated agreement comment list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Comments" ], "summary": "Create an agreement comment", "operationId": "createAgreementComment", "description": "Creates a canonical comment scoped directly to an agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/sections/{section_ref}/comments": { "get": { "tags": [ "Comments" ], "summary": "List section comments", "operationId": "listSectionComments", "description": "Returns a paginated canonical comment collection scoped to a section.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated section comment list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Comments" ], "summary": "Create a section comment", "operationId": "createSectionComment", "description": "Creates a canonical comment scoped to a section.", "parameters": [ { "$ref": "#/components/parameters/SectionRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/terms/{term_ref}/comments": { "get": { "tags": [ "Comments" ], "summary": "List term comments", "operationId": "listTermComments", "description": "Returns a paginated canonical comment collection scoped to a term.", "parameters": [ { "$ref": "#/components/parameters/TermRef" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "Paginated term comment list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" } } } } ] } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Comments" ], "summary": "Create a term comment", "operationId": "createTermComment", "description": "Creates a canonical comment scoped to a term and optionally pinned to the current revision.", "parameters": [ { "$ref": "#/components/parameters/TermRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreate" } } } }, "responses": { "201": { "description": "Comment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/comments/{comment_ref}": { "put": { "tags": [ "Comments" ], "summary": "Update a comment", "operationId": "updateComment", "description": "Updates a canonical comment identified by comment reference.", "parameters": [ { "$ref": "#/components/parameters/CommentRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdate" } } } }, "responses": { "200": { "description": "Updated comment representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Comments" ], "summary": "Delete a comment", "operationId": "deleteComment", "description": "Deletes a canonical comment and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/CommentRef" } ], "responses": { "200": { "description": "Deleted comment representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "$ref": "#/components/schemas/Comment" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/settings": { "get": { "tags": [ "Settings" ], "summary": "Get actor settings", "operationId": "getActorSettings", "description": "Returns notification preferences and security context for the bearer-authenticated actor.", "responses": { "200": { "description": "Authenticated actor settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "$ref": "#/components/schemas/Settings" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } }, "put": { "tags": [ "Settings" ], "summary": "Update actor settings", "operationId": "updateActorSettings", "description": "Updates notification preferences for the bearer-authenticated actor and returns the current settings view.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettingsUpdate" } } } }, "responses": { "200": { "description": "Updated actor settings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "$ref": "#/components/schemas/Settings" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/actors/self/avatar": { "put": { "tags": [ "Actors" ], "summary": "Replace the authenticated actor avatar", "operationId": "replaceActorAvatar", "description": "Stores avatar media for the bearer-authenticated actor and returns the updated actor representation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarUpload" } } } }, "responses": { "200": { "description": "Updated actor representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "actor" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Actors" ], "summary": "Delete the authenticated actor avatar", "operationId": "deleteActorAvatar", "description": "Deletes avatar media for the bearer-authenticated actor and returns the updated actor representation.", "responses": { "200": { "description": "Updated actor representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "actor" ], "properties": { "actor": { "$ref": "#/components/schemas/Actor" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/actors/self/avatar/content": { "get": { "tags": [ "Actors" ], "summary": "Get the authenticated actor avatar content", "operationId": "getActorAvatarContent", "description": "Returns the binary avatar media content for the bearer-authenticated actor.", "responses": { "200": { "description": "Avatar media content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/contacts/{contact_ref}/avatar": { "put": { "tags": [ "Contacts" ], "summary": "Replace a contact avatar", "operationId": "replaceContactAvatar", "description": "Stores avatar media for a canonical contact identified by contact reference.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvatarUpload" } } } }, "responses": { "200": { "description": "Updated contact representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Contacts" ], "summary": "Delete a contact avatar", "operationId": "deleteContactAvatar", "description": "Deletes avatar media for a canonical contact identified by contact reference.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "responses": { "200": { "description": "Updated contact representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "$ref": "#/components/schemas/Contact" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/contacts/{contact_ref}/avatar/content": { "get": { "tags": [ "Contacts" ], "summary": "Get contact avatar content", "operationId": "getContactAvatarContent", "description": "Returns the binary avatar media content for a canonical contact identified by contact reference.", "parameters": [ { "$ref": "#/components/parameters/ContactRef" } ], "responses": { "200": { "description": "Avatar media content.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/agreements/imports": { "post": { "tags": [ "Imports" ], "summary": "Import an agreement", "operationId": "importAgreement", "description": "Creates a canonical agreement by importing a canonical document payload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalDocument" } } } }, "responses": { "201": { "description": "Agreement created from import.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/templates/imports": { "post": { "tags": [ "Imports" ], "summary": "Import a template", "operationId": "importTemplate", "description": "Creates a canonical template by importing a canonical document payload.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalDocument" } } } }, "responses": { "201": { "description": "Template created from import.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "template" ], "properties": { "template": { "$ref": "#/components/schemas/Template" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List agreement attachments", "operationId": "listAgreementAttachments", "description": "Returns canonical attachments scoped to the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "200": { "description": "Agreement attachment list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Attachments" ], "summary": "Create an agreement attachment", "operationId": "createAgreementAttachment", "description": "Creates a canonical attachment scoped to the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCreate" } } } }, "responses": { "201": { "description": "Attachment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachment" ], "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/attachments": { "get": { "tags": [ "Attachments" ], "summary": "List template attachments", "operationId": "listTemplateAttachments", "description": "Returns canonical attachments scoped to the identified template.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "200": { "description": "Template attachment list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachments" ], "properties": { "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } }, "post": { "tags": [ "Attachments" ], "summary": "Create a template attachment", "operationId": "createTemplateAttachment", "description": "Creates a canonical attachment scoped to the identified template.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentCreate" } } } }, "responses": { "201": { "description": "Attachment created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachment" ], "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/attachments/{attachment_ref}": { "put": { "tags": [ "Attachments" ], "summary": "Update an attachment", "operationId": "updateAttachment", "description": "Updates canonical attachment metadata identified by attachment reference.", "parameters": [ { "$ref": "#/components/parameters/AttachmentRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentUpdate" } } } }, "responses": { "200": { "description": "Updated attachment representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachment" ], "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } }, "delete": { "tags": [ "Attachments" ], "summary": "Delete an attachment", "operationId": "deleteAttachment", "description": "Deletes canonical attachment metadata and returns its final representation.", "parameters": [ { "$ref": "#/components/parameters/AttachmentRef" } ], "responses": { "200": { "description": "Deleted attachment representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "attachment" ], "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/templates/{template_ref}/content": { "get": { "tags": [ "Templates" ], "summary": "Get template content", "operationId": "getTemplateContent", "description": "Returns the canonical document content compiled from the identified template.", "parameters": [ { "$ref": "#/components/parameters/TemplateRef" } ], "responses": { "200": { "description": "Canonical template content.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/components/schemas/CanonicalDocument" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/protocols": { "get": { "tags": [ "Signing" ], "summary": "Get agreement signing protocol", "operationId": "getAgreementProtocol", "description": "Returns the current signing state and the single valid next action for the identified agreement.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "200": { "description": "Agreement signing protocol state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Protocol" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/protocols/{agreement_ref}/authentications": { "post": { "tags": [ "Signing" ], "summary": "Create a protocol authentication", "operationId": "createProtocolAuthentication", "description": "Creates the current signing authentication transition for the identified agreement protocol.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationCreate" } } } }, "responses": { "200": { "description": "Session continuation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" } } } }, "201": { "description": "Refreshed authenticated session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" } } } }, "202": { "description": "Verification challenge for authentication completion.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/protocols/{agreement_ref}/rcp/assignments": { "post": { "tags": [ "Signing" ], "summary": "Create an RCP assignment", "operationId": "createProtocolRcpAssignment", "description": "Creates the reciprocal confirmation requirements for the identified agreement protocol.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "responses": { "200": { "description": "Updated reciprocal confirmation context.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "rcp" ], "properties": { "rcp": { "$ref": "#/components/schemas/RcpContext" } } } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/protocols/{agreement_ref}/rcp/confirmations": { "post": { "tags": [ "Signing" ], "summary": "Create an RCP confirmation", "operationId": "createProtocolRcpConfirmation", "description": "Confirms the current reciprocal confirmation challenge for the identified agreement protocol.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RcpConfirmation" } } } }, "responses": { "200": { "description": "Updated reciprocal confirmation state.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "challenge", "rcp" ], "properties": { "challenge": { "$ref": "#/components/schemas/RcpChallenge" }, "rcp": { "$ref": "#/components/schemas/RcpContext" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/agreements/{agreement_ref}/signatures": { "post": { "tags": [ "Signing" ], "summary": "Create a signature", "operationId": "createAgreementSignature", "description": "Attempts to create the actor's agreement signature and returns either the created signature or a verification challenge.", "parameters": [ { "$ref": "#/components/parameters/AgreementRef" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureCreate" }, "examples": { "example": { "summary": "Sign an agreement", "value": { "legal_affirmed": true } } } } } }, "responses": { "200": { "description": "Agreement signing result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureCreateResponse" } } } }, "201": { "description": "Agreement signing result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureCreateResponse" }, "examples": { "example": { "summary": "Signature created", "value": { "data": { "agreement": { "ref": "a1b2c3d4-0001-4000-8000-000000000001", "name": "PRD: Enterprise Data Export v1", "status": "signing", "intent": "binding", "priority": "high", "executed_at": null, "rejected_at": null, "rejected_reason": null, "requires_2fa": false, "requires_rcp": false, "description": null, "sections": [], "terms": [] }, "signature": { "ref": "a1b2c3d4-0701-4000-8000-000000000001", "created_at": "2026-06-27T14:00:00Z", "requires_2fa": false }, "verification": null } } } } } } }, "202": { "description": "Agreement signing result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignatureCreateResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/verifications/{verification_ref}/confirmations": { "post": { "tags": [ "Signing" ], "summary": "Create a verification confirmation", "operationId": "createVerificationConfirmation", "description": "Completes the current signing-related verification challenge identified by verification reference.", "parameters": [ { "$ref": "#/components/parameters/VerificationRef" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationCode" } } } }, "responses": { "201": { "description": "Refreshed authenticated session.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "session" ], "properties": { "session": { "$ref": "#/components/schemas/Session" } } } } } } } }, "202": { "description": "Updated agreement representation.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" } } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Bearer" } }, "parameters": { "AttachmentRef": { "name": "attachment_ref", "in": "path", "required": true, "description": "Public attachment reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "AgreementRef": { "name": "agreement_ref", "in": "path", "required": true, "description": "Public agreement reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "CommentRef": { "name": "comment_ref", "in": "path", "required": true, "description": "Public comment reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "ContactRef": { "name": "contact_ref", "in": "path", "required": true, "description": "Public contact reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "InvitationRef": { "name": "invitation_ref", "in": "path", "required": true, "description": "Public invitation reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "ParticipantRef": { "name": "participant_ref", "in": "path", "required": true, "description": "Public participant reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "SectionRef": { "name": "section_ref", "in": "path", "required": true, "description": "Public section reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "TemplateRef": { "name": "template_ref", "in": "path", "required": true, "description": "Public template reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "TermRef": { "name": "term_ref", "in": "path", "required": true, "description": "Public term reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "VerificationRef": { "name": "verification_ref", "in": "path", "required": true, "description": "Public verification reference.", "schema": { "$ref": "#/components/schemas/Ref" } }, "Page": { "name": "page", "in": "query", "required": false, "description": "One-based page number.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PageSize": { "name": "page_size", "in": "query", "required": false, "description": "Maximum number of records returned per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } }, "responses": { "Error": { "description": "Standard API error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Ref": { "type": "string", "format": "uuid", "description": "Public stable resource reference." }, "Actor": { "type": "object", "description": "Canonical actor identity summary for bearer authentication.", "required": [ "avatar_url", "email", "family_name", "given_name", "job_title", "kind", "name", "organization", "ref" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "family_name": { "type": [ "string", "null" ] }, "given_name": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "organization": { "type": [ "string", "null" ] }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "ActorUpdate": { "type": "object", "description": "Authenticated actor update payload.", "additionalProperties": false, "properties": { "family_name": { "type": [ "string", "null" ] }, "given_name": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] } } }, "NotificationSettings": { "type": "object", "description": "Notification preference flags for the authenticated actor.", "required": [ "agreement_execution", "agreement_invitations", "comments_mentions", "signature_requests", "term_revisions", "weekly_digest" ], "properties": { "agreement_execution": { "type": "boolean" }, "agreement_invitations": { "type": "boolean" }, "comments_mentions": { "type": "boolean" }, "signature_requests": { "type": "boolean" }, "term_revisions": { "type": "boolean" }, "weekly_digest": { "type": "boolean" } } }, "NotificationSettingsUpdate": { "type": "object", "description": "Notification preference update payload for the authenticated actor.", "additionalProperties": false, "properties": { "agreement_execution": { "type": "boolean" }, "agreement_invitations": { "type": "boolean" }, "comments_mentions": { "type": "boolean" }, "signature_requests": { "type": "boolean" }, "term_revisions": { "type": "boolean" }, "weekly_digest": { "type": "boolean" } } }, "SecuritySettings": { "type": "object", "description": "Security context for the authenticated actor.", "additionalProperties": true }, "Settings": { "type": "object", "description": "Settings view for the authenticated actor.", "required": [ "notifications", "security" ], "properties": { "notifications": { "$ref": "#/components/schemas/NotificationSettings" }, "security": { "$ref": "#/components/schemas/SecuritySettings" } } }, "AvatarUpload": { "type": "object", "description": "Base64-encoded avatar upload payload.", "additionalProperties": false, "required": [ "content_base64", "content_type" ], "properties": { "content_base64": { "type": "string" }, "content_type": { "type": "string" } } }, "Contact": { "type": "object", "description": "Canonical contact resource.", "required": [ "avatar_url", "email", "family_name", "given_name", "name", "notes", "organization", "phone", "ref" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "family_name": { "type": [ "string", "null" ] }, "given_name": { "type": "string" }, "name": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "CommentActor": { "type": "object", "description": "Actor identity attached to a comment.", "required": [ "avatar_url", "name", "ref" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "CommentRevision": { "type": "object", "description": "Revision reference attached to a comment.", "required": [ "latest", "ref" ], "properties": { "latest": { "type": "boolean" }, "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "CommentResourceRef": { "type": "object", "description": "Nested resource reference attached to a comment.", "required": [ "ref" ], "properties": { "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "Comment": { "type": "object", "description": "Canonical comment resource.", "required": [ "actor", "content", "created_at", "on_revision", "ref", "revision", "section", "term" ], "properties": { "actor": { "$ref": "#/components/schemas/CommentActor" }, "content": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "on_revision": { "type": "boolean" }, "ref": { "$ref": "#/components/schemas/Ref" }, "revision": { "anyOf": [ { "$ref": "#/components/schemas/CommentRevision" }, { "type": "null" } ] }, "section": { "anyOf": [ { "$ref": "#/components/schemas/CommentResourceRef" }, { "type": "null" } ] }, "term": { "anyOf": [ { "$ref": "#/components/schemas/CommentResourceRef" }, { "type": "null" } ] } } }, "AgreementPartial": { "type": "object", "description": "Canonical agreement summary.", "required": [ "description", "intent", "name", "ref", "status" ], "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string" }, "name": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" }, "status": { "type": "string" } } }, "Section": { "type": "object", "description": "Canonical section resource.", "required": [ "description", "name", "position", "ref", "terms" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "position": { "type": [ "integer", "null" ] }, "ref": { "$ref": "#/components/schemas/Ref" }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } } } }, "Term": { "type": "object", "description": "Canonical term resource.", "required": [ "description", "has_review_history", "locked", "name", "negotiable", "pending_counter_proposal", "position", "priority", "ref" ], "properties": { "description": { "type": [ "string", "null" ] }, "has_review_history": { "type": "boolean" }, "locked": { "type": "boolean" }, "name": { "type": "string" }, "negotiable": { "type": "boolean" }, "pending_counter_proposal": { "type": "boolean" }, "position": { "type": [ "integer", "null" ] }, "priority": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "Agreement": { "type": "object", "description": "Canonical agreement resource.", "required": [ "description", "executed_at", "intent", "name", "priority", "rejected_at", "rejected_reason", "ref", "requires_2fa", "requires_rcp", "sections", "status", "terms" ], "properties": { "description": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "intent": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "string" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejected_reason": { "type": [ "string", "null" ] }, "ref": { "$ref": "#/components/schemas/Ref" }, "requires_2fa": { "type": "boolean" }, "requires_rcp": { "type": "boolean" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "status": { "type": "string" }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } } } }, "AgreementCreate": { "type": "object", "description": "Agreement creation payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string", "enum": [ "binding", "nonbinding" ] }, "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "requires_2fa": { "type": "integer", "enum": [ 0, 1 ] }, "requires_rcp": { "type": "integer", "enum": [ 0, 1 ] } } }, "AgreementUpdate": { "type": "object", "description": "Agreement update payload.", "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string", "enum": [ "binding", "nonbinding" ] }, "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "requires_2fa": { "type": "integer", "enum": [ 0, 1 ] }, "requires_rcp": { "type": "integer", "enum": [ 0, 1 ] } } }, "AgreementTermination": { "type": "object", "description": "Agreement rejection or cancellation payload.", "additionalProperties": false, "properties": { "remarks": { "type": [ "string", "null" ], "description": "Optional human-readable remarks attached to the lifecycle event." } } }, "SectionCreate": { "type": "object", "description": "Section creation payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "position": { "type": [ "integer", "null" ] } } }, "SectionReference": { "type": "object", "description": "Nested section reference.", "required": [ "ref" ], "properties": { "ref": { "$ref": "#/components/schemas/Ref" } } }, "PlacementCreate": { "type": "object", "description": "Placement instruction payload.", "additionalProperties": false, "properties": { "after_ref": { "type": [ "string", "null" ] }, "before_ref": { "type": [ "string", "null" ] }, "direction": { "type": [ "string", "null" ], "enum": [ "up", "down", null ] }, "target_root": { "type": [ "boolean", "null" ] }, "target_section_ref": { "type": [ "string", "null" ] } } }, "TermConditionChange": { "type": "object", "description": "Term condition payload.", "additionalProperties": false, "required": [ "negotiable" ], "properties": { "negotiable": { "type": "integer", "enum": [ 0, 1 ] } } }, "SectionUpdate": { "type": "object", "description": "Section update payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "position": { "type": [ "integer", "null" ] } } }, "TermCreate": { "type": "object", "description": "Term creation payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "negotiable": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ] }, "position": { "type": [ "integer", "null" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "section": { "anyOf": [ { "$ref": "#/components/schemas/SectionReference" }, { "type": "null" } ] } } }, "TermUpdate": { "type": "object", "description": "Term update payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "negotiable": { "type": [ "integer", "null" ], "enum": [ 0, 1, null ] }, "position": { "type": [ "integer", "null" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] } } }, "CommentCreate": { "type": "object", "description": "Comment creation payload.", "additionalProperties": false, "required": [ "content" ], "properties": { "content": { "type": "string" }, "on_revision": { "type": "boolean" } } }, "CommentUpdate": { "type": "object", "description": "Comment update payload.", "additionalProperties": false, "required": [ "content" ], "properties": { "content": { "type": "string" }, "on_revision": { "type": "boolean" } } }, "DecisionActor": { "type": "object", "description": "Actor identity attached to a decision.", "required": [ "avatar_url", "name", "ref" ], "properties": { "avatar_url": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "DecisionRevision": { "type": "object", "description": "Revision reference attached to a decision.", "required": [ "ref" ], "properties": { "ref": { "$ref": "#/components/schemas/Ref" } } }, "Decision": { "type": "object", "description": "Canonical decision resource.", "required": [ "actor", "created_at", "ref", "remarks", "revision", "status" ], "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/DecisionActor" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "ref": { "$ref": "#/components/schemas/Ref" }, "remarks": { "type": [ "string", "null" ] }, "revision": { "anyOf": [ { "$ref": "#/components/schemas/DecisionRevision" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "accepted", "rejected" ] } } }, "DecisionCreate": { "type": "object", "description": "Decision creation payload.", "additionalProperties": false, "required": [ "status" ], "properties": { "proposed_description": { "type": [ "string", "null" ] }, "proposed_name": { "type": [ "string", "null" ] }, "remarks": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "accepted", "rejected" ] }, "supersedes_decision_ref": { "type": [ "string", "null" ] } } }, "RevisionActor": { "type": "object", "description": "Actor identity attached to a revision.", "required": [ "name", "ref" ], "properties": { "name": { "type": "string" }, "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "Revision": { "type": "object", "description": "Canonical revision resource.", "required": [ "actor", "created_at", "decisions", "description", "latest", "name", "number", "ref" ], "properties": { "actor": { "anyOf": [ { "$ref": "#/components/schemas/RevisionActor" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "decisions": { "type": "array", "items": { "$ref": "#/components/schemas/Decision" } }, "description": { "type": [ "string", "null" ] }, "latest": { "type": "boolean" }, "name": { "type": [ "string", "null" ] }, "number": { "type": "integer" }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "RevisionProposal": { "type": "object", "description": "Revision proposal payload.", "additionalProperties": false, "required": [ "description" ], "properties": { "description": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "remarks": { "type": [ "string", "null" ] } } }, "TemplatePartial": { "type": "object", "description": "Canonical template partial.", "required": [ "description", "intent", "name", "ref", "status" ], "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string" }, "name": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" }, "status": { "type": "string" } } }, "Template": { "type": "object", "description": "Canonical template resource.", "required": [ "description", "executed_at", "intent", "name", "priority", "rejected_at", "rejected_reason", "ref", "requires_2fa", "requires_rcp", "sections", "status", "terms" ], "properties": { "description": { "type": [ "string", "null" ] }, "executed_at": { "type": [ "string", "null" ], "format": "date-time" }, "intent": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "string" }, "rejected_at": { "type": [ "string", "null" ], "format": "date-time" }, "rejected_reason": { "type": [ "string", "null" ] }, "ref": { "$ref": "#/components/schemas/Ref" }, "requires_2fa": { "type": "boolean" }, "requires_rcp": { "type": "boolean" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/Section" } }, "status": { "type": "string" }, "terms": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } } } }, "TemplateCreate": { "type": "object", "description": "Template creation payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string", "enum": [ "binding", "nonbinding" ] }, "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "requires_2fa": { "type": "integer", "enum": [ 0, 1 ] }, "requires_rcp": { "type": "integer", "enum": [ 0, 1 ] } } }, "TemplateUpdate": { "type": "object", "description": "Template update payload.", "additionalProperties": false, "properties": { "description": { "type": [ "string", "null" ] }, "intent": { "type": "string", "enum": [ "binding", "nonbinding" ] }, "name": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "requires_2fa": { "type": "integer", "enum": [ 0, 1 ] }, "requires_rcp": { "type": "integer", "enum": [ 0, 1 ] } } }, "ContactCreate": { "type": "object", "description": "Contact creation payload.", "additionalProperties": false, "required": [ "email", "name" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "ContactUpdate": { "type": "object", "description": "Contact update payload.", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "organization": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "Attachment": { "type": "object", "description": "Canonical attachment resource.", "required": [ "checksum", "checksum_algorithm", "description", "kind", "name", "ref", "url" ], "properties": { "checksum": { "type": [ "string", "null" ] }, "checksum_algorithm": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "file", "url" ] }, "name": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" }, "url": { "type": [ "string", "null" ] } } }, "AttachmentCreate": { "type": "object", "description": "Attachment creation payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "content_base64": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "file", "url" ] }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "AttachmentUpdate": { "type": "object", "description": "Attachment update payload.", "additionalProperties": false, "required": [ "name" ], "properties": { "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "file", "url" ] }, "name": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "CanonicalDocument": { "type": "object", "description": "Canonical agreement or template document payload.", "additionalProperties": true }, "Session": { "type": "object", "description": "Authenticated session continuation payload.", "additionalProperties": true }, "ProtocolState": { "type": "object", "description": "Current server-driven signing protocol state for the authenticated actor.", "enum": [ "idle", "authenticate", "confirm_authentication", "assign_rcp", "confirm_rcp", "verify_signature", "sign" ] }, "JsonSchema": { "type": "object", "description": "Inline JSON Schema document that validates the next action request body.", "additionalProperties": true }, "ProtocolAction": { "type": "object", "description": "Single next action exposed by the signing protocol.", "required": [ "description", "method", "name", "schema", "url" ], "properties": { "description": { "type": "string" }, "method": { "type": "string", "enum": [ "POST" ] }, "name": { "type": "string", "enum": [ "create_authentication", "create_rcp_assignment", "create_rcp_confirmation", "create_signature", "create_verification_confirmation" ] }, "schema": { "$ref": "#/components/schemas/JsonSchema" }, "url": { "type": "string" } } }, "Protocol": { "type": "object", "description": "Current protocol state and next action for agreement signing.", "required": [ "action", "state" ], "properties": { "state": { "$ref": "#/components/schemas/ProtocolState" }, "action": { "anyOf": [ { "$ref": "#/components/schemas/ProtocolAction" }, { "type": "null" } ] } } }, "SignatureVerification": { "type": "object", "description": "Signature or signing authentication verification challenge.", "required": [ "channel", "expires_at", "ref" ], "properties": { "channel": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "Signature": { "type": "object", "description": "Canonical agreement signature record.", "required": [ "created_at", "ref", "requires_2fa" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "ref": { "$ref": "#/components/schemas/Ref" }, "requires_2fa": { "type": "boolean" } } }, "AuthenticationCreate": { "type": "object", "description": "Signing authentication payload.", "additionalProperties": false, "properties": { "password": { "type": [ "string", "null" ] } } }, "AuthenticationResponse": { "type": "object", "description": "Signing authentication result payload.", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/Session" }, "verification": { "$ref": "#/components/schemas/SignatureVerification" } } } } }, "VerificationCode": { "type": "object", "description": "Verification code payload.", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "SignatureCreate": { "type": "object", "description": "Signature creation payload.", "additionalProperties": false, "properties": { "legal_affirmed": { "type": "boolean" } } }, "SignatureCreateResponse": { "type": "object", "description": "Signature creation result payload.", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "agreement" ], "properties": { "agreement": { "$ref": "#/components/schemas/Agreement" }, "signature": { "$ref": "#/components/schemas/Signature" }, "verification": { "$ref": "#/components/schemas/SignatureVerification" } } } } }, "RcpExpectedActor": { "type": "object", "description": "Actor identity attached to a remote confirmation requirement.", "required": [ "name", "ref" ], "properties": { "name": { "type": "string" }, "ref": { "type": [ "string", "null" ], "format": "uuid" } } }, "RcpIncomingRequirement": { "type": "object", "description": "Incoming remote confirmation requirement for the authenticated actor.", "required": [ "confirmed_at", "expected_from", "token" ], "properties": { "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "expected_from": { "anyOf": [ { "$ref": "#/components/schemas/RcpExpectedActor" }, { "type": "null" } ] }, "token": { "type": "string" } } }, "RcpOutgoingAssignment": { "type": "object", "description": "Outgoing remote confirmation assignment issued by the authenticated actor.", "required": [ "code", "confirmed_at", "recipient", "token" ], "properties": { "code": { "type": "string" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "recipient": { "anyOf": [ { "$ref": "#/components/schemas/RcpExpectedActor" }, { "type": "null" } ] }, "token": { "type": "string" } } }, "RcpContext": { "type": "object", "description": "Remote confirmation party context for an agreement.", "required": [ "completed_count", "incoming_requirement", "outgoing_assignment", "ready", "total_count" ], "properties": { "completed_count": { "type": "integer" }, "incoming_requirement": { "anyOf": [ { "$ref": "#/components/schemas/RcpIncomingRequirement" }, { "type": "null" } ] }, "outgoing_assignment": { "anyOf": [ { "$ref": "#/components/schemas/RcpOutgoingAssignment" }, { "type": "null" } ] }, "ready": { "type": "boolean" }, "total_count": { "type": "integer" } } }, "RcpChallenge": { "type": "object", "description": "Remote confirmation challenge state.", "required": [ "code", "confirmed_at", "ref" ], "properties": { "code": { "type": "string" }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time" }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "RcpConfirmation": { "type": "object", "description": "Remote confirmation completion payload.", "additionalProperties": false, "required": [ "attested", "code", "token" ], "properties": { "attested": { "type": "boolean" }, "code": { "type": "string" }, "token": { "type": "string" } } }, "ParticipantActor": { "type": "object", "description": "Linked actor identity for an active participant.", "required": [ "ref" ], "properties": { "kind": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" } } }, "Participant": { "type": "object", "description": "Canonical agreement participant resource.", "required": [ "active", "actor", "avatar_url", "email", "name", "ref", "type" ], "properties": { "active": { "type": "boolean" }, "actor": { "anyOf": [ { "$ref": "#/components/schemas/ParticipantActor" }, { "type": "null" } ] }, "avatar_url": { "type": [ "string", "null" ] }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "ref": { "$ref": "#/components/schemas/Ref" }, "type": { "type": "string", "enum": [ "commentor", "editor", "signer", "viewer" ] } } }, "InvitationPartial": { "type": "object", "description": "Partial invitation resource returned when participant creation requires recipient acceptance.", "required": [ "email", "ref", "type" ], "properties": { "email": { "type": "string", "format": "email" }, "ref": { "$ref": "#/components/schemas/Ref" }, "type": { "type": "string", "enum": [ "commentor", "editor", "signer", "viewer" ] } } }, "InvitationReference": { "type": "object", "description": "Invitation reference returned by invitation lifecycle events.", "required": [ "ref" ], "properties": { "ref": { "$ref": "#/components/schemas/Ref" } } }, "ParticipantCreate": { "type": "object", "description": "Participant creation payload.", "additionalProperties": false, "required": [ "email", "name", "type" ], "properties": { "agent_ref": { "anyOf": [ { "$ref": "#/components/schemas/Ref" }, { "type": "null" } ] }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "commentor", "editor", "signer", "viewer" ] } } }, "ParticipantUpdate": { "type": "object", "description": "Participant update payload.", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "commentor", "editor", "signer", "viewer" ] } } }, "ParticipantSelfJoinCreate": { "type": "object", "description": "Participant self-join payload.", "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "editor", "signer" ] } } }, "Pagination": { "type": "object", "description": "Standard paginated collection metadata.", "required": [ "page", "page_size", "total_pages", "total_records" ], "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_pages": { "type": "integer" }, "total_records": { "type": "integer" } } }, "Error": { "type": "object", "description": "Standard API error envelope.", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "status" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "status": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } } } }