Metadata-Version: 2.5
Name: langchain-upload-post
Version: 0.1.0
Summary: LangChain tools to publish, schedule and analyze social media posts with Upload-Post (TikTok, Instagram, YouTube, LinkedIn, X, Facebook and more).
Project-URL: Homepage, https://www.upload-post.com
Project-URL: Documentation, https://docs.upload-post.com/guides/langchain
Project-URL: Repository, https://github.com/Upload-Post/langchain-upload-post
Project-URL: API Reference, https://docs.upload-post.com/api/reference
Author-email: Upload-Post <info@upload-post.com>
Maintainer-email: Upload-Post <info@upload-post.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,instagram,langchain,linkedin,social-media,tiktok,tools,upload-post,youtube
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: langchain-core<2.0.0,>=1.0.0
Requires-Dist: upload-post<3.0.0,>=2.13.0
Description-Content-Type: text/markdown

# langchain-upload-post

[![PyPI - Version](https://img.shields.io/pypi/v/langchain-upload-post)](https://pypi.org/project/langchain-upload-post/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

LangChain tools for [Upload-Post](https://www.upload-post.com): let an agent
publish, schedule and track social media posts on **TikTok, Instagram, YouTube,
LinkedIn, Facebook, X, Threads, Pinterest, Bluesky, Discord, Telegram,
Google Business** and more, with a single API.

Built on the official [`upload-post`](https://pypi.org/project/upload-post/)
Python SDK.

## Installation

```bash
pip install -U langchain-upload-post
```

## Credentials

Create an account at [upload-post.com](https://www.upload-post.com), connect
your social accounts to a profile, and generate an API key in the
[dashboard](https://app.upload-post.com). Then set:

```bash
export UPLOAD_POST_API_KEY="your-api-key"
export UPLOAD_POST_PROFILE="my-profile"   # optional: default profile to post from
```

Both values can also be passed explicitly:
`UploadPostToolkit(api_key="...", profile="my-profile")`.

## Tools

| Tool | Name | What it does |
| --- | --- | --- |
| `UploadPostVideo` | `upload_post_video` | Publish or schedule a video from a public URL |
| `UploadPostPhotos` | `upload_post_photos` | Publish or schedule one or more photos / a carousel from public URLs |
| `UploadPostText` | `upload_post_text` | Publish or schedule a text post |
| `UploadPostStatus` | `upload_post_status` | Status of an upload by `request_id` or `job_id` |
| `UploadPostScheduledPosts` | `upload_post_scheduled_posts` | List scheduled posts |
| `UploadPostHistory` | `upload_post_history` | Upload history, filterable by platform, status, profile and date |
| `UploadPostListProfiles` | `upload_post_list_profiles` | Profiles and their connected social accounts |
| `UploadPostAnalytics` | `upload_post_analytics` | Account analytics per platform |

`UploadPostToolkit` returns all of them sharing one API client.
`UploadPostToolkit(read_only=True)` returns only the five tools that never
publish anything.

## Use with an agent

```python
# pip install -U langchain-upload-post "langchain[anthropic]"
from langchain.agents import create_agent

from langchain_upload_post import UploadPostToolkit

tools = UploadPostToolkit(profile="my-profile").get_tools()

agent = create_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=tools,
    system_prompt=(
        "You manage social media through Upload-Post. Check the connected "
        "accounts before publishing and confirm the platforms with the user."
    ),
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "Post https://example.com/launch.mp4 to TikTok and Instagram "
                    "tomorrow at 18:00 Madrid time with the caption "
                    "'We just launched!' and then show me my scheduled posts."
                ),
            }
        ]
    }
)
print(result["messages"][-1].content)
```

## Use a tool directly

```python
from langchain_upload_post import UploadPostText, UploadPostStatus

text = UploadPostText(profile="my-profile")
print(text.invoke({"text": "Hello from LangChain!", "platforms": ["x", "linkedin"]}))

status = UploadPostStatus()
print(status.invoke({"request_id": "..."}))
```

Every tool returns the API response as a JSON string. API errors are returned
to the model as the tool result (instead of raising) so the agent can react to
them.

### Platform-specific options

The publish tools expose the common fields (caption, description, schedule,
queue, first comment). Any other field documented in the
[Upload-Post API reference](https://docs.upload-post.com/api/reference) can be
passed through `platform_options`:

```python
from langchain_upload_post import UploadPostVideo

UploadPostVideo(profile="my-profile").invoke(
    {
        "video": "https://example.com/clip.mp4",
        "platforms": ["youtube", "tiktok"],
        "title": "Behind the scenes",
        "platform_options": {
            "privacyStatus": "unlisted",       # YouTube
            "tags": ["bts", "making-of"],      # YouTube
            "privacy_level": "SELF_ONLY",      # TikTok
            "tiktok_title": "BTS #makingof",   # per-platform caption
        },
    }
)
```

### Local files (off by default)

By default the publish tools only accept **public http(s) URLs** for media: a
local path is rejected with an error the model can read. This stops a model
(or a prompt injection) from uploading arbitrary files from the machine the
agent runs on.

If you run the agent in a trusted, single-user environment and want it to
publish files from disk, turn local paths on explicitly:

```python
UploadPostToolkit(allow_local_files=True)
# or per tool / per wrapper:
UploadPostVideo(allow_local_files=True)
UploadPostAPIWrapper(allow_local_files=True)
```

## Development

```bash
uv sync --group test
uv run pytest tests/unit_tests --disable-socket --allow-unix-socket
# integration tests hit the real API (read-only endpoints only):
UPLOAD_POST_API_KEY=... UPLOAD_POST_PROFILE=... uv run pytest tests/integration_tests
```

## Links

- Upload-Post: https://www.upload-post.com
- LangChain guide: https://docs.upload-post.com/guides/langchain
- API docs: https://docs.upload-post.com
- Source: https://github.com/Upload-Post/langchain-upload-post
- Python SDK: https://pypi.org/project/upload-post/

## License

MIT
