> For the complete documentation index, see [llms.txt](https://apidocs.zerionsoftware.com/doc/iformbuilder-v81/llms.txt)

# Restore Deleted Media

> POST /profiles/{profile_id}/pages/{page_id}/media_restore
> 
> Restores media files that were deleted from a versioned S3 bucket (for example via `DELETE .../media_upload`) by removing the S3 delete marker, making the object readable again.
> 
> ### Request body
> 
> Send either a JSON array of `{ "url": ... }` objects or a single `{ "url": ... }` object. Both public `https://...amazonaws.com/...` URLs and `privates3://{bucket}/{key}` URLs (as returned for private media) are accepted. A request may contain **at most 200 items**; 201 or more returns `413` and nothing is restored.
> 
> ### Response
> 
> A plain JSON array with one entry per submitted item, in request order. Each entry has `url` and `status`; `reason` is added on `PERMANENTLY_DELETED` and `RESTORE_FAILED`, and `version_id` is added only on `RESTORED`.
> 
> | `status` | `reason` | Meaning |
> |---|---|---|
> | `RESTORED` | - | Delete marker removed; the object is readable again. `version_id` is the id of the removed delete marker. |
> | `ALREADY_ACTIVE` | - | The latest version has no delete marker. A no-op success, so replaying a request is idempotent. |
> | `PERMANENTLY_DELETED` | `LIFECYCLE_EXPIRED`, `OBJECT_NEVER_EXISTED` | Nothing to restore: the versions have been expired by the bucket lifecycle, or no object with that key ever existed. |
> | `RESTORE_FAILED` | `URL_REQUIRED`, `URL_OUT_OF_SCOPE`, `S3_CLIENT_UNAVAILABLE`, `AWS_SDK_ERROR`, or the raw AWS error code returned by S3 (for example `AccessDenied` or `NoSuchBucket`) | The item failed. Failures are per item and do not abort the rest of the batch (barring a server-side media configuration error, which fails the whole request). Malformed URLs and URLs on non-S3 hosts are reported as `URL_OUT_OF_SCOPE`. |
> 
> ### HTTP status
> 
> - `200` no item failed (`RESTORED`, `ALREADY_ACTIVE` and `PERMANENTLY_DELETED` all count as non-failures)
> - `207` some items failed and some did not
> - `400` every item failed, or the body was empty or malformed
> - `413` more than 200 items in one request
> - `401` no valid bearer token
> - `403` BASIC user, no record-modify permission on the page, or another profile's `profile_id`
> - `404` invalid `page_id`, or the page does not belong to the profile
> 
> ### Authorization
> 
> Standard bearer token. **BASIC users are denied with `403` before any S3 call**; COMPANY and SERVER users are allowed. The caller must also be able to modify records on the page.
> 
> ### Scope
> 
> Every URL must belong to the page in the path: its key must contain `{profile_id}/{data_table_name}`, where the data table name is resolved server-side from `(profile_id, page_id)`. URLs outside that scope come back as `RESTORE_FAILED` / `URL_OUT_OF_SCOPE` rather than being looked up in S3.



## Servers
- https://api.iformbuilder.com/exzact/api/v81/[servername]: https://api.iformbuilder.com/exzact/api/v81/[servername]


## Authentication methods
- Oauth2


## Parameters
### Headers

- **Authorization** (string)
  e.g. Bearer {access_token}


### Path parameters

- **profile_id** (string)
  id of the profile

- **page_id** (number)
  id of the page



### Body: application/json (array[object])

- **url** (string)
  public `https://...amazonaws.com/...` or `privates3://{bucket}/{key}` url of the media file



## Responses
### 200
OK - no item in the batch failed (every `status` is `RESTORED`, `ALREADY_ACTIVE` or `PERMANENTLY_DELETED`).

#### Body: application/json (array[object])
- **url** (string | null)
  the url exactly as submitted (null when the item had no url)

- **status** (string)
  per-asset outcome

- **reason** (string)
  present only on `PERMANENTLY_DELETED` and `RESTORE_FAILED`

- **version_id** (string)
  present only on `RESTORED`; the S3 version id of the delete marker that was removed


### 207
Multi-Status - some items succeeded and some failed. The body has the same shape as `200`; inspect each item's `status`.

#### Body: application/json (array[object])
- **url** (string | null)
  the url exactly as submitted (null when the item had no url)

- **status** (string)
  per-asset outcome

- **reason** (string)
  present only on `PERMANENTLY_DELETED` and `RESTORE_FAILED`

- **version_id** (string)
  present only on `RESTORED`; the S3 version id of the delete marker that was removed


### 400
Bad Request - either the body was empty or not valid JSON (standard error object body), or every item in the batch failed (same outcome array as `200`, one entry per item).

### 401
Unauthorized - missing or invalid bearer token.

### 403
Forbidden - the token belongs to a BASIC user, the user cannot modify records on this page, or `profile_id` is not the caller's own profile.

### 404
Not Found - `page_id` is not a valid page id, or the page does not belong to `profile_id`.

### 413
Payload Too Large - more than 200 items were submitted. Split the batch and retry.


[Powered by Bump.sh](https://bump.sh)
