Imports and private documents

An assignment brief, or a paper they were given and downloaded. Returns a presigned URL: PUT the file to it directly (see `curl` in the result), then call extract_brief (kind "brief") or ingest_pdf (kind "paper") with the returned document_id. The URL is single-purpose and expires in minutes. Uploaded files are private to the member's account and never shown to anyone else.

Public papers are never affected.

Use it to re-check a document still "processing" or "queued", or to read its text.

Call after the upload. Waits up to wait_seconds for the conversion; if it is not finished the status is "processing" (or "queued" while it waits for a processing worker): check again with GET /documents/{id}.

On success returns `markdown` (the brief as text) and `structured`: title, module, deadline (YYYY-MM-DD), word_count {min,max}, citation_style, questions, rubric [{criterion, weight, descriptors}], required_sections, constraints. Fields not stated in the brief are null or empty, never guessed: check `structured` against `markdown` before relying on it.

Call after the upload (kind "paper"). The PDF is converted and indexed PRIVATELY: searchable by the member only, never displayed to anyone else, and not added to the shared library. If it is a paper the library already holds (same arXiv id, DOI or title), the public record is attached to the project instead (`matched_paper_id` / `matched_paper`) and no private copy is stored. Waits up to wait_seconds; if unfinished the status is "processing" or "queued".

Each import is "queued" (waiting for the PDF fetch), "queued_waiting_for_workers" (waiting, and the background workers look offline: it will resume when they're back), "fetching" (being converted), "converted" (full text ready, search index pending), "chunked" (fully searchable) or "failed" (with error). No timing is promised. Also returns the import allowance. Imports into one project: GET /projects/{project_id}/imports.

Up to 25 identifiers, or a .bib/.ris export's text (file_text). Papers already in the library are free; only new ones count against the import allowance. New papers' PDFs are then converted in the background: check GET /papers/imports. To add them to a project too, use POST /projects/{project_id}/imports.

Returns {"imports": [{identifier, status: added|already_in_library|failed, paper_id, title, counted, error}], "allowance", "skipped" (file entries with no id)}.

Searches Semantic Scholar by title (and optionally author) and ingests the best-matching paper into PaperVantage's library through the same pipeline as a direct arXiv import (summary generation, embedding, reference extraction). Only papers with an arXiv id can be ingested. Prefer POST /papers/imports (by arXiv id or DOI; find them with GET /papers/search?mode=title), which is metered and can add to a project.

Each import is "queued" (waiting for the PDF fetch), "queued_waiting_for_workers" (waiting, and the background workers look offline: it will resume when they're back), "fetching" (being converted), "converted" (full text ready, search index pending), "chunked" (fully searchable) or "failed" (with error). No timing is promised. Also returns the import allowance.

Up to 25 identifiers, or a .bib/.ris export's text (file_text). Papers already in the library are free and attach at once; only new ones count against the import allowance. New papers' PDFs are then converted in the background: check GET /projects/{project_id}/imports. In the in-paper assistant this always waits for the member's Confirm click (HTTP 202 with the pending action).

Returns {"imports": [{identifier, status: added|already_in_library|failed, paper_id, title, counted, error}], "allowance", "skipped" (file entries with no id)}.