# Update activity image

`PUT /api/configuration/activity/{id}/image`

- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Update activity image](https://support.gladstonesoftware.cloud/reference/configuration/update-activity-image)

## Overview

Uploads an image file and points an existing activity at it, replacing whatever image the activity
was previously using. The image is what member-facing booking screens and activity listings show
for that activity.

**Send this as `multipart/form-data`, not JSON.** The form has two required parts:

- `imageFile` — the image file itself.
- `imageName` — a name for the stored file, sent as a plain text form field.

The call happens in two steps, and they are not all-or-nothing:

1. The file is uploaded and stored, possibly under a different filename from the one you sent.
2. That returned filename — not the `imageName` you sent — is written to the activity as its image
   reference.

**If step 2 fails the uploaded file is not rolled back.** The most common cause is an activity
identifier that does not exist, which fails only at step 2, so a `404` from this endpoint still
leaves an orphaned uploaded file behind. Verify the activity exists before uploading.

This is a targeted update: only the activity's image reference is written, and no other activity
configuration is touched or cleared. There is no way to clear an activity's image with this call —
you can only replace it with another upload.

On success the response is `204 No Content` with an empty body.

## Endpoint

`PUT {base_url}/api/configuration/activity/{id}/image`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Identifier of the activity whose image reference is rewritten. It is not validated before the file is uploaded; an identifier that does not match an activity fails at the second step with `404`, after the upload has already happened. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `imageRef` | string | Yes | The stored filename written to the activity as its image reference. **You do not supply this** — it is set from the filename the file was stored under after the upload, so it may differ from the `imageName` you sent. The parts you actually send are `imageFile` (the file) and `imageName` (a text field), both required, as `multipart/form-data`; see the Overview and the sample request. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/configuration/activity/{id}/image' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -F 'imageFile=@/path/to/badminton.png' \
  -F 'imageName=badminton.png'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | No file part was supplied — body is the string `An image file is required`. |
| `400` | Bad request | `imageName` is missing. Both form parts are required, so the request is rejected before anything is uploaded and the body is a validation problem document rather than a plain string. |
| `400` | Bad request | The file upload was rejected. The rejection message is passed through verbatim, so the text varies with the reason the file was refused. |
| `400` | Bad request | The image reference update was rejected — body is `Failed to update activity image reference: {downstream response}`. The file has already been uploaded at this point. |
| `404` | Not found | No activity matches `{id}`, so the second step cannot write the reference — body is `Failed to update activity image reference: {downstream response}`. The upload is not undone. |
| `409` | Conflict | The file upload reported a conflict, and its message is passed through verbatim. |
| `500` | Internal server error | The file upload failed for a reason other than a rejection or conflict; the upload's error message is used as the message. Also returned when the upload's success response cannot be read (`Failed to deserialize upload activity image response`), when the reference update fails for a reason other than `400` or `404` (`Failed to update activity image reference`), or on any other unexpected server-side failure. |
| `503` | Service unavailable | Not returned by this endpoint itself; if you see a `503`, it is more likely to come from infrastructure in front of the API. |