> For the complete documentation index, see [llms.txt](https://diffio.ai/llms.txt). This page is also available as HTML at https://diffio.ai/docs/api-reference/reopen-project-upload/.

# Get new upload instructions

Returns fresh multipart `upload` instructions (with a new 24-hour `upload_token`) for a project whose file has not arrived yet.

POST `https://api.diffio.ai/v2/projects/{project_id}/upload`

- Key scope: `projects:write`
- Auth header: `Authorization: Bearer <apiKey>`
- Body: None

## Request

Pass `project_id` in the path; send no body (or `{}`).

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string | Yes | Unique identifier of the project. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `Diffio-End-User` | string | No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |

## Example request

**Python**

```python
import os
from diffio import DiffioClient

key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)

project = client.projects.reopen_upload(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)
```

**Node.js**

```javascript
import { DiffioClient } from "diffio"

const client = new DiffioClient({
  apiKey: process.env.DIFFIO_API_KEY,
})

const project =
  await client.projects.reopenUpload(
    "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  )
```

**cURL**

```bash
curl -X POST "https://api.diffio.ai/v2/projects/62f62565-049f-5e7e-bbd2-9de0cf7ddbfe/upload" \
  -H "Authorization: Bearer $DIFFIO_API_KEY"
```

## Response

Returns the `project` with renewed `upload` descriptors pointing to the same destination.

Success: `200`

### Response fields

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `id` | string | Always | Unique project identifier (UUID). |
| `object` | string | Always | Resource type, always `"project"`. |
| `status` | string | Always | Upload and preparation state: `awaiting_upload` until bytes arrive, `preparing` while media is probed, `ready` when ready to restore, or `failed`. |
| `upload` | object \| null | Always | Multipart upload instructions for sending the file to the media edge, or `null` on an idempotent replay after the upload has arrived. [Fields below](#fields-upload) |

**`upload` fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `upload.upload_session_id` | string | Always | Upload session identifier (`api-{project_id}`). |
| `upload.edge_base_url` | string | Always | Origin URL of the media upload edge (`https://media.diffio.io`). |
| `upload.upload_token` | string | Always | Signed bearer token sent as `Authorization: Bearer <token>` on every upload edge request. |
| `upload.part_size_bytes` | integer | Always | Required byte length for every upload part except the last (`33554432`, 32 MiB). |
| `upload.max_bytes` | integer | Always | Maximum total upload size in bytes (`2147483648`, 2 GB). |
| `upload.expires_at` | string | Always | ISO 8601 UTC timestamp when `upload_token` expires (24 hours after minting); renew via `POST /projects/{project_id}/upload`. |
| `upload.requests` | object | Always | Pre-built HTTP request descriptors for the multipart upload (`start`, `part`, `complete`, `abort`). |
| `upload.requests.start` | object | Always | Descriptor (`method`, `url`, `headers`, `body`, `returns`, `description`) called once first to obtain `uploadId`. |
| `upload.requests.part` | object | Always | Descriptor called once per part (numbered from `1`) with raw bytes as the `PUT` body; save each returned `etag`. |
| `upload.requests.complete` | object | Always | Descriptor called once after all parts finish, sending `uploadId` and the ordered `parts` array (`partNumber`, `etag`). |
| `upload.requests.abort` | object | Always | Optional descriptor to discard uploaded parts for an unfinished `uploadId`. |

**Other response fields**

| Field | Type | Present | Description |
| --- | --- | --- | --- |
| `file_name` | string \| null | Always | Recording filename as sent at creation, or `null`. |
| `content_type` | string \| null | Always | MIME type sent at creation (`application/octet-stream` when none was sent), or `null`. |
| `size_bytes` | integer \| null | Always | File size in bytes: the uploaded byte count once the upload arrives, before that the `size_bytes` sent at creation; `null` when unknown. |
| `duration_seconds` | number \| null | Always | Recording duration in seconds once `status` is `ready`, or `null` while awaiting upload or preparing. |
| `has_video` | boolean | Always | True when the recording has video: inferred from `content_type` or the file name until the upload is probed, then from the file itself. |
| `end_user` | string \| null | Always | End-user identifier from the `Diffio-End-User` header at creation, or `null` for account-level projects. |
| `metadata` | object | Always | Key-value string map saved with the project (`{}` when none was supplied). |
| `generation_count` | integer | Always | Total number of generations created for this project. |
| `video_preview_status` | string \| null | Always | State of a video project's picture-only HLS stream (`video_hls`): `preparing`, `ready`, or `failed`; `null` for audio projects. |
| `share_id` | string \| null | Always | Public 17-character share identifier while a share is published, or `null` when unshared. |
| `latest_generation` | object \| null | Always | Newest `Generation` object on this project, or `null` when no generation exists yet. |
| `created_at` | string \| null | Always | ISO 8601 UTC timestamp when the project was created, or `null`. |
| `updated_at` | string \| null | Always | ISO 8601 UTC timestamp when the project last changed, or `null`. |
| `error` | object \| null | Always | Failure details when `status` is `failed`, or `null` otherwise. |
| `error.code` | string | Always | Stable `snake_case` project failure code (`media_processing_failed` or `project_failed`). |
| `error.message` | string | Always | Human-readable explanation of why the upload could not be prepared. |

## Example response (200)

**Response, key fields: Response: key fields**

```json
{
  "id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "object": "project",
  "status": "awaiting_upload",
  "upload": {
    "upload_token": "v1.REDACTED",
    "part_size_bytes": 33554432,
    "expires_at": "2026-11-14T00:33:21.812909Z",
    "requests": {
      "start": {
        "method": "POST",
        "url": "https://media.diffio.io/v1/uploads/start",
        "headers": {
          "Authorization": "Bearer v1.REDACTED"
        },
        "body": null,
        "returns": [
          "uploadId",
          "partSizeBytes",
          "maxBytes"
        ],
        "description": "Once, first. Keep uploadId for the other requests."
      }
    }
  }
}
```

**Full response: Successful response**

```json
{
  "id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
  "object": "project",
  "status": "awaiting_upload",
  "file_name": "interview.mp3",
  "content_type": "audio/mpeg",
  "size_bytes": 510957,
  "duration_seconds": null,
  "has_video": false,
  "end_user": "customer-mwe8tm1g",
  "metadata": {
    "order_id": "1042"
  },
  "generation_count": 0,
  "video_preview_status": null,
  "latest_generation": null,
  "share_id": null,
  "created_at": "2026-11-13T00:33:21.812909Z",
  "updated_at": "2026-11-13T00:33:21.812909Z",
  "error": null,
  "upload": {
    "upload_session_id": "api-62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
    "edge_base_url": "https://media.diffio.io",
    "upload_token": "v1.REDACTED",
    "part_size_bytes": 33554432,
    "max_bytes": 2147483648,
    "expires_at": "2026-11-14T00:33:21.812909Z",
    "requests": {
      "start": {
        "method": "POST",
        "url": "https://media.diffio.io/v1/uploads/start",
        "headers": {
          "Authorization": "Bearer v1.REDACTED"
        },
        "body": null,
        "returns": [
          "uploadId",
          "partSizeBytes",
          "maxBytes"
        ],
        "description": "Once, first. Keep uploadId for the other requests."
      },
      "part": {
        "method": "PUT",
        "url": "https://media.diffio.io/v1/uploads/parts/{part_number}?uploadId={upload_id}",
        "headers": {
          "Authorization": "Bearer v1.REDACTED",
          "Content-Length": "{part_length}"
        },
        "body": null,
        "returns": [
          "partNumber",
          "etag"
        ],
        "description": "Once per part, numbered from 1; the body is the part's raw bytes. Every part but the last is exactly part_size_bytes. Keep each etag."
      },
      "complete": {
        "method": "POST",
        "url": "https://media.diffio.io/v1/uploads/complete",
        "headers": {
          "Authorization": "Bearer v1.REDACTED",
          "Content-Type": "application/json"
        },
        "body": {
          "uploadId": "{upload_id}",
          "parts": [
            {
              "partNumber": "{part_number}",
              "etag": "{etag}"
            }
          ]
        },
        "returns": [
          "sizeBytes",
          "etag"
        ],
        "description": "Once, after every part, listing every part. Repeating it is safe."
      },
      "abort": {
        "method": "POST",
        "url": "https://media.diffio.io/v1/uploads/abort",
        "headers": {
          "Authorization": "Bearer v1.REDACTED",
          "Content-Type": "application/json"
        },
        "body": {
          "uploadId": "{upload_id}"
        },
        "returns": [],
        "description": "Optional: drop an unfinished upload's parts."
      }
    }
  }
}
```

## Return codes

- `200` Returns the project with renewed 24-hour `upload` instructions.
- `400` Malformed JSON body, or `Diffio-End-User` exceeds 128 characters. [`invalid_json`](https://diffio.ai/docs/api-reference/errors/#invalid_json) [`invalid_header`](https://diffio.ai/docs/api-reference/errors/#invalid_header)
- `403` Key is inactive or lacks `projects:write`. [`permission_denied`](https://diffio.ai/docs/api-reference/errors/#permission_denied)
- `404` No project with that `project_id` exists for this account and end user. [`project_not_found`](https://diffio.ai/docs/api-reference/errors/#project_not_found)
- `409` The project's file has already arrived, with `details.project_status` reporting its current status. [`upload_already_received`](https://diffio.ai/docs/api-reference/errors/#upload_already_received)
- **`401` `405` Same on every endpoint**

  - `401` Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).
  - `405` HTTP method not supported on this path; check the Allow header (code method_not_allowed).

### Example error response

Errors are JSON: an `error` object with `code`, `message` and `request_id`. An unrecognized key returns `401`:

**Error response**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key.",
    "request_id": "dead773b60e148fd9e22d680a22fa701"
  }
}
```

## Notes

- Only projects in `status: "awaiting_upload"` accept new upload instructions; once the upload arrives, create a new project to upload a different file.
- Both SDKs call this from `projects.upload(...)` when you pass a project id instead of the created project; the Python SDK also calls it when `upload.expires_at` is less than 60 seconds away.

## Related pages

- Previous: [Delete a project](https://diffio.ai/docs/api-reference/delete-project/): Delete a project and all of its stored uploads, generations, exports, and shares.
- Next: [Complete a project's upload](https://diffio.ai/docs/api-reference/complete-project-upload/): Verify and prepare a finished multipart upload immediately instead of waiting for edge callback.

- [Full API guide](https://diffio.ai/docs/developers/full-api-guide/): Every topic, limit and concept in one index.
- [Diffio API overview](https://diffio.ai/api-overview/): The cloud batch workflow and SDKs on one page.
