Skip to main content

File upload

This guide describes the multi-step process of uploading files to the Postmypost API. Overall, it consists of three steps:

  1. Initialize the upload — send file metadata and receive parameters. See API: Initialize file upload.
  2. Upload the file
    • Scenario A: direct upload to storage (S3) using pre-signed parameters.
    • Scenario B: upload by URL, when you ask the system to fetch the file itself.
  3. Wait for processing and check readiness — poll the status until it's ready. See API: File upload status.

Prerequisites​

  • Base API URL: https://api.postmypost.io/v4.1
  • Authentication: include the header Authorization: Bearer <ACCESS_TOKEN> in all requests to the Postmypost API.
  • Know the project_id (the ID of the project the file is uploaded to) in advance.

Step 1. Initialize the upload​

POST /upload/init → method documentation

Choose one of the request body options:

  • "by file": provide project_id, file name name, and file size in bytes size.
  • "by URL": provide project_id and the source file url.

Example ("by file", cURL):

curl -X POST "https://api.postmypost.io/v4.1/upload/init" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 12345,
    "name": "cat.jpg",
    "size": 259390
  }'

A successful response for the "by file" option returns parameters for direct S3 upload:

{
  "id": 32,
  "name": "cat.jpg",
  "size": 259390,
  "action": "https://uploads.s3.amazonaws.com/",
  "fields": [
    { "key": "acl", "value": "public-read" },
    { "key": "key", "value": "1/79811084-92e0-4cf1-805c-18cc4ec20339" },
    { "key": "X-Amz-Credential", "value": "YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" },
    { "key": "X-Amz-Algorithm", "value": "AWS4-HMAC-SHA256" },
    { "key": "X-Amz-Date", "value": "20250630T064654Z" },
    { "key": "Policy", "value": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." },
    { "key": "X-Amz-Signature", "value": "a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" }
  ],
  "status": 5
}

Save id, action, and all fields[].key → fields[].value pairs — you'll need them later.

Step 2. Upload the file: choose a scenario​

Scenario A — direct upload to storage (S3)​

  1. Send the file to the action URL with the fields parameters using multipart/form-data.

Example (cURL):

# Substitute the action and fields values from step 1
curl -X POST "https://uploads.s3.amazonaws.com/" \
  -F "acl=public-read" \
  -F "key=1/79811084-92e0-4cf1-805c-18cc4ec20339" \
  -F "X-Amz-Credential=YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Date=20250630T064654Z" \
  -F "Policy=eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." \
  -F "X-Amz-Signature=a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" \
  -F "file=@./cat.jpg"

Expected storage response — 204/201/302. After a successful upload, proceed to step 2.

  1. Complete the upload in the API: POST /upload/complete?id=<id> → method documentation
curl -X POST "https://api.postmypost.io/v4.1/upload/complete?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Example response:

{ "id": 32, "status": 1 }

Scenario B — upload by URL​

If you used the "by URL" option during initialization (Step 1), you don't need to upload anything manually — the system will download the file itself. The /upload/complete method is not called in this scenario.

For monitoring, go directly to Step 3 and poll the status by id.

Step 3. Wait for processing and check readiness​

GET /upload/status?id=<id> → method documentation

curl -X GET "https://api.postmypost.io/v4.1/upload/status?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Example response:

{ "id": 32, "status": 1 }

Possible statuses:

  • 5 — waiting for upload
  • 4 — uploading
  • 3 — processing
  • 2 — error
  • 1 — file successfully uploaded

Common errors and tips​

  • 401/403: verify the Authorization: Bearer <ACCESS_TOKEN> header and that you have permissions for the project.
  • 422: verify the request body — required fields:
    • for direct upload: project_id, name, size
    • for upload by URL: project_id, url
  • At the S3 step, you must pass all fields from fields exactly as they were returned by init.
  • In multipart/form-data, use -F "file=@/path/to/file" to send the actual file contents.
  • Provide size in bytes.
  • If the connection was interrupted, you can retry the S3 upload step and then call /upload/complete again (for Scenario A).