> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dokstamp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload and manage PDF files. Every certificate must reference an uploaded file.

# Files

Files are PDF documents uploaded to DokStamp before being attached to certificates or documents. Each file can only be used by **one** certificate — once attached, it is marked as used and cannot be reused.

***

## The file object

```json theme={null}
{
  "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
  "original_name": "diploma-maria-silva.pdf",
  "mime_type": "application/pdf",
  "extension": "pdf",
  "size": 245760,
  "used_at": null,
  "file": "https://storage.dokstamp.eu/files/h8i9j0k1.pdf"
}
```

| Field           | Type           | Description                                                       |
| --------------- | -------------- | ----------------------------------------------------------------- |
| `uuid`          | string         | Unique identifier — use as `file_uuid` when creating certificates |
| `original_name` | string         | Original filename                                                 |
| `mime_type`     | string         | MIME type (e.g., `application/pdf`)                               |
| `extension`     | string         | File extension                                                    |
| `size`          | integer        | File size in bytes                                                |
| `used_at`       | datetime\|null | Null = available. Non-null = already attached to a certificate.   |
| `file`          | string         | Direct download URL                                               |

***

## Upload files

```http theme={null}
POST /files
```

Accepts `multipart/form-data`. You can upload multiple files in a single request.

| Parameter | Type | Required | Description           |
| --------- | ---- | -------- | --------------------- |
| `files[]` | file | Yes      | One or more PDF files |

<CodeGroup>
  ```bash cURL theme={null}
  # Upload a single file
  curl -X POST https://api.dokstamp.com/files \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}" \
    -F "files[]=@/path/to/diploma-maria-silva.pdf"

  # Upload multiple files at once
  curl -X POST https://api.dokstamp.com/files \
    -H "Authorization: Bearer {TOKEN}" \
    -H "Accept: application/json" \
    -H "X-Tenant: {TENANT}" \
    -F "files[]=@diploma-1.pdf" \
    -F "files[]=@diploma-2.pdf" \
    -F "files[]=@diploma-3.pdf"
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append('files[]', pdfBlob, 'diploma-maria-silva.pdf');

  const res = await fetch('https://api.dokstamp.com/files', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Accept': 'application/json',
      'X-Tenant': TENANT,
      // Do NOT set Content-Type — let the browser set multipart boundary
    },
    body: formData,
  });

  const { data } = await res.json();
  const fileUuid = data[0].uuid; // Use this as file_uuid in POST /certificates
  ```

  ```php PHP theme={null}
  $response = Http::withToken($token)
      ->withHeaders(['X-Tenant' => $tenant, 'Accept' => 'application/json'])
      ->attach('files[]', file_get_contents($filePath), basename($filePath))
      ->post('https://api.dokstamp.com/files');

  $fileUuid = $response->json('data.0.uuid');
  ```
</CodeGroup>

**Response `201`:**

```json theme={null}
{
  "data": [
    {
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "original_name": "diploma-maria-silva.pdf",
      "mime_type": "application/pdf",
      "size": 245760,
      "used_at": null
    }
  ]
}
```

***

## List files

```http theme={null}
GET /files
```

Filter for unused files (available to attach to new certificates):

```bash theme={null}
GET /files?where[used_at]=null
```

***

## Get file metadata

```http theme={null}
GET /files/{uuid}
```

***

## Download a file

```http theme={null}
GET /files/{uuid}/download
```

<Note>This endpoint is **public** — no `Authorization` header required. Share this URL directly with signers, students, or employers.</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.dokstamp.com/files/h8i9j0k1-l2m3-4567-nopq-678901234567/download" \
    --output diploma.pdf
  ```
</CodeGroup>

***

## Update file metadata

```http theme={null}
PATCH /files/{uuid}
PUT   /files/{uuid}
```

***

## Delete a file

```http theme={null}
DELETE /files/{uuid}
```

<Warning>
  You cannot delete a file that is already attached to a certificate (`used_at` is not null). Delete or revoke the certificate first.
</Warning>

***

## Deduplication

The API computes a `hash` for each uploaded file. If you upload the same file content twice, the second upload returns the existing file record instead of creating a duplicate. This prevents storage bloat in batch upload workflows.