{"openapi":"3.1.0","info":{"title":"Lev-Al Prose API","version":"1.0.0","description":"Paid-plan API for MeaningLock contracts, editing, verification and Fidelity Passports. Passage text is processed in request memory only and is not stored or logged. The free passage cannot be used through the API."},"servers":[{"url":"https://levalprose.com/api/v1"}],"security":[{"integrationKey":[]}],"paths":{"/contracts":{"post":{"operationId":"createContract","summary":"Build a MeaningLock contract for a source text. No words deducted.","security":[{"integrationKey":["contract:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractResponse"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/edits":{"post":{"operationId":"runEdit","summary":"Edit one passage (max 500 words) into three verified revisions.","description":"Deducts the original input word count once, only after success. Failed runs are refunded.","security":[{"integrationKey":["edit:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–128 characters: letters, digits, '-', '_', '.', ':'. A repeated key never deducts twice.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditResponse"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_replayed or request_in_progress. Nothing was deducted again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"too_long or invalid_document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/verifications":{"post":{"operationId":"verifyRevision","summary":"Verify a revision against its source. No words deducted.","description":"Uses the same independent meaning review as Workspace. If that review is unavailable, the verdict is review_required, never preserved.","security":[{"integrationKey":["verify:run"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/documents":{"post":{"operationId":"runDocument","summary":"Edit pasted document text (max 5,000 words, 500-word sections).","description":"Pasted text only, sent as a JSON \"text\" field. .docx upload is not available through the API (415 pasted_text_only).","security":[{"integrationKey":["document:run"]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–128 characters: letters, digits, '-', '_', '.', ':'. A repeated key never deducts twice.","schema":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResponse"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_replayed or request_in_progress. Nothing was deducted again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Body has no \"text\" field (pasted_text_only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"too_long or invalid_document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/passports":{"post":{"operationId":"createPassport","summary":"Sign a Fidelity Passport for a fully verified revision. No words deducted.","description":"Send the source, the revision and the receipt returned with it by /edits, /verifications or /documents. The server rebuilds the Passport, re-runs the MeaningLock and length checks and reads the independent review from the receipt; self-declared statuses are never signed. A missing, forged or mismatched receipt returns 422 unverified. Failed or review_required revisions return 422 not_verified. Texts are used in request memory only; the Passport carries counts and salted digests, never passage text. A valid signature confirms the Passport is authentic and unaltered; it does not prove the source facts are true.","security":[{"integrationKey":["passport:create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PassportRequest"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PassportResponse"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unverified or not_verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/passports/verify":{"post":{"operationId":"verifyPassport","summary":"Check a Passport's Ed25519 signature. No words deducted.","security":[{"integrationKey":["passport:verify"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PassportCheck"}}}},"400":{"description":"Bad input (invalid_input, invalid_json, key_in_url, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked integration key (unauthenticated).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"No active paid plan (plan_inactive) or too few words (insufficient_allowance).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the scope this endpoint requires (insufficient_scope).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request body too large (too_large).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 30 requests per minute for this key (rate_limited).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Processing failed (processing_failed). Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service busy or signing unavailable. Nothing was deducted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"integrationKey":{"type":"http","scheme":"bearer","description":"Integration key (lvp_…) in the Authorization header. Keys in the URL are refused. Scopes: contract:create, edit:run, verify:run, document:run, passport:create, passport:verify."}},"schemas":{"Mode":{"type":"string","enum":["faithful","exact_length","tighten"],"default":"faithful"},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["unauthenticated","key_in_url","insufficient_scope","plan_inactive","insufficient_allowance","rate_limited","invalid_input","invalid_json","too_large","too_long","invalid_document","pasted_text_only","idempotency_key_required","idempotency_replayed","request_in_progress","not_verified","signing_unavailable","service_busy","processing_failed","not_found","method_not_allowed"]},"message":{"type":"string"}}}}},"Status":{"type":"string","enum":["preserved","review_required","failed"]},"Finding":{"type":"object","properties":{"category":{"type":"string"},"status":{"type":"string"},"explanation":{"type":["string","null"]}}},"Check":{"type":"object","properties":{"input_words":{"type":"integer"},"output_words":{"type":"integer"},"length":{"type":"object","properties":{"status":{"type":"string","enum":["met","review_required","not_applicable"]},"target":{"type":["integer","null"]},"message":{"type":"string"}}},"locks":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"meaning":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"deep_scan":{"type":"object"},"verdict":{"$ref":"#/components/schemas/Status"}}},"Version":{"allOf":[{"$ref":"#/components/schemas/Check"},{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"text":{"type":"string"},"unchanged":{"type":"boolean"}}}]},"ContractRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":40000},"mode":{"$ref":"#/components/schemas/Mode"},"target_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"exact_length only. Defaults to the input word count."},"max_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"tighten only."},"reduction_percent":{"type":["integer","null"],"minimum":5,"maximum":60,"description":"tighten only."},"locks":{"type":["array","null"],"maxItems":80,"items":{"type":"string","minLength":1,"maxLength":300},"description":"Extra phrases to keep exactly. Ignored unless they appear in the source."},"doc_type":{"type":["string","null"],"maxLength":80}}},"ContractResponse":{"type":"object","properties":{"contract":{"type":"object"},"review_required":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"reason":{"type":["string","null"]}}}}}},"EditRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":8000,"description":"1–500 words."},"mode":{"$ref":"#/components/schemas/Mode"},"target_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"exact_length only. Defaults to the input word count."},"max_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"tighten only."},"reduction_percent":{"type":["integer","null"],"minimum":5,"maximum":60,"description":"tighten only."},"locks":{"type":["array","null"],"maxItems":80,"items":{"type":"string","minLength":1,"maxLength":300},"description":"Extra phrases to keep exactly. Ignored unless they appear in the source."},"doc_type":{"type":["string","null"],"maxLength":80}}},"EditResponse":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/Mode"},"words_charged":{"type":"integer"},"remaining_words":{"type":"integer"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/Version"}}}},"VerifyRequest":{"type":"object","required":["source","revision"],"properties":{"source":{"type":"string","minLength":1,"maxLength":40000},"revision":{"type":"string","minLength":1,"maxLength":60000},"mode":{"$ref":"#/components/schemas/Mode"},"target_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"exact_length only. Defaults to the input word count."},"max_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"tighten only."},"reduction_percent":{"type":["integer","null"],"minimum":5,"maximum":60,"description":"tighten only."},"locks":{"type":["array","null"],"maxItems":80,"items":{"type":"string","minLength":1,"maxLength":300},"description":"Extra phrases to keep exactly. Ignored unless they appear in the source."},"doc_type":{"type":["string","null"],"maxLength":80}}},"VerifyResponse":{"allOf":[{"$ref":"#/components/schemas/Check"},{"type":"object","properties":{"review":{"type":"string","enum":["independent","unavailable"]},"passport_eligible":{"type":"boolean"}}}]},"DocumentRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":60000,"description":"Pasted plain text, up to 5,000 words."},"mode":{"$ref":"#/components/schemas/Mode"},"target_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"exact_length only. Defaults to the input word count."},"max_words":{"type":["integer","null"],"minimum":1,"maximum":5000,"description":"tighten only."},"reduction_percent":{"type":["integer","null"],"minimum":5,"maximum":60,"description":"tighten only."},"locks":{"type":["array","null"],"maxItems":80,"items":{"type":"string","minLength":1,"maxLength":300},"description":"Extra phrases to keep exactly. Ignored unless they appear in the source."},"doc_type":{"type":["string","null"],"maxLength":80}}},"DocumentResponse":{"type":"object","properties":{"input":{"type":"string","const":"pasted_text_only"},"mode":{"$ref":"#/components/schemas/Mode"},"words_charged":{"type":"integer"},"remaining_words":{"type":"integer"},"sections":{"type":"integer"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/Version"}}}},"Digest":{"type":"object","required":["algorithm","nonce","value"],"properties":{"algorithm":{"type":"string","const":"SHA-256"},"nonce":{"type":"string"},"value":{"type":"string"}}},"PassportRequest":{"type":"object","additionalProperties":false,"required":["source","revision","receipt"],"properties":{"source":{"type":"string","maxLength":60000},"revision":{"type":"string","maxLength":60000},"receipt":{"type":"string","description":"Returned with each verified revision."},"versionLabel":{"type":"string","maxLength":60},"documentType":{"type":"string","maxLength":60},"language":{"type":"string","maxLength":20},"mode":{"type":"string","enum":["faithful","exact_length","tighten"]},"targetWords":{"type":["integer","null"]},"maxWords":{"type":["integer","null"]},"reductionPercent":{"type":["integer","null"]},"locks":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":80}}},"PassportBody":{"type":"object","additionalProperties":false,"description":"Counts, statuses and salted digests only. No passage text is accepted.","required":["contractVersion","mode","documentType","language","versionLabel","inputWords","outputWords","targetWords","lengthStatus","lockCounts","locks","unsupportedClaims","changedWords","disclosures","inputDigest","outputDigest"],"properties":{"contractVersion":{"type":"string"},"mode":{"$ref":"#/components/schemas/Mode"},"documentType":{"type":"string","minLength":1,"maxLength":60},"language":{"type":"string","minLength":2,"maxLength":20},"versionLabel":{"type":"string","minLength":1,"maxLength":60},"inputWords":{"type":"integer","minimum":1,"maximum":5000},"outputWords":{"type":"integer","minimum":0,"maximum":10000},"targetWords":{"type":["integer","null"],"minimum":1,"maximum":5000},"lengthStatus":{"type":"string","enum":["met","review_required","not_applicable"]},"lockCounts":{"type":"object","properties":{"exact":{"type":"integer"},"numeric":{"type":"integer"},"structural":{"type":"integer"},"register":{"type":"integer"},"semantic":{"type":"integer"}}},"locks":{"type":"array","maxItems":400,"items":{"type":"object"}},"unsupportedClaims":{"type":"string","enum":["none_detected","review_required","not_checked"]},"changedWords":{"type":"integer","minimum":0,"maximum":10000},"disclosures":{"type":"array","maxItems":40,"items":{"type":"string","maxLength":300}},"inputDigest":{"$ref":"#/components/schemas/Digest"},"outputDigest":{"$ref":"#/components/schemas/Digest"}}},"PassportResponse":{"type":"object","properties":{"passport":{"type":"object","description":"The submitted body plus receiptId, issuedAt, schemaVersion and an Ed25519 signature."}}},"PassportCheck":{"type":"object","properties":{"valid":{"type":"boolean"},"reason":{"type":"string"},"key_id":{"type":"string"}}}}}}