Upload Sessions

Create a session

Create a session by specifying which destinations should receive the uploaded images. If you omit destination_ids, the API key's default destinations are used.

Request body

curl -X POST https://api.apertur.ca/api/v1/upload-sessions \
  -H "Authorization: Bearer aptr_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_ids": [
      "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "7c9e6679-7425-40de-944b-e07fc1f90ae7"
    ],
    "tags": ["user:123", "order:456"],
    "expires_in_hours": 24,
    "max_images": 10
  }'

Destinations

Destinations are pre-configured delivery targets managed in your dashboard under Project → Destinations. Apertur supports 9 destination types across four categories.

Cloud Storage

Cloud Drives

Server

HTTP

Destination management

Manage destinations via the API or the dashboard under Project → Destinations.

OAuth-based destinations (google_drive, dropbox, onedrive, box) are created through an OAuth authorization flow initiated from the dashboard.

Long polling

Long polling is a boolean option on the session, not a destination type. When enabled, your server can poll for images alongside any push destinations. This is useful when your server cannot accept inbound requests. See the Long Polling documentation for details.

{
  "destination_ids": ["d290f1ee-..."],
  "long_polling": true
}

Response

The response includes a uuid to identify the session and the list of resolved destinations.

{
  "uuid": "sess_01HX4ABCDEFGHIJKLMN",
  "destinations": [
    { "id": "d290f1ee-...", "type": "s3", "name": "Production S3" },
    { "id": "7c9e6679-...", "type": "webhook", "name": "My Webhook" }
  ],
  "long_polling": false,
  "expires_at": "2024-03-29T10:00:00Z",
  "password_protected": false
}

Delivery status

Track per-image, per-destination delivery progress for any session.

curl https://api.apertur.ca/api/v1/upload-sessions/sess_01HX4ABCDEFGHIJKLMN/delivery-status \
  -H "Authorization: Bearer aptr_xxxx"

{
  "session_id": "sess_01HX4ABCDEFGHIJKLMN",
  "images": [
    {
      "image_id": "img_01HX...",
      "image_index": 0,
      "deliveries": [
        {
          "destination_id": "d290f1ee-...",
          "destination_name": "Production S3",
          "destination_type": "s3",
          "status": "delivered",
          "delivered_at": "2024-03-28T10:01:23Z"
        },
        {
          "destination_id": "7c9e6679-...",
          "destination_name": "My Webhook",
          "destination_type": "webhook",
          "status": "pending",
          "attempts": 1,
          "next_retry_at": "2024-03-28T10:02:00Z"
        }
      ]
    }
  ]
}

Session options

These optional fields let you customize session behavior.

Session status