PUpublora
Media

Attach a file to a post by reference

Changed on

Attach one image or video to an existing draft or scheduled post using a file reference: an HTTPS download URL plus a stable file ID, the shape ChatGPT supplies through openai/fileParams to the MCP attach_media tool. Publora downloads the file right away through the same guarded pipeline as mediaUrls, which detects the type from the bytes and probes the file. Accepted: JPEG, PNG, GIF, WebP, TIFF and AVIF images up to 25 MB; MP4, MOV and WebM videos up to 150 MB. The file is attached with status ready, and no presigned PUT or complete-media call is needed. The post is always left in draft. A scheduled post is demoted to draft and keeps its stored time; schedule it again with update-post. The body accepts only file and fileName, and publishing parameters are rejected with INVALID_MEDIA_FILE. The response has the update-post shape and does not include the media ID, so read media[] from get-post. Each attempt that reaches the download counts one URL against the media URL ingestion limit of 60 URLs per hour, shared with mediaUrls; idempotent replays don't count.

post/attach-media/{postGroupId}

Request

  • Base URL
    https://api.publora.com/api/v1
  • Auth
    API key in header x-publora-key

Path parameters

postGroupIdstring required

Headers

x-publora-user-idstring
Idempotency-Keystring

Recommended. Publora recognises a retry by the post ID, file.file_id and the sanitized file name. download_url and mime_type are excluded, so a retry with a refreshed temporary URL replays the original response instead of attaching the file twice. Reusing the key with a different post, file ID or file name returns 422. A failed download frees the key for a retry with a fresh reference. Without a key, every call attaches another copy. Keys are kept for 24 hours.

Request body

fileNamestring

Descriptive file name with an extension. Takes precedence over file.file_name; if both are absent the name is chatgpt-media. Only the last path segment is kept; it is trimmed, each run of whitespace becomes _, and any character other than an ASCII letter, digit, _, . or - is removed. A name that ends up empty or only dots is rejected, including one taken from file.file_name. get-post returns the result as media[].sourceFileName.

Example request

{
  "file": {
    "download_url": "https://files.example.com/download/abc123?signature=TEMPORARY",
    "file_id": "file-abc123",
    "mime_type": "image/png",
    "file_name": "image.png"
  },
  "fileName": "spring-launch-banner.png"
}

Response

File downloaded, validated and attached; the post is in draft

successboolean
messagestring
scheduledTimestring date-time nullable

The stored scheduled time. A post demoted from scheduled keeps its time while in draft; null when no time is stored.

Example response

{
  "message": "Post updated successfully"
}

Changes