# 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 |

> [!info] 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.

```bash
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.**

```bash
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"}'
```

```python
from scispace import Scispace

client = Scispace()

with open("Attention is all you need.pdf", "rb") as f:
    file = client.files.create(file=f, purpose="document")

document = client.documents.create(
    file_id=file.id,
    library_id="lib_5t7ye1kq0p",
).wait(timeout=300)
```

```typescript
import { createReadStream } from "node:fs";
import Scispace from "scispace";

const client = new Scispace();

const file = await client.files.create({
  file: createReadStream("Attention is all you need.pdf"),
  purpose: "document",
});

const document = await client.documents
  .create({ file_id: file.id, library_id: "lib_5t7ye1kq0p" })
  .wait({ timeoutMs: 300_000 });
```

**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.

```bash
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"}'
```

> [!warning] 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.

## Related

document · files · chats · extractions · data-privacy