post-upload 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,37 @@
1
+ # Changelog
2
+
3
+ ## 1.2.0 (2026-11-22)
4
+
5
+ ### Renamed: `indreelforge` is now `post-upload`
6
+
7
+ - The distribution is now **`post-upload`** on PyPI (`pip install post-upload`) and the import package is **`post_upload`**. The main names are `PostUpload` and `PostUploadError`.
8
+ - Backward compatible: `IndReelForge`, `InReelForge`, `IndReelForgeError` and `InReelForgeError` are aliases of the new names, and the package still ships an `indreelforge` module (`import indreelforge`, `from indreelforge.client import ...`) that re-exports `post_upload` and emits a `DeprecationWarning`.
9
+ - Default API address is now `https://api.post-upload.com` (the old address keeps working while the move completes).
10
+ - `api_key` is optional: when omitted it is read from `POST_UPLOAD_API_KEY`, then `INDREELFORGE_API_KEY`.
11
+ - `User-Agent` is now `post-upload-python/<version>`.
12
+ - The old `indreelforge` PyPI package gets no further releases.
13
+
14
+ ### Large videos: chunked upload up to 500 MB
15
+
16
+ - `upload_video` sends local files larger than 95 MiB (`CHUNKED_THRESHOLD`, or the `chunked_threshold` client option) through the chunked upload endpoints automatically, then posts them by `staged_file_id`. `chunked=True` / `chunked=False` force or disable it.
17
+ - Parts are sent sequentially, exactly the server's `chunk_size` each, read from disk part by part, and retried with exponential backoff on 429, 5xx and network errors (honouring `Retry-After`; `max_retries` client option, default 5). A failed upload cancels its session.
18
+ - `on_progress(sent_bytes, total_bytes)` callback.
19
+ - New methods: `upload_large_file()` (returns the `staged_file_id`), `create_upload_session()`, `upload_part()`, `complete_upload_session()`, `get_upload_session()`, `abort_upload_session()`.
20
+ - `upload_video` also accepts `video_file` (bytes or a binary file object / stream) and `staged_file_id`; exactly one video source is allowed.
21
+ - `PostUploadError.headers` exposes the response headers.
22
+
23
+ ### Platforms and responses
24
+
25
+ - Six new platforms: `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk` (22 in total) in `PLATFORMS` and `CREDENTIAL_PLATFORMS`, with optional credential fields in the new `CREDENTIAL_OPTIONAL_FIELDS`.
26
+ - `data.skipped_platforms` (platforms the file is too large for) is typed (`SkippedPlatform`, `UploadResponse`) and returned by the new `get_skipped_platforms(response)` helper.
27
+ - Response `TypedDict`s are exported and the package ships `py.typed`.
28
+
29
+ ## 1.1.0
30
+
31
+ - Typed methods for the full REST API, typed errors, explicit `User-Agent`.
32
+ - Discord, Telegram, Slack, Mastodon and WordPress, and `connect_with_credentials()`.
33
+ - Class renamed `IndReelForge` (`InReelForge` kept as an alias).
34
+
35
+ ## 1.0.0
36
+
37
+ - First release.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 IndReelForge
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,3 @@
1
+ include README.md
2
+ include LICENSE
3
+ include CHANGELOG.md
@@ -0,0 +1,548 @@
1
+ Metadata-Version: 2.4
2
+ Name: post-upload
3
+ Version: 1.2.0
4
+ Summary: Official Python SDK for Post-Upload — one API to post to 22 platforms: Instagram, YouTube, TikTok, Facebook, X, LinkedIn, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop & Listmonk
5
+ Home-page: https://post-upload.com
6
+ Author: Post-Upload
7
+ Author-email: support@post-upload.com
8
+ Project-URL: Homepage, https://post-upload.com
9
+ Project-URL: Documentation, https://docs.post-upload.com
10
+ Project-URL: Source, https://github.com/Indreelforge/indreelforge-python
11
+ Project-URL: Bug Tracker, https://github.com/Indreelforge/indreelforge-python/issues
12
+ Keywords: social-media-api,instagram-api,youtube-api,tiktok-api,facebook-api,twitter-api,linkedin-api,threads-api,pinterest-api,reddit-api,bluesky-api,google-business-profile-api,social-media-posting,video-upload,post-upload,indreelforge,mcp,model-context-protocol,ai-agents,discord-api,telegram-api,slack-api,mastodon-api,wordpress-api,devto-api,hashnode-api,lemmy-api,nostr,whop-api,listmonk
13
+ Classifier: Development Status :: 5 - Production/Stable
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.8
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: Internet :: WWW/HTTP
25
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
26
+ Requires-Python: >=3.8
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Requires-Dist: requests>=2.28.0
30
+ Provides-Extra: test
31
+ Requires-Dist: pytest>=7; extra == "test"
32
+ Dynamic: author
33
+ Dynamic: author-email
34
+ Dynamic: classifier
35
+ Dynamic: description
36
+ Dynamic: description-content-type
37
+ Dynamic: home-page
38
+ Dynamic: keywords
39
+ Dynamic: license-file
40
+ Dynamic: project-url
41
+ Dynamic: provides-extra
42
+ Dynamic: requires-dist
43
+ Dynamic: requires-python
44
+ Dynamic: summary
45
+
46
+ # Post-Upload — Python SDK
47
+
48
+ [![PyPI version](https://img.shields.io/pypi/v/post-upload.svg)](https://pypi.org/project/post-upload/)
49
+ [![Python versions](https://img.shields.io/pypi/pyversions/post-upload.svg)](https://pypi.org/project/post-upload/)
50
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
51
+
52
+ Official Python SDK for the [Post-Upload](https://post-upload.com) API. Publish videos, photos, text and documents to **22 platforms** with a single API call: **Instagram, YouTube, TikTok, Facebook, X (Twitter), LinkedIn, Threads, Pinterest, Reddit, Bluesky, Google Business Profile, Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop & Listmonk**.
53
+
54
+ > **Moving from the `indreelforge` package?** The SDK was renamed with the product. Run `pip uninstall indreelforge && pip install post-upload`, then import from `post_upload`. Old code keeps running: this package still ships an `indreelforge` module (with a `DeprecationWarning`), and `IndReelForge` / `IndReelForgeError` are aliases of `PostUpload` / `PostUploadError`. The `indreelforge` package on PyPI gets no further updates. See [Upgrading](#upgrading).
55
+
56
+ ## Installation
57
+
58
+ ```bash
59
+ pip install post-upload
60
+ ```
61
+
62
+ Requires Python 3.8+. The only dependency is `requests`.
63
+
64
+ ## Quick start
65
+
66
+ ```python
67
+ from post_upload import PostUpload
68
+
69
+ client = PostUpload(api_key="your-api-key-here") # or set POST_UPLOAD_API_KEY
70
+
71
+ result = client.upload_video(
72
+ user="my-profile",
73
+ platforms=["instagram", "tiktok", "youtube"],
74
+ video_path="./my-video.mp4",
75
+ title="Check out this video!",
76
+ )
77
+
78
+ print(result["data"]["upload_id"])
79
+ ```
80
+
81
+ ## Configuration
82
+
83
+ ```python
84
+ client = PostUpload(
85
+ api_key="your-api-key", # Dashboard → API Keys. Default: $POST_UPLOAD_API_KEY
86
+ base_url="https://api.post-upload.com", # Optional (default)
87
+ timeout=120, # Optional, seconds per request (default 120)
88
+ session=None, # Optional requests.Session
89
+ headers={"X-Trace": "abc"}, # Optional extra headers
90
+ chunked_threshold=None, # Optional, bytes (default 95 MiB), see "Large videos"
91
+ max_retries=5, # Optional, retries per failed chunk
92
+ )
93
+
94
+ # Or as a context manager, which closes the HTTP session afterwards:
95
+ with PostUpload() as client: # key from POST_UPLOAD_API_KEY
96
+ print(client.get_me())
97
+ ```
98
+
99
+ Without `api_key` the client reads `POST_UPLOAD_API_KEY` (or the older `INDREELFORGE_API_KEY`). Every request sends `Authorization: Apikey <key>` and an explicit `User-Agent: post-upload-python/<version>`. (The API sits behind Cloudflare, which blocks generic agents such as `Python-urllib`; if you call the REST API without this SDK, set your own User-Agent.)
100
+
101
+ ## Publishing
102
+
103
+ ### Common upload options
104
+
105
+ All `upload_*` methods accept:
106
+
107
+ | Argument | API field | Description |
108
+ |---|---|---|
109
+ | `user` | `user` | Profile name (required) |
110
+ | `platforms` | `platform[]` | `instagram`, `youtube`, `tiktok`, `facebook`, `x`, `linkedin`, `threads`, `pinterest`, `reddit`, `bluesky`, `google_business`, `discord`, `telegram`, `slack`, `mastodon`, `wordpress`, `devto`, `hashnode`, `lemmy`, `nostr`, `whop`, `listmonk` (also exported as `PLATFORMS`) |
111
+ | `title` | `title` | Title / caption |
112
+ | `description` | `description` | Long description |
113
+ | `first_comment` | `first_comment` | First comment |
114
+ | `schedule` | `schedule` | ISO-8601 datetime to publish later |
115
+ | `timezone` | `timezone` | IANA timezone for `schedule` |
116
+ | `add_to_queue` | `add_to_queue` | Put the post in the profile's next free queue slot |
117
+ | `async_upload` | `async_upload` | `False` = wait (up to ~50 s) for the publish result |
118
+ | `request_id` | `request_id` | Your own correlation id (see `get_request_status`) |
119
+ | `idempotency_key` | `Idempotency-Key` header | Retries with the same key never double-post |
120
+ | `platform_options` / `**kwargs` | any | Platform-specific fields, sent as-is (see below) |
121
+
122
+ ### Upload a video
123
+
124
+ ```python
125
+ # From a local file
126
+ client.upload_video(
127
+ user="my-profile",
128
+ platforms=["instagram", "tiktok", "youtube", "facebook"],
129
+ video_path="./video.mp4",
130
+ title="My video",
131
+ first_comment="#socialmedia",
132
+ schedule="2026-12-01T10:00:00Z",
133
+ youtube_privacy="public",
134
+ youtube_tags="tutorial,tech",
135
+ idempotency_key="video-2026-12-01",
136
+ )
137
+
138
+ # From a public URL (the server downloads it, up to 500 MB)
139
+ client.upload_video(
140
+ user="my-profile",
141
+ platforms=["tiktok"],
142
+ video_url="https://cdn.example.com/clip.mp4",
143
+ )
144
+
145
+ # From bytes or an open binary file / stream
146
+ with open("./video.mp4", "rb") as f:
147
+ client.upload_video(user="my-profile", platforms=["x"], video_file=f, title="Clip")
148
+ ```
149
+
150
+ Give the video in exactly one way: `video_path`, `video_file`, `video_url` or `staged_file_id`.
151
+
152
+ ### Large videos (chunked upload, up to 500 MB)
153
+
154
+ Requests reach the API through Cloudflare, which caps one request at 100 MB. **Local files larger than 95 MiB are sent in parts automatically**: the SDK starts an upload session, sends each part (sequentially, exactly the server's `chunk_size`, retrying on `429`, `5xx` and network errors with backoff and `Retry-After`), completes it and posts the result by `staged_file_id`. Files are read part by part, never loaded whole into memory. If anything fails after the session started, the session is cancelled and the error is raised.
155
+
156
+ ```python
157
+ def progress(sent, total):
158
+ print(f"{sent * 100 // total}%")
159
+
160
+ client.upload_video(
161
+ user="my-profile",
162
+ platforms=["youtube", "facebook"],
163
+ video_path="./full-episode.mp4", # e.g. 380 MB
164
+ title="Full episode",
165
+ on_progress=progress, # called after each part
166
+ )
167
+ ```
168
+
169
+ `chunked=True` forces the chunked path for any size, `chunked=False` disables it. To upload once and post later, or to drive the parts yourself:
170
+
171
+ ```python
172
+ staged = client.upload_large_file("./full-episode.mp4", on_progress=progress)
173
+ client.upload_video("my-profile", ["youtube"], staged_file_id=staged, title="Full episode")
174
+
175
+ # Low level (POST/PUT/GET/DELETE /api/upload/chunked/...)
176
+ s = client.create_upload_session("episode.mp4", size, "video/mp4")
177
+ # -> upload_session_id, chunk_size (32 MiB), total_chunks, expires_at (6 hours)
178
+ for i in range(s["total_chunks"]):
179
+ client.upload_part(s["upload_session_id"], i, read_part(i, s["chunk_size"]))
180
+ client.get_upload_session(s["upload_session_id"]) # received_chunks, to resume
181
+ staged = client.complete_upload_session(s["upload_session_id"])["staged_file_id"]
182
+ # client.abort_upload_session(s["upload_session_id"]) # cancel
183
+ ```
184
+
185
+ A staged file can be posted once, only by the account (and workspace) that uploaded it. Chunked upload is for videos (MP4, MOV, AVI, WebM, MKV); at most 5 sessions can be in progress per account.
186
+
187
+ ### Skipped platforms
188
+
189
+ Each platform has its own maximum file size (for example Bluesky 100 MB, Discord 10 MB). Platforms the file is too large for are **skipped**: the post goes to the others, and the skipped ones are marked `failed` with `FILE_TOO_LARGE_FOR_PLATFORM` and listed in `data.skipped_platforms`. `get_skipped_platforms()` returns that list (or `[]`):
190
+
191
+ ```python
192
+ from post_upload import get_skipped_platforms
193
+
194
+ res = client.upload_video("my-profile", ["youtube", "bluesky"], video_path="./big.mp4")
195
+ for s in get_skipped_platforms(res):
196
+ print(s["platform"], s["message"]) # also: error_code, file_size_mb, max_size_mb
197
+ ```
198
+
199
+ Only when no selected platform can take the file is the request refused (`413 FILE_TOO_LARGE_FOR_PLATFORM`). The response types are exported as `TypedDict`s (`UploadResponse`, `SkippedPlatform`, `UploadSession`, …) for type checkers.
200
+
201
+ ### Upload photos
202
+
203
+ Local files, public URLs, or both — up to 10 in total.
204
+
205
+ ```python
206
+ client.upload_photos(
207
+ user="my-profile",
208
+ platforms=["instagram", "facebook", "pinterest"],
209
+ photo_paths=["./photo1.jpg"],
210
+ photo_urls=["https://cdn.example.com/photo2.jpg"],
211
+ title="Photo carousel",
212
+ platform_options={"pinterest_board_id": "1234567890"},
213
+ )
214
+ ```
215
+
216
+ ### Text post
217
+
218
+ ```python
219
+ client.upload_text(
220
+ user="my-profile",
221
+ platforms=["x", "threads", "bluesky", "linkedin"],
222
+ text="Just shipped a new feature!", # `title=` still works as in 1.0
223
+ )
224
+ ```
225
+
226
+ ### Document post (LinkedIn)
227
+
228
+ ```python
229
+ client.upload_document(
230
+ user="my-profile",
231
+ document_path="./deck.pdf", # PDF, PPT, PPTX, DOC, DOCX (max 100 MB)
232
+ title="Q4 results",
233
+ visibility="PUBLIC",
234
+ target_linkedin_page_id="12345", # optional: post as a company page
235
+ )
236
+ ```
237
+
238
+ ### Synchronous mode
239
+
240
+ By default an upload returns immediately and publishes in the background. With `async_upload=False` the server waits up to about 50 seconds and returns the outcome:
241
+
242
+ ```python
243
+ res = client.upload_text(user="my-profile", platforms=["bluesky"], text="hi", async_upload=False)
244
+ if res.get("sync"):
245
+ print(res["data"]["status"], res["data"]["platforms"], res["data"]["platform_post_ids"])
246
+ else:
247
+ # Took longer than the wait window: poll instead
248
+ print(client.get_upload_status(res["data"]["upload_id"]))
249
+ ```
250
+
251
+ ### Platform-specific options
252
+
253
+ Pass any platform-specific API field through `platform_options` (or as extra keyword arguments). Lists are sent as repeated fields, booleans as `"true"`/`"false"`, dicts as JSON.
254
+
255
+ ```python
256
+ client.upload_photos(
257
+ user="my-profile",
258
+ platforms=["tiktok", "google_business", "reddit"],
259
+ photo_urls=["https://cdn.example.com/menu.jpg"],
260
+ title="New menu is live",
261
+ platform_options={
262
+ "privacy_level": "PUBLIC_TO_EVERYONE", # TikTok
263
+ "auto_add_music": True,
264
+ "gbp_location_id": "locations/123", # Google Business Profile
265
+ "gbp_cta_type": "LEARN_MORE",
266
+ "gbp_cta_url": "https://example.com",
267
+ "reddit_subreddit": "food", # Reddit
268
+ },
269
+ )
270
+ ```
271
+
272
+ Use the platform helper methods below to look up page, board and location ids.
273
+
274
+ **Per-platform text overrides (every platform).** `<platform>_title` and `<platform>_description` replace the shared `title` / `description` for that platform only, e.g. `x_title`, `linkedin_description`, `mastodon_title`, `wordpress_description`.
275
+
276
+ **Mastodon**
277
+
278
+ | Field | Values |
279
+ |---|---|
280
+ | `mastodon_visibility` | `public` (default), `unlisted`, `private` or `direct` |
281
+ | `mastodon_spoiler_text` | Content warning shown before the post |
282
+ | `mastodon_sensitive` | `True` to mark media as sensitive. Omit it otherwise: the server treats any non-empty value, including `"false"`, as true |
283
+ | `mastodon_alt_text` | Alt text for attached media (defaults to the title) |
284
+ | `mastodon_language` | ISO 639 language code, e.g. `"en"` |
285
+
286
+ **WordPress**
287
+
288
+ | Field | Values |
289
+ |---|---|
290
+ | `wordpress_status` | `publish` (default) or `draft` |
291
+ | `wordpress_categories` | Numeric category IDs: `"3,7"` or `[3, 7]` |
292
+ | `wordpress_tags` | Numeric tag IDs: `"12,15"` or `[12, 15]` |
293
+
294
+ ```python
295
+ client.upload_text(
296
+ user="my-profile",
297
+ platforms=["mastodon", "wordpress", "slack"],
298
+ text="Release notes",
299
+ description="Full changelog for 1.1 …",
300
+ platform_options={
301
+ "mastodon_title": "Release notes are out (short version for Mastodon)",
302
+ "mastodon_visibility": "unlisted",
303
+ "mastodon_language": "en",
304
+ "wordpress_status": "draft",
305
+ "wordpress_categories": [3, 7],
306
+ "wordpress_tags": "12,15",
307
+ },
308
+ )
309
+ ```
310
+
311
+ ## Connect platforms with credentials
312
+
313
+ Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk connect with credentials instead of an OAuth login. `connect_with_credentials(profile, platform, credentials=None, **fields)` sends them to the API, which verifies them live with the platform before saving them (encrypted). Connecting again replaces the stored credentials. Pass the fields as a dict, as keyword arguments, or both (keyword arguments win):
314
+
315
+ | Platform | Fields (`?` = optional) |
316
+ |---|---|
317
+ | `discord` | `webhook_url` — channel webhook URL |
318
+ | `telegram` | `bot_token`, `chat_id` — token from @BotFather; public channel `@username` or numeric chat ID |
319
+ | `slack` | `webhook_url` — incoming webhook URL (Slack can only verify it on the first post) |
320
+ | `mastodon` | `instance_url`, `access_token` — e.g. `https://mastodon.social`; token with `write:statuses` and `write:media` |
321
+ | `wordpress` | `site_url`, `username`, `app_password` — self-hosted site, a user who can publish, an application password |
322
+ | `devto` | `api_key`, `base_url?` — DEV API key (Settings → Extensions); `base_url` only for another Forem site |
323
+ | `hashnode` | `access_token`, `publication_id` — personal access token; the publication needs a Hashnode Pro plan |
324
+ | `lemmy` | `instance_url`, `username`, `password`, `community`, `totp?` — community as `name` or `name@instance`; `totp` only with 2FA (used once, not stored) |
325
+ | `nostr` | `nsec`, `relays?`, `blossom_server?` — `nsec1…` or hex key; comma-separated `wss://` relays; Blossom server for photos |
326
+ | `whop` | `api_key` + **one of** `experience_id` (forum, `exp_…`) or `channel_id` (chat) |
327
+ | `listmonk` | `base_url`, `api_user`, `api_token`, `list_ids` — API user with campaigns:manage, campaigns:send, lists:get_all, media:manage; list IDs comma-separated |
328
+
329
+ ```python
330
+ from post_upload import PostUploadError
331
+
332
+ res = client.connect_with_credentials("my-profile", "telegram", bot_token="123456789:AA…", chat_id="@mychannel")
333
+ print(res["platform_username"])
334
+
335
+ client.connect_with_credentials("my-profile", "devto", api_key="…")
336
+ client.connect_with_credentials("my-profile", "whop", api_key="…", experience_id="exp_XXXXXXXX")
337
+
338
+ try:
339
+ client.connect_with_credentials(
340
+ "my-profile", "mastodon", {"instance_url": "https://mastodon.social", "access_token": "bad"}
341
+ )
342
+ except PostUploadError as e:
343
+ if e.status_code == 400:
344
+ # e.code: "MISSING_FIELD" | "FIELD_TOO_LONG" | "INVALID_CREDENTIALS"
345
+ print(e.code, (e.body.get("details") or {}).get("field"), e)
346
+ ```
347
+
348
+ Other failures: `404` (profile not found) and `502` (the platform could not be reached to verify the details). The required fields per platform are also exported as `CREDENTIAL_PLATFORMS`, the optional ones as `CREDENTIAL_OPTIONAL_FIELDS`.
349
+
350
+ ## All methods
351
+
352
+ | Area | Method | Endpoint |
353
+ |---|---|---|
354
+ | Upload | `upload_video(user, platforms, video_path=None, ..., video_url=None, video_file=None, staged_file_id=None, chunked=None, on_progress=None)` | `POST /api/upload` (+ chunked endpoints for large files) |
355
+ | | `upload_photos(user, platforms, photo_paths=None, ..., photo_urls=None)` | `POST /api/upload_photos` |
356
+ | | `upload_text(user, platforms, title=None, ..., text=None)` | `POST /api/upload_text` |
357
+ | | `upload_document(user, document_path, title=None, ...)` | `POST /api/upload_document` |
358
+ | Chunked upload | `upload_large_file(video, filename=None, mime_type=None, on_progress=None)` → `staged_file_id` | init + parts + complete |
359
+ | | `create_upload_session(filename, size, mime_type=None)` | `POST /api/upload/chunked/init` |
360
+ | | `upload_part(session_id, index, data, retries=None)` | `PUT /api/upload/chunked/:id/:index` |
361
+ | | `complete_upload_session(session_id)` | `POST /api/upload/chunked/:id/complete` |
362
+ | | `get_upload_session(session_id)` | `GET /api/upload/chunked/:id` |
363
+ | | `abort_upload_session(session_id)` | `DELETE /api/upload/chunked/:id` |
364
+ | Account | `get_me()` | `GET /api/me` |
365
+ | Uploads | `get_upload_status(upload_id)` | `GET /api/upload/:id/status` |
366
+ | | `get_request_status(request_id)` | `GET /api/uploadposts/status?request_id=` |
367
+ | | `list_uploads(limit=None, page=None, status=None)` | `GET /api/uploads` |
368
+ | | `get_upload(upload_id)` | `GET /api/uploads/:id` |
369
+ | | `delete_upload(upload_id)` | `DELETE /api/uploads/:id` |
370
+ | | `retry_upload(upload_id)` | `POST /api/uploads/:id/retry` |
371
+ | | `get_platform_limits()` | `GET /api/platform-limits` |
372
+ | Profiles | `get_profiles()` | `GET /api/profiles` |
373
+ | | `create_profile(name)` | `POST /api/profiles` |
374
+ | | `delete_profile(name)` | `DELETE /api/profiles/:name` |
375
+ | | `connect_with_credentials(profile, platform, credentials=None, **fields)` | `POST /api/profiles/:name/connect/:platform/credentials` |
376
+ | Schedule | `get_scheduled_posts()` | `GET /api/schedule` |
377
+ | | `update_scheduled_post(job_id, scheduled_date=None, timezone=None, title=None, caption=None)` | `PATCH /api/schedule/:jobId` |
378
+ | | `cancel_scheduled_post(job_id)` | `DELETE /api/schedule/:jobId` |
379
+ | Queue | `get_queue_settings(profile)` | `GET /api/queue/settings` |
380
+ | | `update_queue_settings(profile, slots=None, days_of_week=None, timezone=None, max_posts_per_slot=None)` | `POST /api/queue/settings` |
381
+ | | `get_queue_preview(profile, count=None)` | `GET /api/queue/preview` |
382
+ | | `get_next_queue_slot(profile)` | `GET /api/queue/next-slot` |
383
+ | Platform helpers | `get_facebook_pages(profile)` | `GET /api/platforms/facebook/pages` |
384
+ | | `get_linkedin_pages(profile)` | `GET /api/platforms/linkedin/pages` |
385
+ | | `get_pinterest_boards(profile)` | `GET /api/platforms/pinterest/boards` |
386
+ | | `get_google_business_locations(profile)` | `GET /api/platforms/google-business/locations` |
387
+ | Analytics | `get_analytics(range="30d")` | `GET /api/analytics/overview` |
388
+ | | `get_live_analytics(profile, platforms=None)` | `GET /api/analytics/live/:profile` |
389
+ | | `get_post_analytics(upload_id, platform=None)` | `GET /api/analytics/post/:upload_id` |
390
+ | | `get_total_impressions(profile, platform=None, period=None, start_date=None, end_date=None)` | `GET /api/analytics/total-impressions/:profile` |
391
+ | FFmpeg | `get_ffmpeg_usage()` | `GET /api/ffmpeg/usage` |
392
+ | | `list_ffmpeg_jobs()` | `GET /api/ffmpeg/jobs` |
393
+ | | `get_ffmpeg_job(job_id)` | `GET /api/ffmpeg/jobs/:jobId` |
394
+ | Plans | `get_plans()` | `GET /api/plans` |
395
+
396
+ Examples:
397
+
398
+ ```python
399
+ me = client.get_me() # plan + monthly usage
400
+ failed = client.list_uploads(status="failed", limit=10)["uploads"]
401
+ if failed:
402
+ client.retry_upload(failed[0]["id"])
403
+
404
+ client.update_queue_settings(
405
+ "my-profile",
406
+ slots=["09:00", "17:30"],
407
+ days_of_week=[1, 2, 3, 4, 5],
408
+ timezone="Europe/London",
409
+ )
410
+ client.upload_video("my-profile", ["youtube"], "./v.mp4", add_to_queue=True)
411
+
412
+ posts = client.get_scheduled_posts()["scheduled_posts"]
413
+ client.update_scheduled_post(posts[0]["id"], scheduled_date="2026-12-24T09:00:00Z")
414
+ ```
415
+
416
+ ## Error handling
417
+
418
+ Every API failure raises `PostUploadError` (`IndReelForgeError` is the same class):
419
+
420
+ | Attribute | Description |
421
+ |---|---|
422
+ | `status_code` (alias `status`) | HTTP status (`0` = network error, `408` = client-side timeout) |
423
+ | `code` | API error code (`error_code` / `code`), e.g. `MISSING_VIDEO`, or `NETWORK_ERROR` / `TIMEOUT` |
424
+ | `body` | Parsed response body (dict) or raw text |
425
+ | `headers` | Response headers (`None` for network errors), e.g. `Retry-After` |
426
+ | `str(err)` | Human-readable message from the API |
427
+
428
+ ```python
429
+ from post_upload import PostUploadError
430
+
431
+ try:
432
+ client.upload_video(user="my-profile", platforms=["tiktok"], video_path="./v.mp4")
433
+ except PostUploadError as e:
434
+ print(f"API error {e.status_code} ({e.code}): {e}", e.body)
435
+ except FileNotFoundError as e:
436
+ print(f"File not found: {e}")
437
+ ```
438
+
439
+ Invalid arguments (for example neither `video_path` nor `video_url`, or more than 10 photos) raise `ValueError` before any request is made.
440
+
441
+ ## MCP: use Post-Upload from AI agents
442
+
443
+ Post-Upload runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server, so Claude, ChatGPT, Cursor and other agents can publish posts, check upload status and read analytics with your API key. No Python is needed for this.
444
+
445
+ **Hosted URL (Streamable HTTP)** — for clients that support remote MCP servers with headers:
446
+
447
+ - URL: `https://api.post-upload.com/mcp`
448
+ - Header: `Authorization: ApiKey your-api-key`
449
+
450
+ **stdio clients (Claude Desktop, Cursor)** — use the bridge from the [Node.js package](https://www.npmjs.com/package/post-upload) (requires Node.js 18+):
451
+
452
+ ```json
453
+ {
454
+ "mcpServers": {
455
+ "post-upload": {
456
+ "command": "npx",
457
+ "args": ["-y", "post-upload", "mcp"],
458
+ "env": {
459
+ "POST_UPLOAD_API_KEY": "your-api-key"
460
+ }
461
+ }
462
+ }
463
+ }
464
+ ```
465
+
466
+ See the [Node.js SDK README](https://github.com/Indreelforge/indreelforge-node) and the [MCP guide](https://docs.post-upload.com/guides/mcp-server) for all MCP options. Agents that can't stream large files through MCP can pass a public `video_url` (up to 500 MB).
467
+
468
+ ## Supported platforms
469
+
470
+ | Platform | Video | Photo | Text | Document | Scheduling |
471
+ |----------|-------|-------|------|----------|------------|
472
+ | Instagram | ✓ | ✓ | - | - | ✓ |
473
+ | YouTube | ✓ | - | - | - | ✓ |
474
+ | TikTok | ✓ | ✓ | - | - | ✓ |
475
+ | Facebook | ✓ | ✓ | ✓ | - | ✓ |
476
+ | X (Twitter) | ✓ | ✓ | ✓ | - | ✓ |
477
+ | LinkedIn | ✓ | ✓ | ✓ | ✓ | ✓ |
478
+ | Threads | ✓ | ✓ | ✓ | - | ✓ |
479
+ | Pinterest | ✓ | ✓ | - | - | ✓ |
480
+ | Reddit | ✓ | ✓ | ✓ | - | ✓ |
481
+ | Bluesky | ✓ | ✓ | ✓ | - | ✓ |
482
+ | Google Business Profile | - | ✓ | ✓ | - | ✓ |
483
+ | Discord | ✓ | ✓ | ✓ | - | ✓ |
484
+ | Telegram | ✓ | ✓ | ✓ | - | ✓ |
485
+ | Slack | - | - | ✓ | - | ✓ |
486
+ | Mastodon | ✓ | ✓ | ✓ | - | ✓ |
487
+ | WordPress | ✓ | ✓ | ✓ | - | ✓ |
488
+ | Dev.to | - | - | ✓ | - | ✓ |
489
+ | Hashnode | - | ✓ | ✓ | - | ✓ |
490
+ | Lemmy | - | ✓ | ✓ | - | ✓ |
491
+ | Nostr | - | ✓ | ✓ | - | ✓ |
492
+ | Whop | ✓ | ✓ | ✓ | - | ✓ |
493
+ | Listmonk | - | ✓ | ✓ | - | ✓ |
494
+
495
+ Discord, Telegram, Slack, Mastodon, WordPress, Dev.to, Hashnode, Lemmy, Nostr, Whop and Listmonk are connected with [credentials](#connect-platforms-with-credentials); the others connect through an OAuth login in the dashboard (or an app password for Bluesky).
496
+
497
+ ## Upgrading
498
+
499
+ ### From `indreelforge` (1.1 and earlier) to `post-upload` 1.2
500
+
501
+ ```bash
502
+ pip uninstall indreelforge
503
+ pip install post-upload
504
+ ```
505
+
506
+ ```python
507
+ # before
508
+ from indreelforge import IndReelForge, IndReelForgeError
509
+ client = IndReelForge(api_key="...")
510
+
511
+ # after
512
+ from post_upload import PostUpload, PostUploadError
513
+ client = PostUpload(api_key="...")
514
+ ```
515
+
516
+ Nothing else changes: methods, arguments and return values are the same. Until you update your imports, `import indreelforge` keeps working from the `post-upload` package (it warns with `DeprecationWarning`), and `IndReelForge`, `InReelForge`, `IndReelForgeError` and `InReelForgeError` remain aliases of the new names. The default API address is now `https://api.post-upload.com` (the old address keeps working while the move completes), and the key can come from `POST_UPLOAD_API_KEY` (`INDREELFORGE_API_KEY` is still read).
517
+
518
+ Don't keep both packages installed: both provide an `indreelforge` module.
519
+
520
+ ### From 1.0 to 1.1
521
+
522
+ 1.1 is backward compatible: existing method names, positional arguments and return values keep working.
523
+
524
+ - The class was renamed `IndReelForge` (now `PostUpload`); `InReelForge` is still exported as an alias.
525
+ - The exception is `IndReelForgeError`; `InReelForgeError` is an alias, so `except InReelForgeError` still works.
526
+ - Uploads are always sent as `multipart/form-data`, and file handles are closed after each request.
527
+ - `upload_text` sends your text as `text` (the API treats `text` and `title` the same).
528
+
529
+ ## Development
530
+
531
+ ```bash
532
+ python -m venv .venv
533
+ .venv/bin/pip install -e ".[test]"
534
+ .venv/bin/python -m pytest
535
+ ```
536
+
537
+ ## Links
538
+
539
+ - [Website](https://post-upload.com)
540
+ - [API documentation](https://docs.post-upload.com)
541
+ - [Dashboard](https://post-upload.com/dashboard)
542
+ - [Pricing](https://post-upload.com/pricing)
543
+ - [Node.js SDK & MCP bridge](https://www.npmjs.com/package/post-upload)
544
+ - [Changelog](https://github.com/Indreelforge/indreelforge-python/blob/main/CHANGELOG.md)
545
+
546
+ ## License
547
+
548
+ MIT