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
200no item failed (RESTORED,ALREADY_ACTIVEandPERMANENTLY_DELETEDall count as non-failures)207some items failed and some did not400every item failed, or the body was empty or malformed413more than 200 items in one request401no valid bearer token403BASIC user, no record-modify permission on the page, or another profile'sprofile_id404invalidpage_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.
Responses
-
OK - no item in the batch failed (every
statusisRESTORED,ALREADY_ACTIVEorPERMANENTLY_DELETED). -
Multi-Status - some items succeeded and some failed. The body has the same shape as
200; inspect each item'sstatus. -
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). -
Unauthorized - missing or invalid bearer token.
-
Forbidden - the token belongs to a BASIC user, the user cannot modify records on this page, or
profile_idis not the caller's own profile. -
Not Found -
page_idis not a valid page id, or the page does not belong toprofile_id. -
Payload Too Large - more than 200 items were submitted. Split the batch and retry.
curl \
--request POST 'https://api.iformbuilder.com/exzact/api/v80/[servername]/profiles/self/pages/{page_id}/media_restore' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer {access_token}" \
--data '[
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png"
},
{
"url": "privates3://zerion-iform-private-media-example/app/67890/_data67890_inspection_form/field_5678.png"
}
]'
[
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png"
},
{
"url": "privates3://zerion-iform-private-media-example/app/67890/_data67890_inspection_form/field_5678.png"
}
]
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png"
}
[
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png",
"status": "ALREADY_ACTIVE"
},
{
"url": "privates3://zerion-iform-private-media-example/app/67890/_data67890_inspection_form/field_5678.jpeg",
"status": "RESTORED",
"version_id": "tn1cpMCxjyrb_0ksm3HBGnz6ORIAMZ9O"
}
]
[
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/67890/_data67890_inspection_form/field_1234.png",
"status": "RESTORED",
"version_id": "tn1cpMCxjyrb_0ksm3HBGnz6ORIAMZ9O"
},
{
"url": "https://zerion-iform-media-example.s3.amazonaws.com/app/99999/_data99999_other_form/field_1.png",
"status": "RESTORE_FAILED",
"reason": "URL_OUT_OF_SCOPE"
}
]