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

# Attachments in the API: Reports and Documents on Inspections

> List and upload inspection attachments with the Hive Inspect API. Learn the two kinds, the file limits, and when an upload notifies your client.

<p className="hive-locator">In the dashboard: open an inspection, then <strong>Additional Reports</strong> or <strong>Additional Information & Documents</strong></p>

<Note>
  **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon. To ask for early access, message us from the chat bubble in your dashboard.
</Note>

An attachment is a file or link added to an inspection. The API covers the two kinds you can add on an inspection in the dashboard.

## The two kinds

| | `report` | `document` |
| - | - | - |
| In the dashboard | Additional Reports | Additional Documents |
| What it is | A named report, with a description and a file or a link | A plain file |
| Who sees it | Always visible to the client | Visible to the client, unless you mark it inspector-only |
| Inspection status | Confirmed inspections only | Any status |
| Maximum file size | 25 MB | 10 MB |
| File types | pdf, doc, docx, xls, xlsx, jpg, png, gif | The same, plus txt, csv and webp |

<Warning>
  **Uploading a report can notify your client.** It runs your "Additional report added" automations, the same as adding the report in the dashboard. If those automations email or text the client or their agent, each upload sends that message. Uploading a document never sends anything.
</Warning>

Private notes are not attachments. They are the `notes` field on the inspection.

## List an inspection's attachments

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/inspections/INSPECTION_ID/attachments" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Each attachment has a `kind`, a `name`, and a `url` to download the file. Use `kind=report` or `kind=document` to list one kind, and `visible_to_client=false` to list only your inspector-only documents.

<Note>
  The `url` is a signed link that works for 1 hour. Do not store it. List the attachments again when you need a fresh link. A report that is only a link has no file, so its `url` is `null`.
</Note>

## List attachments across all inspections

To collect new files without asking each inspection in turn, use the account-wide list. It returns the same attachment objects, each with its `inspection_id`, newest change first:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/attachments?updated_since=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

* `updated_since` returns only attachments added or changed since that time.
* `kind`, `visible_to_client` and `inspection_id` narrow the list.
* Attachments on deleted inspections and sample inspections are left out.

<Note>
  When you sync with `updated_since`, start a few minutes before your last sync so nothing is missed. A document's `id` is unique within its inspection, so identify a document by `inspection_id` and `id` together.
</Note>

## Upload an attachment

Uploads use `multipart/form-data`, not JSON.

<Steps titleSize="h3">
  <Step title="Upload a report">
    Send `kind=report` and a `name`. The `description` and the `file` are optional, so you can add a report that is only a link.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST "https://api.hiveinspect.com/v1/inspections/INSPECTION_ID/attachments" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "kind=report" \
      -F "name=Sewer Scope Report" \
      -F "description=Video: https://example.com/sewer-scope" \
      -F "file=@sewer-scope.pdf;type=application/pdf"
    ```
  </Step>

  <Step title="Upload a document">
    Send `kind=document` and the `file`. Add `internal_only=true` to keep it inspector-only, hidden from the client.

    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    curl -X POST "https://api.hiveinspect.com/v1/inspections/INSPECTION_ID/attachments" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "kind=document" \
      -F "internal_only=true" \
      -F "file=@cost-notes.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
    ```
  </Step>
</Steps>

The response is the new attachment, with status `201`.

## Things to know

* **Send the right content type.** The file's content type must match its extension, for example `application/pdf` for a `.pdf` file. A mismatch returns `400`.
* **File names are cleaned up.** Spaces become underscores and special characters are removed, so `Site Plan (v2).pdf` is stored as `Site_Plan_v2.pdf`.
* **A file over the limit returns `413`.**
* **A report on an inspection that is not confirmed returns `400`.** Confirm the inspection first.
* **Attachments cannot be deleted or renamed through the API yet.** Remove them in the dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.