# Getting started

Connect an account, create an API key, and publish your first post.

Source: https://opensocial.run/docs/getting-started
Markdown: https://opensocial.run/docs/getting-started.md



Use the dashboard for account connection and post management. Use an API key
to connect the API, CLI, or an agent to your organisation.

## Using an AI agent? [#using-an-ai-agent]

Help me integrate Open Social with my application or AI agent.

Read these documents first:
- Documentation index: https://opensocial.run/llms.txt
- Getting started: https://opensocial.run/docs/getting-started.md
- API reference: https://opensocial.run/docs/api.md
- Platform requirements: https://opensocial.run/docs/video-platforms.md
- All public documentation: https://opensocial.run/llms-full.txt

For a self-hosted service, replace the origin in these URLs with the service address.

Use the REST API at the service address with the /v1 path, the repository CLI, or the Open Social MCP tools. Ask which client and service address to use if they are not known. Follow the connection instructions in the getting started guide. Keep API keys in environment variables. Do not put keys in source code or logs.

List connected accounts and read platform capabilities before you create a post. Use returned account and media IDs. Do not guess IDs, limits, or platform options. For TikTok, read current publishing options and ask the creator to select privacy and confirm consent for each video.

Validate content for all target accounts. Correct errors before publication. Create a draft unless I request publication or a schedule. Use an RFC 3339 timestamp with an explicit time zone for a schedule. Confirm the time zone if it is not known.

A publish request starts an asynchronous operation. Check each publication status before you report success. Report failures and partial success. Do not repeat a publish request without checking the current post status.


## Connect an account [#connect-an-account]

1. [Sign in or create an account](https://opensocial.run/login).
2. Open [Accounts](https://opensocial.run/dashboard/accounts) and select **Connect an account**.
3. Select a platform and complete its connection steps. For OAuth platforms,
   sign in with the platform and grant the requested permissions.
4. Confirm that the account status is **Connected**.

For Bluesky, use your handle and an app password. For Instagram, TikTok, and
YouTube, see the [platform guide](https://opensocial.run/docs/video-platforms).

If a platform shows **Setup required**, contact the service administrator.
If an account shows **Needs reconnect**, connect that account again.

## Create your first post [#create-your-first-post]

1. Open [Posts](https://opensocial.run/dashboard/posts) and create a post.
2. Select the connected accounts that must receive the post.
3. Enter text, attach media, and set the required platform options.
4. Validate the post and correct each reported error.
5. Save a draft, publish now, or select a date and time to schedule the post.

A publish request starts the publication process. Check the status of each
publication before you report that the post was published. A post can succeed
on one platform and fail on another.

## Create an API key [#create-an-api-key]

Open [API keys](https://opensocial.run/dashboard/keys) and create a key. Copy the full key when it is
shown. The key is shown only once. The prefix in the key list cannot authenticate
requests.

Select the permissions your client needs. An empty scope list gives full access.
For the agent workflow below, a restricted key needs `accounts:read`,
`capabilities:read`, `posts:read`, and `posts:write`. Add `media:write` for uploads
and `events:read` to read events.

Select **How to use** on the API keys page for CLI, MCP, and REST connection
instructions. Keep the key private.

If a key is exposed or no longer needed, select its **Revoke API key** row
action and confirm. The key stops working for CLI, REST, and MCP requests.
You can also run `bun run cli -- keys revoke key_example` with a full access
key or a key that has `keys:write`. Replace `key_example` with the key ID from
`bun run cli -- keys list`. Revocation cannot be undone.

## Use an agent [#use-an-agent]

Add Open Social to your MCP client with the instructions in **How to use**.
Ask the agent to list your connected accounts to check its connection.

For a client that supports an MCP JSON configuration, use this template:

```json
{
  "mcpServers": {
    "open-social": {
      "command": "bun",
      "args": ["--cwd", "/absolute/path/to/open-social", "run", "mcp"],
      "env": {
        "OPEN_SOCIAL_BASE_URL": "https://opensocial.run",
        "OPEN_SOCIAL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

Install Bun and the repository dependencies with `bun install` first. Replace
the repository path and API key. For a local or self-hosted service, also
replace the service address. This MCP server uses stdio.
The client starts it as a local process. It does not use a remote MCP URL.
Keep the configuration private. Use the client's secret storage if available.

Use these tools in this order:

| Step | MCP tool                                        | Purpose                                                       |
| ---- | ----------------------------------------------- | ------------------------------------------------------------- |
| 1    | `social_accounts_list`                          | Get connected accounts and their IDs.                         |
| 2    | `social_capabilities_get`                       | Read text limits, media limits, and platform requirements.    |
| 3    | `social_account_publishing_options`             | Read current TikTok privacy choices and creator limits.       |
| 4    | `social_media_upload`                           | Upload an attachment and get its media ID, if needed.         |
| 5    | `social_post_validate`                          | Check text, attachments, and options for the target accounts. |
| 6    | `social_post_create`                            | Create a draft, or set `publish_at` to schedule the post.     |
| 7    | `social_post_publish` or `social_post_schedule` | Publish a draft or set its publication time.                  |
| 8    | `social_post_status`                            | Check the post and each publication result.                   |
| 9    | `social_events_list`                            | Read recent events, if needed.                                |

Pass account IDs from the account list. Use media IDs returned by the upload
tool. Do not guess IDs or platform limits. For TikTok, ask the creator to choose
the privacy level and confirm consent for each video.

The create and validate tools apply the same `platform_options` to all target
accounts. Use separate tool calls when accounts need different options.

## Use the CLI or API [#use-the-cli-or-api]

The **How to use** dialog supplies the client connection instructions. After
CLI setup, run these commands from the open-social repository directory:

```sh
export OPEN_SOCIAL_BASE_URL="https://opensocial.run"
export OPEN_SOCIAL_API_KEY="YOUR_API_KEY"
bun run cli -- accounts list
bun run cli -- capabilities bluesky
bun run cli -- posts validate --text "Hello from Open Social" --account acct_YOUR_ACCOUNT
bun run cli -- posts create --text "Hello from Open Social" --account acct_YOUR_ACCOUNT
bun run cli -- posts publish post_YOUR_POST
bun run cli -- posts status post_YOUR_POST
```

Replace the account ID with an ID from the account list. Replace the post ID
with the ID returned by the create command. Choose a platform that matches your
account. Run `bun run cli -- --help` for available commands.

For a local or self-hosted service, replace `https://opensocial.run` with your
service address. Set the API key in
your local environment. Do not commit it to the repository.

For REST requests, send your API key in the `Authorization` header. Use the
same service address as the dashboard, with the `/v1` path. See the
[API reference](https://opensocial.run/docs/api) for request bodies and response fields.

To check a REST connection, use the same environment variables:

```sh
curl --fail-with-body "$OPEN_SOCIAL_BASE_URL/v1/accounts" \
  -H "Authorization: Bearer $OPEN_SOCIAL_API_KEY"
```