Documents

Ingest your own PDFs so you can chat with them and extract from them.

Endpoints

Method	Path	Scope	Credits	Description
POST	`/v1/documents`	`documents:write`	1 per 10 pages, min 1	Create from `file_id` or `url`
GET	`/v1/documents/{id}`	`documents:read`	0	Retrieve, incl. parse status
GET	`/v1/documents`	`documents:read`	0	List
DELETE	`/v1/documents/{id}`	`documents:write`	0	Delete document and derived data
GET	`/v1/documents/{id}/content`	`documents:read`	0	Sectioned text, tables, figures

This endpoint is asynchronous

Parsing is a job. A document is not queryable until status: succeeded.

Upload flow

Ingest is two calls: upload the bytes, then create the document from the resulting file.

Step 1 — upload the file. multipart/form-data, 100 MB maximum, application/pdf only.

cURL

curl https://api.scispace.com/v1/files \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -F "purpose=document" \
  -F "file=@Attention is all you need.pdf;type=application/pdf"

json

{ "object": "file", "id": "file_qwqxq7ix10", "byte_size": 2214883, "created_at": "2026-08-11T09:19:58Z" }

Step 2 — create the document.

curl https://api.scispace.com/v1/documents \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"file_id":"file_qwqxq7ix10","library_id":"lib_5t7ye1kq0p"}'

Or skip step 1 by passing a URL we can fetch. The URL must be publicly reachable and serve application/pdf; it is fetched once, at create time.

cURL

curl https://api.scispace.com/v1/documents \
  -H "Authorization: Bearer $SCISPACE_API_KEY" \
  -H "SciSpace-Version: 2026-08-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"url":"https://arxiv.org/pdf/1706.03762","library_id":"lib_5t7ye1kq0p"}'

Ingest consumes credits

1 credit per 10 pages, minimum 1. A 15-page paper costs 2. See pricing-and-credits.

The document object

json

{
  "object": "document",
  "id": "doc_8ba2f01c47",
  "status": "succeeded",
  "filename": "Attention is all you need.pdf",
  "page_count": 15,
  "library_id": "lib_5t7ye1kq0p",
  "error": null,
  "created_at": "2026-08-11T09:20:04Z"
}

Field	Type	Description
`id`	string	`doc_`-prefixed identifier
`status`	enum	`queued`, `running`, `succeeded`, `failed`. Only `succeeded` is queryable
`filename`	string	As uploaded; not unique and not an identifier
`page_count`	integer	Parsed pages. `null` until `succeeded`; the basis for citation `page` values
`library_id`	string	Owning Library. `null` if unfiled
`error`	object	`type`, `code`, `message`. Populated only when `status` is `failed`
`created_at`	string	RFC 3339

Failures are terminal — re-upload rather than retry. The common causes:

`error.code`	Cause	Fix
`file_encrypted`	password-protected PDF	remove protection and re-upload
`file_not_parseable`	scanned images, no text layer	OCR it first
`file_unsupported_type`	not `application/pdf`	convert to PDF
`file_too_large`	over 100 MB	split the document

Errors

Status	`code`	When
400	`unsupported_file_type`	not a PDF
400	`file_too_large`	over 100 MB
422	`document_unparseable`	encrypted, scanned without OCR, or corrupt

Deletion and retention

Documents are retained until you delete them. There is no automatic expiry.
DELETE is effective within 24 hours and cascades to parsed text, embeddings, and extraction rows derived from that document.
Backups are purged within 30 days.
The source File is deleted automatically 24 hours after successful document creation.
Test-key documents are removed after 7 days.

Full policy, including Enterprise zero-data-retention: data-privacy.

document · files · chats · extractions · data-privacy

Last updated 2026-08-10