# ovok.documents

Canonical page: https://docs.ovok.com/web-sdk/core/namespaces/documents

Uploaded documents. Uploading is two steps: register the document with the API, then send the file to the pre-signed target it returns.

## Upload a file [#upload-a-file]

```ts
const doc = await ovok.documents.createUpload({
  fileName: 'report.pdf',
  contentType: 'application/pdf',
  isPublic: false,
});

if (doc.uploadOptions) {
  const form = new FormData();
  for (const [name, value] of Object.entries(doc.uploadOptions.fields)) form.append(name, value);
  form.append('file', file);
  await fetch(doc.uploadOptions.url, { method: 'POST', body: form });
}
```

- `createUpload` only registers the document. The file goes straight to the storage URL; the SDK does not send it.
- Put the `file` field last in the form, as pre-signed POST targets expect.
- `replaceUpload(documentId, body)` registers a new file for an existing document. It takes the same `fileName`, `contentType` and `isPublic`.

## List and change documents [#list-and-change-documents]

```ts
const documents = await ovok.documents.list();
await ovok.documents.updateMetadata(documentId, metadata);
await ovok.documents.delete(documentId);
```

- `list` takes an optional search query and returns the server's envelope.
- Calls routes under `document`.

## Build download URLs [#build-download-urls]

```ts
const url = ovok.documents.downloadUrl(documentId, { width: 400 });
const publicUrl = ovok.documents.publicDownloadUrl(publicToken);
```

- Both methods build a URL and make no request.
- `downloadUrl` needs the bearer token: fetch it with the session's token, and it redirects to a signed URL. It cannot be used as an `<img src>`.
- `publicDownloadUrl` needs no bearer, so it fits an image or media element. The token comes from a document registered with `isPublic: true`.
- `width`, `height` and `fit` resize image downloads.

## Reference [#reference]

- [documents API reference](/web-sdk/core/reference/core/documents): every method and type.
- [Errors and retries](/web-sdk/core/errors-and-retries)