{
    "openapi": "3.0.2",
    "info": {
        "title": "SciSummary API",
        "version": "1.0.0",
        "description": "SciSummary API lets you generate summaries of scientific articles in bulk.\n\nTo call the API you must sign up at https://scisummary.com and subscribe to the API. Learn more about pricing at https://scisummary.com/api/pricing.\n\n## Authentication\nAuthenticate every request with an API token. Create one at https://scisummary.com/api/tokens and set the `Authorization` header to your token (a raw token or a `Bearer <token>` value are both accepted).\n\n## Errors\nAll error responses share a consistent JSON envelope: `{ \"error\": { \"code\": \"...\", \"message\": \"...\", \"hint\": \"...\", \"status\": 000 } }`. Inspect `error.code` for programmatic handling and surface `error.message`/`error.hint` to end users.",
        "contact": {
            "name": "SciSummary Support",
            "email": "support@scisummary.com",
            "url": "https://scisummary.com/contact"
        },
        "license": {
            "name": "SciSummary Terms of Service",
            "url": "https://scisummary.com/terms-of-service"
        }
    },
    "externalDocs": {
        "description": "Human-readable API documentation and pricing",
        "url": "https://scisummary.com/api/documentation"
    },
    "servers": [
        {
            "url": "https://scisummary.com",
            "description": "Production. All requests should be sent to this host."
        }
    ],
    "tags": [
        {
            "name": "Batch",
            "description": "Create and retrieve batches of summarization requests."
        },
        {
            "name": "Request",
            "description": "Retrieve individual summarization requests and their summaries."
        }
    ],
    "paths": {
        "/api/batch": {
            "get": {
                "operationId": "listBatches",
                "tags": [
                    "Batch"
                ],
                "summary": "List batches",
                "description": "Returns a paginated list of every batch created with your account, most recent first.",
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "1-indexed page number of results to return.",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/PaginatedBatches"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                }
            },
            "post": {
                "operationId": "createBatch",
                "tags": [
                    "Batch"
                ],
                "summary": "Create batch",
                "description": "Creates a batch of summarization requests and kicks off the summarization jobs asynchronously. Poll GET /api/batch/{uuid} to retrieve summaries as they complete, or set `synchronous` to true to wait for the results in the response.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BatchRequest"
                            }
                        },
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/BatchRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Batch"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "422": {
                        "$ref": "#/components/responses/ValidationError"
                    }
                }
            }
        },
        "/api/batch/{uuid}": {
            "get": {
                "operationId": "getBatch",
                "tags": [
                    "Batch"
                ],
                "summary": "Get batch",
                "description": "Retrieve an entire batch of requests, including all summaries. The batch is populated as summaries are generated.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/BatchUuid"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Batch"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            },
            "delete": {
                "operationId": "deleteBatch",
                "tags": [
                    "Batch"
                ],
                "summary": "Delete batch",
                "description": "Permanently deletes a batch and all of its requests and summaries.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/BatchUuid"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The batch was deleted successfully."
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/batch/{uuid}/summarize": {
            "post": {
                "operationId": "summarizeBatch",
                "tags": [
                    "Batch"
                ],
                "summary": "Initialize or retry batch summaries",
                "description": "If you created the batch as a dry run, call this endpoint to trigger the summaries. You can also call it to retry summaries: every call creates a new set of summaries for each request in the batch.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/BatchUuid"
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/InitializeSummaryRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Batch"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        },
        "/api/request": {
            "get": {
                "operationId": "listRequests",
                "tags": [
                    "Request"
                ],
                "summary": "List requests",
                "description": "Returns the summarization requests associated with your account.",
                "responses": {
                    "200": {
                        "description": "List of requests associated with your account.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/Request"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    }
                }
            }
        },
        "/api/request/{uuid}": {
            "get": {
                "operationId": "getRequest",
                "tags": [
                    "Request"
                ],
                "summary": "Get request",
                "description": "Retrieve a single summarization request and its summaries by UUID.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/RequestUuid"
                    }
                ],
                "responses": {
                    "200": {
                        "$ref": "#/components/responses/Request"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                }
            }
        }
    },
    "components": {
        "parameters": {
            "BatchUuid": {
                "name": "uuid",
                "in": "path",
                "required": true,
                "description": "UUID of the batch.",
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            },
            "RequestUuid": {
                "name": "uuid",
                "in": "path",
                "required": true,
                "description": "UUID of the request.",
                "schema": {
                    "type": "string",
                    "format": "uuid"
                }
            }
        },
        "schemas": {
            "Error": {
                "title": "Error",
                "description": "Standard error envelope returned by every SciSummary API error response.",
                "type": "object",
                "required": [
                    "error"
                ],
                "properties": {
                    "error": {
                        "type": "object",
                        "required": [
                            "code",
                            "message",
                            "status"
                        ],
                        "properties": {
                            "code": {
                                "type": "string",
                                "description": "Machine-readable error code, e.g. `unauthenticated`, `forbidden`, `not_found`, `validation_failed`, `rate_limited`, `server_error`."
                            },
                            "message": {
                                "type": "string",
                                "description": "Human-readable description of what went wrong."
                            },
                            "hint": {
                                "type": "string",
                                "description": "Actionable suggestion for resolving the error."
                            },
                            "status": {
                                "type": "integer",
                                "description": "HTTP status code, mirrored here for convenience."
                            }
                        }
                    }
                },
                "example": {
                    "error": {
                        "code": "not_found",
                        "message": "The requested resource was not found.",
                        "hint": "Check the UUID, or list your batches at GET /api/batch.",
                        "status": 404
                    }
                }
            },
            "Request": {
                "title": "Request",
                "description": "A request to summarize an article.",
                "type": "object",
                "properties": {
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "text": {
                        "type": "string"
                    },
                    "from": {
                        "type": "string"
                    },
                    "to": {
                        "type": "string"
                    },
                    "message_id": {
                        "type": "string"
                    },
                    "subject": {
                        "type": "string"
                    },
                    "type": {
                        "type": "string",
                        "description": "Source type of the request, e.g. `pdf`, `url`, or `text`."
                    },
                    "filename": {
                        "type": "string"
                    },
                    "summaries": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Summary"
                        }
                    }
                },
                "example": {
                    "created_at": "2023-02-05 05:18",
                    "updated_at": "2023-02-05 05:18",
                    "uuid": "e131ea01-58c2-4a1d-a874-0494fc71174c",
                    "text": "Article...",
                    "from": "heckel.max@gmail.com",
                    "to": "api@scisummary.com",
                    "message_id": "",
                    "subject": "",
                    "type": "pdf",
                    "filename": "PIIS2589537023000172.pdf",
                    "summaries": [
                        {
                            "created_at": "2023-02-05T05:20:11.000000Z",
                            "updated_at": "2023-02-05T05:20:11.000000Z",
                            "uuid": "9b29fe13-ce11-475e-a4ce-d47daaf33487",
                            "request_id": 7,
                            "text": "Summarized..."
                        }
                    ]
                }
            },
            "Batch": {
                "title": "Batch",
                "description": "A batch of requests to summarize articles.",
                "type": "object",
                "properties": {
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "requests": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Request"
                        }
                    }
                },
                "example": {
                    "created_at": "2023-02-05T05:18:57.000000Z",
                    "updated_at": "2023-02-05T05:18:57.000000Z",
                    "uuid": "8019f0de-99a5-4c9f-a9e2-54b667e0cb64",
                    "requests": []
                }
            },
            "Summary": {
                "title": "Summary",
                "description": "A summary of an article.",
                "type": "object",
                "properties": {
                    "created_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "updated_at": {
                        "type": "string",
                        "format": "date-time"
                    },
                    "uuid": {
                        "type": "string",
                        "format": "uuid"
                    },
                    "request_id": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "text": {
                        "type": "string"
                    },
                    "rank": {
                        "type": "string"
                    }
                },
                "example": {
                    "created_at": "2023-02-05T05:20:11.000000Z",
                    "updated_at": "2023-02-05T05:20:11.000000Z",
                    "uuid": "9b29fe13-ce11-475e-a4ce-d47daaf33487",
                    "request_id": 7,
                    "text": "Summarized"
                }
            },
            "BatchRequest": {
                "title": "BatchRequest",
                "description": "Payload for creating a batch of summarization requests. Provide at least one of `texts`, `urls`, `pdf_urls`, or `pdfs[]`.",
                "type": "object",
                "properties": {
                    "texts": {
                        "description": "Array of raw article text to be summarized.",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "urls": {
                        "description": "Array of URLs whose article contents should be summarized.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "pdf_urls": {
                        "description": "Array of URLs pointing directly to PDF files.",
                        "type": "array",
                        "items": {
                            "type": "string",
                            "format": "uri"
                        }
                    },
                    "pdfs[]": {
                        "description": "Only works for multipart/form-data request bodies. An array of PDF files.",
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/File"
                        }
                    },
                    "synchronous": {
                        "description": "Whether to run this batch synchronously and return the summaries in the response. Defaults to false.",
                        "type": "boolean",
                        "default": false
                    },
                    "dry_run": {
                        "description": "When true, requests are stored and token counts computed but no summaries are generated. Trigger them later with POST /api/batch/{uuid}/summarize.",
                        "type": "boolean",
                        "default": false
                    },
                    "word_count": {
                        "description": "Approximate number of words the summary should be. Takes precedence over `length` when both are provided.",
                        "type": "number"
                    },
                    "mode": {
                        "description": "The summary mode.\n\n* summarize: standard summary mode\n* simplify: simplify and summarize\n* keypoints: get key points\n* future_research: opportunities for future research\n* abstract: write the abstract for this paper\n* sentences: key sentences for this paper\n* questions: key questions to ask about this paper\n* overview_and_keypoints: key points followed by a summary",
                        "type": "string",
                        "enum": [
                            "summarize",
                            "simplify",
                            "keypoints",
                            "future_research",
                            "abstract",
                            "sentences",
                            "questions",
                            "overview_and_keypoints"
                        ]
                    },
                    "length": {
                        "description": "How long the summaries should be.",
                        "type": "string",
                        "enum": [
                            "short",
                            "medium",
                            "long"
                        ]
                    },
                    "language": {
                        "description": "Language the results should be translated to, e.g. `english`, `spanish`, `french`, `german`, `chinese`, `japanese`.",
                        "type": "string"
                    }
                },
                "example": {
                    "urls": [
                        "https://article.one",
                        "https://article.two"
                    ],
                    "mode": "summarize",
                    "length": "medium"
                }
            },
            "File": {
                "title": "File",
                "description": "A binary file upload (PDF).",
                "type": "string",
                "format": "binary"
            },
            "InitializeSummaryRequest": {
                "title": "InitializeSummaryRequest",
                "description": "Options for triggering summaries on an existing (dry-run) batch.",
                "type": "object",
                "properties": {
                    "synchronous": {
                        "description": "Whether to wait for the summaries to complete before responding.",
                        "type": "boolean",
                        "default": false
                    }
                },
                "example": {
                    "synchronous": true
                }
            },
            "PaginatedBatches": {
                "title": "PaginatedBatches",
                "description": "Paginated list of batches.",
                "type": "object",
                "properties": {
                    "page": {
                        "type": "integer",
                        "format": "int32"
                    },
                    "data": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "created_at": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "updated_at": {
                                    "type": "string",
                                    "format": "date-time"
                                },
                                "uuid": {
                                    "type": "string",
                                    "format": "uuid"
                                }
                            }
                        }
                    },
                    "next": {
                        "type": "string",
                        "nullable": true
                    },
                    "previous": {
                        "type": "string",
                        "nullable": true
                    },
                    "total": {
                        "type": "integer",
                        "format": "int32"
                    }
                },
                "example": {
                    "page": 1,
                    "data": [
                        {
                            "created_at": "2023-02-04T18:56:58.000000Z",
                            "updated_at": "2023-02-04T18:56:58.000000Z",
                            "uuid": "d52199be-aefb-4d1e-9fca-eba50e847f8c"
                        }
                    ],
                    "total": 1
                }
            }
        },
        "responses": {
            "Batch": {
                "description": "A batch of requests to summarize articles.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Batch"
                        }
                    }
                }
            },
            "Request": {
                "description": "A single summarization request.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Request"
                        }
                    }
                }
            },
            "PaginatedBatches": {
                "description": "Paginated list of batches.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/PaginatedBatches"
                        }
                    }
                }
            },
            "Unauthorized": {
                "description": "No valid API token was provided.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "example": {
                            "error": {
                                "code": "unauthenticated",
                                "message": "Authentication is required to access this resource.",
                                "hint": "Set the Authorization header to an API token created at https://scisummary.com/api/tokens.",
                                "status": 401
                            }
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "The API token is not authorized for this action (for example, no active API subscription).",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "example": {
                            "forbidden": true,
                            "error": {
                                "code": "forbidden",
                                "message": "Your API token is not authorized to perform this action.",
                                "hint": "Confirm your API subscription is active at https://scisummary.com/api/pricing.",
                                "status": 403
                            }
                        }
                    }
                }
            },
            "NotFound": {
                "description": "The requested resource does not exist or is not owned by your account.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "example": {
                            "error": {
                                "code": "not_found",
                                "message": "The requested resource was not found.",
                                "hint": "Check the UUID, or list your batches at GET /api/batch.",
                                "status": 404
                            }
                        }
                    }
                }
            },
            "ValidationError": {
                "description": "The request body failed validation.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        },
                        "example": {
                            "error": {
                                "code": "validation_failed",
                                "message": "The given data was invalid.",
                                "hint": "Provide at least one of texts, urls, pdf_urls, or pdfs[].",
                                "status": 422
                            }
                        }
                    }
                }
            }
        },
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "description": "Pass an API key created from https://scisummary.com/api/tokens. A raw token or a `Bearer <token>` value are both accepted.",
                "name": "Authorization",
                "in": "header"
            }
        }
    },
    "security": [
        {
            "ApiKeyAuth": []
        }
    ]
}