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

# Imports API guidance

> Workflow guidance for the generated import and archive-upload endpoints.

The generated API Reference includes every supported Import endpoint. An import first creates a tracked row, then uploads an archive, then restores it asynchronously into a new or existing sandbox.

## Choose credentials and destination

Personal bearer tokens can use the complete workflow. Scoped OAuth tokens can use this family too: reads require `import:read`; creates, uploads, completion, cancellation, and multipart actions require `import:write`.

`POST /api/app/imports` requires `sourceUrl`, used for WordPress search-and-replace during restore. Omit `siteId` to create a new sandbox, or send a ready existing `siteId` to push into it in place.

## Upload an archive

The simple protocol appends raw archive chunks to `PUT /api/app/imports/:id/upload` at a contiguous `x-sandywp-offset`. Finish with `POST /api/app/imports/:id/complete`, which seals the archive and starts restore.

```sh theme={null}
curl -X PUT "https://app.sandywp.com/api/app/imports/imp_123/upload" \
  -H "Authorization: Bearer $SANDYWP_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  -H "x-sandywp-offset: 0" \
  --data-binary @archive.tar.gz
```

For large or streamed uploads, use the multipart sequence: initialize, obtain URLs for each part, upload directly, complete each object, then call `/multipart/finalize` for the manifest-based streamed format. An initialization response with `mode: "local"` means direct storage is unavailable, so fall back to the chunked protocol.

## Poll and clean up

`GET /api/app/imports/:id` returns the import state, linked sandbox, live restore progress, and—once ready—a site URL plus a one-click login URL. Poll it until the import is `ready`, `failed`, or `site_deleted`.

Delete without a query parameter to cancel an unfinished import while retaining its history. Use `?action=delete` only to remove the history row; it does not delete an already-created sandbox.

Use [Clone a site](/guides/clone-a-site) for a live source you control, or [Push a local site](/guides/push-local-site) for a local WordPress installation.