{ "openapi": "3.0.0", "info": { "title": "SciSummary API", "description": "API for summarizing scientific articles, papers, and documents", "contact": { "email": "contact@mail.scisummary.com" }, "version": "1.0.0" }, "servers": [ { "url": "/api", "description": "API Server" } ], "paths": { "/summary/{uuid}/regenerate": { "post": { "tags": [ "Batch" ], "summary": "Regenerate a summary", "operationId": "74fd7b90cc702dde337150df60ed625e", "parameters": [ { "name": "uuid", "in": "path", "description": "Summary UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "feedback": { "description": "Optional feedback for regeneration", "type": "string" }, "synchronous": { "description": "Whether to run synchronously", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Summary not found" } }, "security": [ { "sanctum": [] } ] } }, "/summary/{uuid}": { "delete": { "tags": [ "Batch" ], "summary": "Delete a summary", "operationId": "67e49874b02358326016ae4c32b341c2", "parameters": [ { "name": "uuid", "in": "path", "description": "Summary UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Summary deleted successfully" }, "403": { "description": "Forbidden" }, "404": { "description": "Summary not found" } }, "security": [ { "sanctum": [] } ] } }, "/batch": { "get": { "tags": [ "Batch" ], "summary": "Get all batches", "description": "Display a listing of the resource.", "operationId": "39b45e7c24e1d1f89c8476758c43f8a7", "responses": { "200": { "description": "Paginated list of batches", "content": { "application/json": { "schema": { "properties": { "page": { "description": "Current page number", "type": "integer" }, "data": { "type": "array", "items": { "type": "object" } }, "next": { "description": "Next page URL", "type": "string" }, "previous": { "description": "Previous page URL", "type": "string" }, "total": { "description": "Total number of items", "type": "integer" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Batch" ], "summary": "Create a new batch of summarization requests", "description": "Store a newly created resource in storage.", "operationId": "3939c737c703127fd57bc64a09ef8b78", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "texts": { "description": "Array of text strings to summarize", "type": "array", "items": { "type": "string" } }, "urls": { "description": "Array of URLs to crawl and summarize", "type": "array", "items": { "type": "string" } }, "pdf_urls": { "description": "Array of PDF URLs to download and summarize", "type": "array", "items": { "type": "string" } }, "document_uuids": { "description": "Array of existing document UUIDs to include in batch", "type": "array", "items": { "type": "string" } }, "word_count": { "description": "Override default word count", "type": "integer" }, "add_headings": { "description": "Whether to add headings (default: true)", "type": "boolean" }, "language": { "description": "Language for summaries (e.g., english, spanish, french)", "type": "string", "default": "english" }, "mode": { "description": "Summarization mode", "type": "string", "default": "summarize", "enum": [ "summarize", "eli5", "simplify" ] }, "length": { "description": "Summary length", "type": "string", "default": "medium", "enum": [ "short", "medium", "long" ] }, "area_of_focus": { "description": "Specific area to focus on", "type": "string" }, "dry_run": { "description": "Test without actually generating summaries", "type": "boolean" }, "synchronous": { "description": "Wait for summaries to complete before returning", "type": "boolean" } }, "type": "object" } }, "multipart/form-data": { "schema": { "properties": { "pdfs": { "description": "PDF files to upload and summarize", "type": "array", "items": { "type": "string", "format": "binary" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch created successfully", "content": { "application/json": { "schema": { "properties": { "uuid": { "type": "string" }, "user_id": { "type": "integer" }, "requests": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "400": { "description": "Invalid request body" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "sanctum": [] } ] } }, "/batch/{uuid}": { "get": { "tags": [ "Batch" ], "summary": "Get a specific batch", "description": "Display the specified resource.", "operationId": "0a1710a9a0049df09bfefd00bb9d2a53", "parameters": [ { "name": "uuid", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch details with requests and summaries", "content": { "application/json": { "schema": { "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "user_id": { "type": "integer" }, "requests": { "type": "array", "items": { "properties": { "uuid": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "summaries": { "type": "array", "items": { "properties": { "uuid": { "type": "string" }, "text": { "description": "Summary text", "type": "string" }, "config": { "description": "Summary configuration", "type": "object", "example": { "keyTerm": null, "originalTextChunkCount": 1, "detectedLanguage": "english", "prompt": "Summarize the research paper...", "skipStyler": false, "areaOfFocus": null, "sectionIds": [], "startPage": null, "endPage": null, "IMRAD": false, "summarizeUsingPrompt": true, "lengthOverride": "400", "host1VoiceActor": null, "host2VoiceActor": null, "levelOfExpertise": null, "audioSpeed": null, "mode": "summarize", "length": "medium", "language": "english", "acceptAllLengths": true, "isPaidFor": true, "newPrompt": false } } }, "type": "object" } }, "file": { "properties": { "path": { "type": "string" }, "original_filename": { "type": "string" } }, "type": "object" }, "url": { "properties": { "url": { "type": "string" }, "title": { "type": "string" } }, "type": "object" } }, "type": "object" } } }, "type": "object" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Batch not found" } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Batch" ], "summary": "Delete a batch", "description": "Remove the specified resource from storage.", "operationId": "199e996008a518d0a87989021a9ddd23", "parameters": [ { "name": "uuid", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Batch deleted successfully", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "type": "object" } } } }, "403": { "description": "Forbidden" } }, "security": [ { "sanctum": [] } ] } }, "/batch/{uuid}/summarize": { "post": { "tags": [ "Batch" ], "summary": "Trigger summarization for all requests in a batch", "operationId": "21dd270c6c830d8f90196200b6d75cf6", "parameters": [ { "name": "uuid", "in": "path", "description": "Batch UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "synchronous": { "description": "Wait for summaries to complete", "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Batch with updated summaries", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Batch not found" } }, "security": [ { "sanctum": [] } ] } }, "/request": { "get": { "tags": [ "Request" ], "summary": "Get all document requests", "description": "Display a listing of the resource.", "operationId": "971277a4fafe1071d39a1fe3717c3952", "parameters": [ { "name": "search", "in": "query", "description": "Search term for title, parsed_title, or abstract", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "description": "Comma-separated tag UUIDs to filter by", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of document requests", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/request/{uuid}": { "get": { "tags": [ "Request" ], "summary": "Get a specific document request", "description": "Display the specified resource.", "operationId": "0dc825d5116bdf76e9e89441f098600d", "parameters": [ { "name": "uuid", "in": "path", "description": "Request UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Request details with summaries", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "description": "Forbidden" }, "404": { "description": "Request not found" } }, "security": [ { "sanctum": [] } ] } }, "/summary/{uuid}/variations": { "get": { "tags": [ "Summary" ], "summary": "Get all variations (paraphrases) of a summary", "operationId": "9b509f2bb2ce5677e5a06873de9bc723", "parameters": [ { "name": "uuid", "in": "path", "description": "Summary UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of summary variations", "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "uuid": { "description": "Variation UUID", "type": "string" }, "summary_id": { "description": "Original summary ID", "type": "integer" }, "paraphrased_from_summary_id": { "description": "Parent summary ID", "type": "integer" }, "text": { "description": "Summary text", "type": "string" }, "config": { "description": "Summary configuration object", "type": "object", "example": { "keyTerm": null, "originalTextChunkCount": 1, "detectedLanguage": "english", "prompt": "Summarize the research paper...", "skipStyler": false, "areaOfFocus": null, "sectionIds": [], "startPage": null, "endPage": null, "IMRAD": false, "summarizeUsingPrompt": true, "lengthOverride": "400", "host1VoiceActor": null, "host2VoiceActor": null, "levelOfExpertise": null, "audioSpeed": null, "mode": "summarize", "length": "medium", "language": "english", "acceptAllLengths": true, "isPaidFor": true, "newPrompt": false } }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" } } } } }, "404": { "description": "Summary not found or access denied" } }, "security": [ { "sanctum": [] } ] } } }, "components": { "securitySchemes": { "sanctum": { "type": "apiKey", "description": "Enter token in format (Bearer )", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Batch", "description": "Batch operations for managing multiple summarization requests" }, { "name": "Request", "description": "Operations for managing individual document requests" }, { "name": "Summary", "description": "Summary" } ], "security": [ { "sanctum": [] } ] }