{ "openapi": "3.1.0", "info": { "title": "ScriptureLayer API (proposed)", "version": "0.2.0-proposal", "summary": "A proposed contract for source-linked Bible research. Not deployed.", "description": "Status: proposed design only. No endpoints are deployed, no servers are listed, and no API keys are issued. Nothing in this file describes a running service.\n\nThe API is planned as the connection that lets other software request research from ScriptureLayer and receive structured results: passages with their exact text and source links, cross-references, source-linked research drafts, saved collections, teaching outputs that require human review, permissioned libraries, and background processing jobs. Developer and institutional access is planned after the research workspace.\n\nEvery example value is illustrative. Examples that quote Scripture reuse the prepared demonstration on the ScriptureLayer website; they are not live responses.\n\nDesign principles:\n- Exact quotations travel with their reference and a source link.\n- Every statement in a research draft cites the passage or resource it rests on.\n- Each draft states its origin, so prepared material is never presented as generated.\n- Libraries contain only public-domain, owned, or licensed material, and access rules apply during retrieval.\n- Teaching outputs remain drafts until a person approves them.\n- Access would be authenticated and metered per request.", "x-status": "proposed" }, "servers": [], "tags": [ { "name": "Passages", "description": "Passage text with stable references and source links." }, { "name": "Cross-references", "description": "Connections between passages, with the basis for each." }, { "name": "Research", "description": "Source-linked research drafts." }, { "name": "Collections", "description": "Saved research collections." }, { "name": "Outputs", "description": "Teaching outputs that require human review." }, { "name": "Libraries", "description": "Permissioned resource libraries and ingestion." }, { "name": "Jobs", "description": "Background processing for large archives." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/passages": { "get": { "operationId": "getPassage", "tags": [ "Passages" ], "summary": "Retrieve a passage", "description": "Returns the exact text of a passage, its stable identifier, and a link to the source edition.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/Reference" }, { "in": "query", "name": "related", "required": false, "description": "Include identifiers of related passages.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Passage" }, "examples": { "john_1_1": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "passage_id": "JHN.1.1", "reference": "John 1:1", "text": "In the beginning was the Word, and the Word was with God, and the Word was God.", "source": { "edition": "KJV", "url": "https://www.biblegateway.com/passage/?search=John%201%3A1&version=KJV" }, "related_passages": [ "GEN.1.1", "JHN.1.14" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/cross-references": { "get": { "operationId": "listCrossReferences", "tags": [ "Cross-references" ], "summary": "List cross-references for a passage", "description": "Returns passages connected to the given reference, with the relation and the stated basis for each connection.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/Reference" }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CrossReferenceList" }, "examples": { "john_1_1": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "reference": "John 1:1", "items": [ { "to_reference": "Genesis 1:1", "relation": "verbal_parallel", "basis": "Both passages open with the words “In the beginning.”", "review_state": "reviewed" }, { "to_reference": "John 1:14", "relation": "same_passage", "basis": "Later in the same chapter, John states that the Word was made flesh.", "review_state": "reviewed" } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/research": { "post": { "operationId": "createResearchDraft", "tags": [ "Research" ], "summary": "Request a source-linked research draft", "description": "Retrieves passages and permitted resource excerpts that bear on a question and returns a draft in which every finding cites its evidence. The draft states its origin and review state.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchRequest" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "question": "How does John introduce the Word?", "library_ids": [ "lib_example_study" ], "max_citations": 8 } } } } } }, "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchDraft" }, "examples": { "john_1": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "research_id": "res_example_word", "origin": "prepared_demonstration", "question": "How does John introduce the Word?", "topics": [ "John 1", "Creation", "Incarnation" ], "note": { "title": "The Word, creation, and incarnation.", "findings": [ { "text": "John begins with the Word already present “in the beginning.”", "citations": [ "a" ] }, { "text": "Genesis opens with God creating the heaven and the earth.", "citations": [ "b" ] }, { "text": "John later states that the Word was made flesh.", "citations": [ "c" ] } ], "guidance": "Read the passages together, while preserving the distinct claim each one makes." }, "citations": [ { "marker": "a", "reference": "John 1:1", "quotation": "In the beginning was the Word, and the Word was with God, and the Word was God.", "source_url": "https://www.biblegateway.com/passage/?search=John%201%3A1&version=KJV", "context_url": "https://www.biblegateway.com/passage/?search=John%201&version=KJV" }, { "marker": "b", "reference": "Genesis 1:1", "quotation": "In the beginning God created the heaven and the earth.", "source_url": "https://www.biblegateway.com/passage/?search=Genesis%201%3A1&version=KJV", "context_url": "https://www.biblegateway.com/passage/?search=Genesis%201&version=KJV" }, { "marker": "c", "reference": "John 1:14", "quotation": "And the Word was made flesh, and dwelt among us, (and we beheld his glory, the glory as of the only begotten of the Father,) full of grace and truth.", "source_url": "https://www.biblegateway.com/passage/?search=John%201%3A14&version=KJV", "context_url": "https://www.biblegateway.com/passage/?search=John%201&version=KJV" } ], "checks": { "quotations_verified": true, "unsupported_statements": 0 }, "review": { "state": "requires_human_review" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/research/{research_id}": { "get": { "operationId": "getResearchDraft", "tags": [ "Research" ], "summary": "Retrieve a research draft", "description": "Returns a previously created research draft.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/ResearchId" } ], "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchDraft" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/collections": { "post": { "operationId": "createCollection", "tags": [ "Collections" ], "summary": "Create a saved research collection", "description": "Creates a private or team collection for gathering passages, findings, and resource excerpts.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "name": "Careful study", "description": "Passages for a lesson on studying Scripture.", "visibility": "private" } } } } } }, "responses": { "201": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "collection_id": "col_example_study", "name": "Careful study", "description": "Passages for a lesson on studying Scripture.", "visibility": "private", "item_count": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/collections/{collection_id}/items": { "post": { "operationId": "addCollectionItem", "tags": [ "Collections" ], "summary": "Add an item to a collection", "description": "Adds a passage, research finding, or resource excerpt to a collection. Passage items store the exact quotation and source link.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/CollectionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionItemCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "type": "passage", "reference": "Acts 17:11", "note": "Opening text for the lesson on careful study." } } } } } }, "responses": { "201": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionItem" }, "examples": { "acts_17_11": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "item_id": "itm_example_1", "collection_id": "col_example_study", "type": "passage", "reference": "Acts 17:11", "quotation": "These were more noble than those in Thessalonica, in that they received the word with all readiness of mind, and searched the scriptures daily, whether those things were so.", "source_url": "https://www.biblegateway.com/passage/?search=Acts%2017%3A11&version=KJV", "note": "Opening text for the lesson on careful study." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/outputs": { "post": { "operationId": "createOutput", "tags": [ "Outputs" ], "summary": "Draft a teaching output for review", "description": "Drafts a lesson outline, sermon notes, or study guide from a collection. Every point cites its passages, and the output stays a draft until a person approves it.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutputCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "collection_id": "col_example_study", "format": "lesson_outline", "title": "What careful study looks like" } } } } } }, "responses": { "201": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Output" }, "examples": { "lesson_outline": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "output_id": "out_example_1", "collection_id": "col_example_study", "format": "lesson_outline", "title": "What careful study looks like", "state": "draft", "sections": [ { "heading": "Receive and search", "points": [ { "text": "Acts describes the Bereans receiving the word with readiness and examining the Scriptures daily.", "citations": [ "Acts 17:11" ] } ] }, { "heading": "Study with diligence", "points": [ { "text": "Paul’s instruction to Timothy emphasizes diligence and rightly dividing the word of truth.", "citations": [ "2 Timothy 2:15" ] } ] } ], "review": { "state": "requires_human_review", "reviewer": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/outputs/{output_id}/review": { "post": { "operationId": "reviewOutput", "tags": [ "Outputs" ], "summary": "Record a review decision", "description": "Records a person's decision on a teaching output: approve it, or request changes with a comment.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/OutputId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewDecision" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "decision": "request_changes", "comment": "Add the surrounding verses for the second point." } } } } } }, "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Output" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/libraries": { "post": { "operationId": "createLibrary", "tags": [ "Libraries" ], "summary": "Create a permissioned library", "description": "Creates a library that will hold only public-domain, owned, or licensed resources.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LibraryCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "name": "Ministry teaching archive", "rights_basis": [ "owned" ] } } } } } }, "responses": { "201": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Library" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "library_id": "lib_example_ministry", "name": "Ministry teaching archive", "rights_basis": [ "owned" ], "resource_count": 0 } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/libraries/{library_id}/resources": { "post": { "operationId": "addResource", "tags": [ "Libraries" ], "summary": "Register a resource for ingestion", "description": "Registers a resource with its rights basis and attribution. Processing happens later in a background job.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/LibraryId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "title": "Sunday evening Bible study transcripts", "rights_basis": "owned", "attribution": "Example Ministry", "source": { "type": "upload", "upload_id": "upl_example_1" } } } } } } }, "responses": { "202": { "description": "Proposed accepted response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resource" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "resource_id": "rsc_example_1", "library_id": "lib_example_ministry", "title": "Sunday evening Bible study transcripts", "rights_basis": "owned", "attribution": "Example Ministry", "ingestion_state": "pending_processing" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/jobs": { "post": { "operationId": "createJob", "tags": [ "Jobs" ], "summary": "Queue a background processing job", "description": "Queues bounded background work on a library: indexing, extracting Scripture references, or preparing research drafts for review.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobCreate" }, "examples": { "example": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "library_id": "lib_example_ministry", "type": "extract_references", "limits": { "max_documents": 100 } } } } } } }, "responses": { "202": { "description": "Proposed accepted response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "examples": { "extract_references": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "job_id": "job_example_1", "library_id": "lib_example_ministry", "type": "extract_references", "state": "queued", "limits": { "max_documents": 100 }, "progress": { "documents_processed": 0, "documents_total": 100 }, "notify": { "event": "job.completed" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/v1/jobs/{job_id}": { "get": { "operationId": "getJob", "tags": [ "Jobs" ], "summary": "Check a job", "description": "Returns the state and progress of a background job.\n\nProposed contract only. This endpoint is not deployed. Authentication, permissions, metering, storage, and model integration remain to be implemented.", "x-status": "proposed", "parameters": [ { "$ref": "#/components/parameters/JobId" } ], "responses": { "200": { "description": "Proposed successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } }, "webhooks": { "jobCompleted": { "post": { "summary": "Job completed (proposed)", "description": "Proposed notification sent when a background job finishes. Not implemented.", "x-status": "proposed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobEvent" }, "examples": { "job_completed": { "summary": "Illustrative example. Not a live response; no endpoint is deployed.", "value": { "event": "job.completed", "job_id": "job_example_1", "state": "completed" } } } } } }, "responses": { "204": { "description": "Receiver acknowledged the notification." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Proposed token authentication. Not implemented, and no keys are issued." } }, "parameters": { "Reference": { "in": "query", "name": "reference", "required": true, "description": "A Scripture reference such as John 1:1.", "schema": { "type": "string" }, "example": "John 1:1" }, "ResearchId": { "in": "path", "name": "research_id", "required": true, "schema": { "type": "string" } }, "CollectionId": { "in": "path", "name": "collection_id", "required": true, "schema": { "type": "string" } }, "OutputId": { "in": "path", "name": "output_id", "required": true, "schema": { "type": "string" } }, "LibraryId": { "in": "path", "name": "library_id", "required": true, "schema": { "type": "string" } }, "JobId": { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "The request was malformed, or the reference could not be recognized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Authentication required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "The caller cannot access this library or collection.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "No resource exists with that identifier.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Usage limit exceeded.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "SourceLink": { "type": "object", "required": [ "edition", "url" ], "properties": { "edition": { "type": "string", "description": "Edition of the source text." }, "url": { "type": "string", "format": "uri" } } }, "Passage": { "type": "object", "required": [ "passage_id", "reference", "text", "source" ], "properties": { "passage_id": { "type": "string", "description": "Stable identifier, e.g. JHN.1.1." }, "reference": { "type": "string" }, "text": { "type": "string", "description": "The exact text, unaltered." }, "source": { "$ref": "#/components/schemas/SourceLink" }, "related_passages": { "type": "array", "items": { "type": "string" } } } }, "CrossReference": { "type": "object", "required": [ "to_reference", "relation", "basis" ], "properties": { "to_reference": { "type": "string" }, "relation": { "type": "string", "enum": [ "verbal_parallel", "same_passage", "quotation", "allusion", "theme" ] }, "basis": { "type": "string", "description": "Why the connection is listed, stated plainly." }, "review_state": { "type": "string", "enum": [ "reviewed", "unreviewed" ] } } }, "CrossReferenceList": { "type": "object", "required": [ "reference", "items" ], "properties": { "reference": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CrossReference" } } } }, "ResearchRequest": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "maxLength": 4000 }, "library_ids": { "type": "array", "items": { "type": "string" }, "description": "Permissioned libraries the draft may draw on." }, "max_citations": { "type": "integer", "minimum": 1, "maximum": 20, "default": 8 } } }, "Finding": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Markers of the citations this statement rests on." } } }, "Citation": { "type": "object", "required": [ "marker", "reference", "quotation", "source_url" ], "properties": { "marker": { "type": "string" }, "reference": { "type": "string" }, "quotation": { "type": "string", "description": "The exact quoted text." }, "source_url": { "type": "string", "format": "uri" }, "context_url": { "type": "string", "format": "uri", "description": "Link to the surrounding chapter or section." }, "resource_id": { "type": "string", "description": "Present when the citation is a library resource rather than Scripture." } } }, "Review": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "requires_human_review", "reviewed", "changes_requested", "approved" ] }, "reviewer": { "type": [ "string", "null" ] }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ResearchDraft": { "type": "object", "required": [ "research_id", "origin", "question", "note", "citations", "review" ], "properties": { "research_id": { "type": "string" }, "origin": { "type": "string", "enum": [ "retrieval_and_synthesis", "prepared_demonstration" ], "description": "How the draft was produced. Prepared material is always labeled as such." }, "question": { "type": "string" }, "topics": { "type": "array", "items": { "type": "string" } }, "note": { "type": "object", "required": [ "title", "findings" ], "properties": { "title": { "type": "string" }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }, "guidance": { "type": "string" } } }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/Citation" } }, "checks": { "type": "object", "properties": { "quotations_verified": { "type": "boolean" }, "unsupported_statements": { "type": "integer", "minimum": 0 } } }, "review": { "$ref": "#/components/schemas/Review" } } }, "CollectionCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "team" ], "default": "private" } } }, "Collection": { "type": "object", "required": [ "collection_id", "name", "visibility" ], "properties": { "collection_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "team" ] }, "item_count": { "type": "integer", "minimum": 0 } } }, "CollectionItemCreate": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "passage", "finding", "resource_excerpt" ] }, "reference": { "type": "string" }, "research_id": { "type": "string" }, "finding_index": { "type": "integer", "minimum": 0 }, "note": { "type": "string" } } }, "CollectionItem": { "type": "object", "required": [ "item_id", "collection_id", "type" ], "properties": { "item_id": { "type": "string" }, "collection_id": { "type": "string" }, "type": { "type": "string", "enum": [ "passage", "finding", "resource_excerpt" ] }, "reference": { "type": "string" }, "quotation": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "note": { "type": "string" } } }, "OutputCreate": { "type": "object", "required": [ "collection_id", "format" ], "properties": { "collection_id": { "type": "string" }, "format": { "type": "string", "enum": [ "lesson_outline", "sermon_notes", "study_guide" ] }, "title": { "type": "string" } } }, "Output": { "type": "object", "required": [ "output_id", "format", "state", "sections", "review" ], "properties": { "output_id": { "type": "string" }, "collection_id": { "type": "string" }, "format": { "type": "string", "enum": [ "lesson_outline", "sermon_notes", "study_guide" ] }, "title": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "approved" ] }, "sections": { "type": "array", "items": { "type": "object", "required": [ "heading", "points" ], "properties": { "heading": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "required": [ "text", "citations" ], "properties": { "text": { "type": "string" }, "citations": { "type": "array", "minItems": 1, "items": { "type": "string" } } } } } } } }, "review": { "$ref": "#/components/schemas/Review" } } }, "ReviewDecision": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "request_changes" ] }, "comment": { "type": "string" } } }, "LibraryCreate": { "type": "object", "required": [ "name", "rights_basis" ], "properties": { "name": { "type": "string" }, "rights_basis": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "owned", "licensed", "public_domain" ] } } } }, "Library": { "type": "object", "required": [ "library_id", "name", "rights_basis" ], "properties": { "library_id": { "type": "string" }, "name": { "type": "string" }, "rights_basis": { "type": "array", "items": { "type": "string", "enum": [ "owned", "licensed", "public_domain" ] } }, "resource_count": { "type": "integer", "minimum": 0 } } }, "ResourceCreate": { "type": "object", "required": [ "title", "rights_basis", "source" ], "properties": { "title": { "type": "string" }, "rights_basis": { "type": "string", "enum": [ "owned", "licensed", "public_domain" ] }, "attribution": { "type": "string" }, "source": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "upload", "url" ] }, "upload_id": { "type": "string" }, "url": { "type": "string", "format": "uri" } } } } }, "Resource": { "type": "object", "required": [ "resource_id", "library_id", "title", "rights_basis", "ingestion_state" ], "properties": { "resource_id": { "type": "string" }, "library_id": { "type": "string" }, "title": { "type": "string" }, "rights_basis": { "type": "string", "enum": [ "owned", "licensed", "public_domain" ] }, "attribution": { "type": "string" }, "ingestion_state": { "type": "string", "enum": [ "pending_processing", "processing", "ready", "failed" ] } } }, "JobCreate": { "type": "object", "required": [ "library_id", "type" ], "properties": { "library_id": { "type": "string" }, "type": { "type": "string", "enum": [ "index_library", "extract_references", "prepare_research_drafts" ] }, "limits": { "type": "object", "properties": { "max_documents": { "type": "integer", "minimum": 1 } } } } }, "Job": { "type": "object", "required": [ "job_id", "library_id", "type", "state" ], "properties": { "job_id": { "type": "string" }, "library_id": { "type": "string" }, "type": { "type": "string", "enum": [ "index_library", "extract_references", "prepare_research_drafts" ] }, "state": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ] }, "limits": { "type": "object", "properties": { "max_documents": { "type": "integer", "minimum": 1 } } }, "progress": { "type": "object", "properties": { "documents_processed": { "type": "integer", "minimum": 0 }, "documents_total": { "type": "integer", "minimum": 0 } } }, "notify": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "job.completed" ] } } } } }, "JobEvent": { "type": "object", "required": [ "event", "job_id", "state" ], "properties": { "event": { "type": "string", "enum": [ "job.completed" ] }, "job_id": { "type": "string" }, "state": { "type": "string", "enum": [ "completed", "failed" ] } } }, "Problem": { "type": "object", "required": [ "title", "status" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" } } } } } }