# Quickstart: publish your first post with the API
URL: https://skedcast.com/developers/guides/social-media-posting-api-quickstart

This is the fastest path from zero to a scheduled post: create an API key, find a connected account, and send one POST /v1/posts call. Every step is a runnable curl command. API keys are available on plans that include API access (see pricing).

## 1. Create an API key
In the SkedCast console, open Settings → Developer and create a key (Owner or Manager only). Give it at least the `posts.read`, `posts.compose`, `accounts.read` and `clients.read` scopes. The secret is shown once, so copy it now.
A key starts with `sked_live_` or `sked_test_`. Test keys are not sandboxed: they act on the same real workspace.

## 2. Find an account to post to
You need at least one connected social account. List what's connected and note an account id. `GET /v1/clients` lists your client groups, and you need one client id for the compose call.

## Example
```bash
curl "https://api.skedcast.com/v1/accounts" \
  -H "Authorization: Bearer sked_live_YOUR_KEY"

curl "https://api.skedcast.com/v1/clients" \
  -H "Authorization: Bearer sked_live_YOUR_KEY"
```

## 3. Publish a post
Call POST /v1/posts with a client id, the account you're targeting and a schedule. Every POST, PATCH and DELETE needs an `Idempotency-Key` (except `POST /v1/posts/preview`). Any unique string works. A UUID is easiest.

## Schedule a post for a specific time.
```bash
curl -X POST https://api.skedcast.com/v1/posts \
  -H "Authorization: Bearer sked_live_YOUR_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "<clientId>",
    "content": "Hello from the SkedCast API 🚀",
    "mediaIds": [],
    "targets": { "mode": "selection", "accountIds": ["<accountId>"] },
    "schedule": { "type": "at", "scheduledAt": "2030-01-15T15:00:00Z" }
  }'
```

## Quickstart: publish your first post with the API
Send `schedule: { "type": "now" }` to publish immediately. Use `"type": "range"` with `from`, `to` and an optional `spreadMinutes` to spread a batch across a window with per-account pacing. To add media, upload it first (see the media guide) and pass the returned asset id in `mediaIds`.

## 4. Confirm it published
`GET /v1/post-targets` (or `GET /v1/posts/{id}`) reports each destination's status and, once published, the platform's own `externalId` and public `permalink`. For anything beyond a one-off script, subscribe to the `target.published` and `target.failed` webhooks instead of polling.

## Example
```bash
curl "https://api.skedcast.com/v1/post-targets?limit=5" \
  -H "Authorization: Bearer sked_live_YOUR_KEY"
```

## FAQ
**Q: Do I need OAuth to try this, or is an API key enough?**
A: An API key is enough for your own scripts and servers, and it's what this quickstart uses. Use OAuth 2.1 only when a third-party app or AI agent needs to act on behalf of a separate SkedCast user's workspace.

**Q: What's the minimum body POST /v1/posts accepts?**
A: clientId, targets (mode plus account ids) and schedule are required. content defaults to an empty string and mediaIds to an empty array, though in practice you'll send real caption text.