# Files

Upload inputs and download exports.

## Endpoints

| Method | Path | Scope | Credits | Description |
|---|---|---|---|---|
| POST | `/v1/files` | `files:write` | 0 | Upload |
| GET | `/v1/files/{id}` | `files:read` | 0 | Retrieve metadata + download URL |

## Upload

Files are uploaded as `multipart/form-data`, never as JSON. Two constraints, both enforced at
upload: **100 MB maximum**, and `purpose=document` accepts **`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"
```

```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")

print(file.id, file.byte_size)
```

```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",
});

console.log(file.id, file.byte_size);
```

```json
{
  "object": "file",
  "id": "file_qwqxq7ix10",
  "purpose": "document",
  "filename": "Attention is all you need.pdf",
  "mime_type": "application/pdf",
  "byte_size": 2214883,
  "created_at": "2026-08-11T09:19:58Z"
}
```

Uploading is free and does nothing on its own — a file is inert until you reference it, usually from
documents. Unreferenced files are deleted after 24 hours.

| `error.code` | Cause |
|---|---|
| `file_too_large` | over 100 MB |
| `file_unsupported_type` | `purpose=document` with a non-PDF |
| `file_empty` | zero bytes |

## Constraints

| Constraint | Value |
|---|---|
| Max size | 100 MB |
| Accepted types (ingest) | `application/pdf` |
| Download URL expiry | 1 hour |

## Errors

| Status | `code` | When |
|---|---|---|
| 400 | `file_too_large` | over 100 MB |
| 400 | `unsupported_file_type` | non-PDF for document ingest |

## Related

file · documents · extractions