{ "openapi": "3.1.0", "info": { "title": "First AI Employee Forms authoring API", "version": "2026-09-05.1", "description": "The token selects the tenant. Lifecycle access requires fresh owner consent. Existing draft-edit and reviewed MCP scopes gain no lifecycle authority. New writes are audited and transactional. Authoring uses live entitlements and existing creation quotas. Close and empty-draft deletion remain available after module deactivation. Client API launch gates and authenticated rate limits apply. Honor Retry-After. Source support does not certify deployment or activation." }, "servers": [ { "url": "https://api.firstaiemployee.com/api/client/v1/forms" } ], "paths": { "/": { "post": { "operationId": "createForm", "summary": "Create an unpublished draft", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Create" } } } }, "responses": { "201": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listForms", "summary": "List forms without draft documents", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "enum": [ "draft", "published", "closed" ] } }, { "name": "updated_since", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "fields", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Live keyset page. Deduplicate by id and reconcile after concurrent edits. Draft definitions require individual reads.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "page", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } }, "page": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{id}": { "get": { "operationId": "getForm", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "fields", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated fields. Select definition explicitly to read the draft." } ], "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteEmptyFormDraft", "summary": "Delete only a never-published draft with no response or revision history", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalWrite" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Deleted" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{id}/duplicate": { "post": { "operationId": "duplicateForm", "summary": "Copy a definition and stable child references into a new draft", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Duplicate" } } } }, "responses": { "201": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{id}/publish-preview": { "post": { "operationId": "prepareFormPublish", "summary": "Review the exact publish candidate", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/PreparedPreview" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "description": "No publication occurs. Preview tokens expire after ten minutes. Reuse this Idempotency-Key for publication. Do not log or persist the token." } }, "/{id}/publish": { "post": { "operationId": "publishForm", "summary": "Publish the explicitly approved preview as a new immutable revision", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publish" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{id}/close": { "post": { "operationId": "closeForm", "summary": "Stop collection without deleting history", "security": [ { "OAuth2": [ "forms:lifecycle" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{16,128}$" }, "description": "One value only. Successful mutation receipts remain valid for 24 hours. The scope includes tenant, application, grant, action and form." }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\"v1:[a-f0-9]{32}\"$" }, "description": "One current strong ETag. The body must also contain the current draft revision." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalWrite" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Form" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/validate": { "post": { "operationId": "validateFormDefinition", "security": [ { "OAuth2": [ "forms:write" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Validate" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Validation" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/{id}:applyOperations": { "post": { "operationId": "applyFormOperations", "summary": "Atomically edit the draft without changing the published version", "security": [ { "OAuth2": [ "forms:write" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,254}$" }, "description": "The existing draft-edit key accepts 8 to 255 characters. One value only. Replay retention is 24 hours." }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 1024 }, "description": "Optional. A supplied header must contain up to eight valid strong tags. At least one must match. The body draft revision remains mandatory." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Apply" } } } }, "responses": { "200": { "description": "The committed result, or its retained replay receipt.", "headers": { "ETag": { "schema": { "type": "string" } }, "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "data", "meta" ], "properties": { "data": { "$ref": "#/components/schemas/Applied" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/schema.json": { "get": { "operationId": "formsAuthoringSchema", "security": [ { "OAuth2": [ "front_desk:forms:read" ] }, { "OAuth2": [ "forms:lifecycle" ] } ], "responses": { "200": { "description": "Structural JSON Schema. Semantic validation remains server-authoritative.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "428": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The shared Client API error envelope. Retry an uncertain server or connection failure with the same key and body.", "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Present when a retry delay applies." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Definition": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://api.firstaiemployee.com/api/client/v1/forms/schema.json", "$comment": "Contract version 2026-09-05.1", "title": "Forms authoring document", "type": "object", "required": [ "title", "fields" ], "description": "Structural checks only. POST /forms/validate runs the canonical semantic validator. Saving also checks references, logic, settings and owned assets. Validation never authorizes publication.", "additionalProperties": true, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "fields": { "type": "array", "items": { "type": "object", "required": [ "type", "title" ], "additionalProperties": true, "properties": { "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "email", "phone_number", "multiple_choice", "checkbox", "picture_choice", "dropdown", "yes_no", "opinion_scale", "rating", "nps", "number", "date", "time", "address", "website", "file_upload", "signature", "contact", "ranking", "matrix", "scheduler", "statement", "legal" ] }, "title": { "type": "string" } } } }, "theme": { "type": "object", "description": "The canonical validator checks colors, layout, fonts and tenant-owned image references." } } }, "Create": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/Definition" }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" } } }, "Duplicate": { "type": "object", "additionalProperties": false, "required": [ "ref", "expected_draft_revision" ], "properties": { "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } }, "Preview": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer", "minimum": 0 } } }, "Publish": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision", "expected_published_version", "preview_receipt", "confirmed" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer", "minimum": 0 }, "preview_receipt": { "type": "string", "minLength": 40, "maxLength": 2000 }, "confirmed": { "const": true } } }, "ConditionalWrite": { "type": "object", "additionalProperties": false, "required": [ "expected_draft_revision" ], "properties": { "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" } } }, "Validate": { "type": "object", "additionalProperties": false, "required": [ "definition" ], "properties": { "definition": { "$ref": "#/components/schemas/Definition" } } }, "Apply": { "type": "object", "additionalProperties": false, "required": [ "version", "expected_draft_revision", "operations" ], "properties": { "version": { "const": 1 }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "operations": { "type": "array", "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string" } } }, "description": "The closed operation vocabulary and semantic constraints are enforced by the canonical Forms operation parser." } } }, "Meta": { "type": "object", "required": [ "request_id", "version" ], "properties": { "request_id": { "type": "string" }, "version": { "const": "1" } }, "additionalProperties": true }, "Form": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "ref": { "type": "string", "pattern": "^[a-z0-9_-]{1,64}$" }, "title": { "type": "string" }, "status": { "enum": [ "draft", "published", "closed" ] }, "version": { "type": "integer" }, "draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "definition": { "$ref": "#/components/schemas/Definition" }, "received_responses": { "type": "integer" }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] } } }, "PreparedPreview": { "type": "object", "required": [ "preview_receipt", "definition", "fingerprint", "expires_at", "expected_draft_revision", "expected_published_version", "published" ], "properties": { "preview_receipt": { "type": "string" }, "definition": { "$ref": "#/components/schemas/Definition" }, "fingerprint": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "expected_draft_revision": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_published_version": { "type": "integer" }, "published": { "const": false }, "confirmation_instruction": { "type": "string" } } }, "Deleted": { "type": "object", "additionalProperties": false, "required": [ "id", "deleted", "scope" ], "properties": { "id": { "type": "string", "format": "uuid" }, "deleted": { "const": true }, "scope": { "const": "never_published_empty_draft" } } }, "Validation": { "type": "object", "properties": { "definition": { "$ref": "#/components/schemas/Definition" }, "warnings": { "type": "array" }, "publication_authorized": { "const": false }, "validation_scope": { "const": "definition_only" } } }, "Applied": { "type": "object", "properties": { "form": { "$ref": "#/components/schemas/Form" }, "applied": { "type": "object" }, "diff": { "type": "object" }, "warnings": { "type": "array" } } }, "Error": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id", "retryable" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "retryable": { "type": "boolean" }, "field": { "type": [ "string", "null" ] }, "details": { "type": "object" } } } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.firstaiemployee.com/oauth/authorize", "tokenUrl": "https://api.firstaiemployee.com/oauth/token", "scopes": { "front_desk:forms:read": "Read form metadata and drafts", "forms:write": "Edit saved drafts", "forms:lifecycle": "Owner-approved form lifecycle access" } } } } } } }