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

# Attachments

> Upload a file by URL and attach it to schedule items, venues, accommodation, or guest list entries.

Attachments are files linked to a resource (schedule item, venue, accommodation, or guest list entry). Daysync **hosts** attachment files — an attachment's `link` is a Daysync-owned storage key, and Daysync builds the public URL from it on read.

Because the API can't receive raw file bytes, you attach a file in **two steps**:

1. **`POST /v1/attachments`** with a public URL — Daysync fetches the file, stores it, and returns a `link`.
2. Pass that `link` in the `attachment` / `attachments` field of a create or update on the target resource.

All endpoints require the standard [authentication](/authentication) headers.

***

## Upload an attachment

```text theme={null}
POST /v1/attachments
```

Fetches the file at `url` and stores it in Daysync-hosted storage. Returns the storage key to use as `attachment.link`.

**Scope:** `schedule.write`

**Body**

| Field      | Type   | Required | Description                                                                                                      |
| ---------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `url`      | string | Yes      | Public **https/http** URL of the file to fetch. Must be directly reachable — see the constraints below.          |
| `fileName` | string | No       | Display file name. If omitted, it's derived from the URL. The extension is set from the response `Content-Type`. |

**Example**

```bash theme={null}
curl -X POST "$BASE/v1/attachments" \
  -H "x-api-key: $KEY" -H "x-api-secret: $SECRET" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-cdn.com/files/stage-plot.pdf", "fileName": "Stage plot" }'
```

**Response `data`**

```json theme={null}
{
  "link": "attachments/8f3c…-stage-plot.pdf",
  "fileName": "stage-plot.pdf",
  "fileSize": 482133
}
```

| Field      | Type   | Description                                                                                                                         |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `link`     | string | Daysync storage **key** — pass this verbatim as `attachment.link`. It is **not** a full URL; Daysync builds the public URL from it. |
| `fileName` | string | The stored file name.                                                                                                               |
| `fileSize` | number | Size in **bytes**.                                                                                                                  |

<Warning>
  The URL you pass is fetched **once, server-side**, and the bytes are copied into Daysync storage. Constraints:

  * **`https`/`http` only.** Other schemes are rejected.
  * **No redirects.** The URL must return the file directly (`200`); a `3xx` is rejected — resolve redirects yourself and pass the final URL.
  * **Public hosts only.** URLs that resolve to private, loopback, link-local, or cloud-metadata addresses are rejected.
  * **25 MB** maximum, **15 s** fetch timeout.

  A URL that violates any of these returns `400`.
</Warning>

***

## Attaching the file to a resource

Use the returned `link` in the `attachment` (single) or `attachments` (array) field on a create or update:

```json theme={null}
"attachments": [
  {
    "link": "attachments/8f3c…-stage-plot.pdf",
    "name": "Stage plot",
    "fileName": "stage-plot.pdf",
    "fileSize": 482133,
    "description": "Rev 3 — updated monitor positions"
  }
]
```

Only `link` is required. Attachments are supported on:

* [Schedule items](/endpoints/schedule#attachments) — `attachment` / `attachments` on create and update (with [upsert/delete semantics](/endpoints/schedule#update-a-schedule-item) on update).
* [Venues](/endpoints/venues#create-a-venue) — `attachments`.
* [Accommodation](/endpoints/accommodation) — `attachment` / `attachments`.
* [Guest list entries](/endpoints/guest-list) — `attachment` / `attachments`.

Bulletins do **not** support attachments.

<Note>
  Always obtain `link` from `POST /v1/attachments`. Don't pass an external URL (e.g. your own CDN link) directly as `attachment.link` — Daysync treats `link` as one of its own storage keys and builds the public URL from it, so a foreign URL renders as a broken link.
</Note>

***

See also: [Schedule](/endpoints/schedule), [Venues](/endpoints/venues), [Scopes & Permissions](/scopes).