# Getting started

The Viraloop API generates ready-to-post short-form videos (wall of text, slideshow, green screen) from your brand's context and publishes them to connected TikTok, Instagram and YouTube accounts. This guide takes you from an empty terminal to a published post.

Base URL: `https://viraloop.io/api/v1`. Every response uses one envelope: `{ "success": true, "data": ..., "pagination"? }` on success, `{ "success": false, "error": { "type", "message" } }` on failure.

## 1. Create an API key

Create a key in the dashboard at https://viraloop.io/settings/developers. Pick the scopes the key needs; for this guide use `accounts:read`, `generations:write`, `posts:read` and `posts:write`. Keys look like `vl_live_...` and the full key is shown once at creation, so store it somewhere safe (an environment variable or secret manager).

```bash
export VIRALOOP_API_KEY=vl_live_...
```

## 2. Verify auth with /me

`GET /me` works with any valid key and returns your team, credit balance, plan, default workspace and the scopes granted to the key.

```bash
curl -s https://viraloop.io/api/v1/me \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"
```

Or with the CLI:

```bash
npm install -g viraloop
viraloop login        # or rely on the VIRALOOP_API_KEY env var
viraloop whoami --json
```

## 3. Find your connected accounts

Posting requires at least one connected social account. Connecting accounts (OAuth) happens in the web app at https://viraloop.io/accounts, not through the API. List what is connected and note the account ids:

```bash
curl -s https://viraloop.io/api/v1/accounts \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"
```

```bash
viraloop accounts list --json
```

## 4. Generate content

`POST /generations` is synchronous: the request returns when generation finishes, typically 5 to 60 seconds depending on count. It costs no credits in v1.

```bash
curl -s -X POST https://viraloop.io/api/v1/generations \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 2}'
```

```bash
viraloop generate --count 2 --json
```

Each suggestion in the response has an `id`, a `caption` (the on-screen text), a `postCaption` (the post body), `hashtags` and a `why` rationale. See the [generations guide](/developers/docs/generations) for the details.

## 5. Publish a post

Publish a suggestion you like with `POST /posts`, targeting account ids from step 3:

```bash
curl -s -X POST https://viraloop.io/api/v1/posts \
  -H "Authorization: Bearer $VIRALOOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"suggestionId": "<suggestionId>", "selectedAccounts": {"tiktok": ["<accountId>"]}, "schedule": "asap"}'
```

```bash
viraloop posts create --suggestion <suggestionId> \
  --accounts tiktok:<accountId> --when asap --wait --json
```

The API responds with `202` and a `statusUrl`; the video renders server-side after the call returns. The CLI's `--wait` flag polls for you.

## 6. Poll until it is posted

```bash
curl -s https://viraloop.io/api/v1/posts/<postId> \
  -H "Authorization: Bearer $VIRALOOP_API_KEY"
```

```bash
viraloop posts get <postId> --json
```

Terminal statuses are `posted`, `partial`, `completed` and `failed`; a `renderStatus` of `failed` is also terminal. Once posted, the response includes a per-platform `postUrl` and an analytics snapshot (views, likes, comments, shares).

## Next steps

- [Authentication and scopes](/developers/docs/authentication)
- [Posts and scheduling](/developers/docs/posts-and-scheduling)
- [CLI](/developers/docs/cli) and [MCP](/developers/docs/mcp)
- Full endpoint reference: [/developers/reference](/developers/reference) or https://viraloop.io/llms-full.txt for agents