Skip to content

Media

Upload a file or import one from a link, then put it in a draft's media.

4 endpoints

POST/groups/{groupId}/media

Start an upload: reserve it and get a URL to PUT the file to

Any keyIdempotency-Key

Single-part uploads up to 50 MiB. PUT the bytes to upload_url with exactly headers, then call verify.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • filenamestringrequired

    1 to 255 characters, matches ^[^\u0000-\u001f\u007f]+$

  • content_typestringrequired

    The MIME type the file will be uploaded with, e.g. image/png.

    1 to 200 characters

  • bytesintegerrequired

    The exact file size. Single-part uploads only (up to 50 MiB).

    1 to 9007199254740991

Returns

201 with a MediaUpload object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/media \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filename": "chart.png",
    "content_type": "image/png",
    "bytes": 284211
  }'
POST/groups/{groupId}/media/import

Import a file from a public https link

Any keyIdempotency-Key

The server downloads the link (https only, public addresses only, up to 3 redirects, 45 s, 50 MiB) and stores it like an upload. Pass the answer in a draft's media array.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

Headers

  • Idempotency-Keystring

    Up to 128 visible ASCII characters. Retrying with the same key and body within 24 hours replays the first answer (with Idempotent-Replayed: true) instead of doing the work twice; the same key with a different body is 422 idempotency_conflict.

    up to 128 characters

Body

  • urlstringrequired

    A public https link to an image, video or PDF (up to 50 MiB).

    1 to 2048 characters

  • namestring

    The file name to keep. Defaults to the link's last path segment.

    1 to 255 characters, matches ^[^\u0000-\u001f\u007f]+$

  • alt_textstring

    Alt text, carried into the draft's media item.

    up to 1000 characters

Returns

201 with a MediaRef object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/media/import \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/chart.png",
    "alt_text": "Signups by month"
  }'
GET/groups/{groupId}/media/{mediaId}

Where an upload is: reserved, uploaded, ready or deleting

Any key

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • mediaIdstringrequired

    The media_id from POST /media.

Returns

200 with a MediaStatus object; an error answers in the Error envelope.

curl https://postacio.com/api/v1/groups/$GROUP_ID/media/$MEDIA_ID \
  -H "Authorization: Bearer $POSTACIO_API_KEY"
POST/groups/{groupId}/media/{mediaId}/verify

Check an uploaded file and get the attachment for a draft

Any key

Pass the answer in a draft's media array, adding alt_text there. A file that fails the check is deleted.

Path

  • groupIduuidrequired

    A social group id from GET /groups.

  • mediaIdstringrequired

    The media_id from POST /media.

Body

  • namestringrequired

    The file name to show for this attachment.

    1 to 255 characters, matches ^[^\u0000-\u001f\u007f]+$

  • content_typestringrequired

    1 to 200 characters

Returns

200 with a MediaRef object; an error answers in the Error envelope.

curl -X POST https://postacio.com/api/v1/groups/$GROUP_ID/media/$MEDIA_ID/verify \
  -H "Authorization: Bearer $POSTACIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "chart.png",
    "content_type": "image/png"
  }'

Ready to send your first draft?

Start your free trial, create a key in Settings, and call the API in a minute.

Start free trialRead the guide