---
title: "Create run"
method: POST
path: "/v1/posts/apply"
tags: ["Publishing Runs and Posts"]
---

# Create run

`POST /v1/posts/apply`

## Request

- Base URL: `https://getsocialclaw.com`
- URL: `https://getsocialclaw.com/v1/posts/apply`
- Auth: HTTP bearer

Creates a scheduled or draft run from a validated schedule.

Note: Use idempotencyKey for generated schedules and retry-safe clients.

Note: The route preflights connected accounts and plan entitlements before creating posts.

## Request body

- ScheduleEnvelope: Schedule document accepted by validation, preview, apply, and dashboard compose workflows.
  - `timezone` string: IANA timezone. Defaults to UTC.
  - `mode` 'scheduled' | 'draft': scheduled creates runnable posts; draft creates an editable draft run.
  - `idempotencyKey` string, nullable: Optional idempotency key. Also accepted as idempotency_key.
  - `posts` PostInput[]: Flat list of posts.
    - `provider` 'x' | 'threads' | 'meta' | 'facebook' | 'instagram_business' | 'instagram' | 'snapchat' | 'tiktok' | 'linkedin' | 'linkedin_page' | 'pinterest' | 'youtube' | 'reddit' | 'discord' | 'telegram' | 'wordpress' | 'null', nullable: Provider. Optional when account handle identifies the provider.
    - `account` string, required: Connected account handle or id.
    - `name` string, nullable: Post title, campaign step title, or provider title.
    - `title` string, nullable: Alias for name on providers requiring titles.
    - `description` string, nullable: Primary post text.
    - `text` string, nullable: Alias for description.
    - `publish_at` string, date-time, nullable: Scheduled publish time.
    - `publishAt` string, date-time, nullable: Camel-case alias for publish_at.
    - `media_link` string, nullable: Single public media URL.
    - `mediaLink` string, nullable: Camel-case alias for media_link.
    - `assets` union[]: One or more asset objects or URL strings.
      - union
        - AssetInput: Media asset referenced by a post.
          - `id` string, nullable: Client-side or SocialClaw asset id.
          - `url` string, required: Publicly reachable media URL.
          - `managed` boolean: True when this is a SocialClaw-managed asset.
          - `originalFilename` string, nullable: Original file name.
          - `mime` string, nullable: MIME type.
          - `kind` 'image' | 'video' | 'audio' | 'other' | 'null', nullable
          - `size` integer, nullable: File size in bytes.
          - `duration` number, nullable: Duration in seconds for video/audio.
          - `width` integer, nullable: Media width in pixels.
          - `height` integer, nullable: Media height in pixels.
          - `altText` string, nullable: Alt text where the provider supports it.
        - string, uri
    - `settings` object: Provider-specific settings from the publish settings API. Standalone Instagram supports destination/format plus per-media alt text and people tags, collaborators, Reel cover/thumbnail/feed/audio/Trial controls, AI disclosure, and location IDs. post_and_story requires one asset and creates two independent jobs.
    - `interaction_type` 'post' | 'reply' | 'comment' | 'null', nullable
    - `parent_step_id` string, nullable: Parent step id for reply/thread workflows.
  - `campaigns` CampaignInput[]: Campaign graph model.
    - `id` string, nullable: Campaign id.
    - `name` string, required: Campaign name.
    - `targets` object[], required: Publishing targets.
      - `account` string: Connected account handle.
      - `publish_at` string, date-time, nullable: Base publish time.
      - `steps` PostInput[]: Campaign steps.
        - `provider` 'x' | 'threads' | 'meta' | 'facebook' | 'instagram_business' | 'instagram' | 'snapchat' | 'tiktok' | 'linkedin' | 'linkedin_page' | 'pinterest' | 'youtube' | 'reddit' | 'discord' | 'telegram' | 'wordpress' | 'null', nullable: Provider. Optional when account handle identifies the provider.
        - `account` string, required: Connected account handle or id.
        - `name` string, nullable: Post title, campaign step title, or provider title.
        - `title` string, nullable: Alias for name on providers requiring titles.
        - `description` string, nullable: Primary post text.
        - `text` string, nullable: Alias for description.
        - `publish_at` string, date-time, nullable: Scheduled publish time.
        - `publishAt` string, date-time, nullable: Camel-case alias for publish_at.
        - `media_link` string, nullable: Single public media URL.
        - `mediaLink` string, nullable: Camel-case alias for media_link.
        - `assets` union[]: One or more asset objects or URL strings.
          - union
            - AssetInput: Media asset referenced by a post.
              - …
            - string, uri
        - `settings` object: Provider-specific settings from the publish settings API. Standalone Instagram supports destination/format plus per-media alt text and people tags, collaborators, Reel cover/thumbnail/feed/audio/Trial controls, AI disclosure, and location IDs. post_and_story requires one asset and creates two independent jobs.
        - `interaction_type` 'post' | 'reply' | 'comment' | 'null', nullable
        - `parent_step_id` string, nullable: Parent step id for reply/thread workflows.
  - `schedule` object: Optional wrapper. Routes accept either the envelope directly or { schedule: envelope }.

## Response `201`

Successful response.

- RunResponse: Run creation or detail response.
  - `ok` unknown, required
  - `duplicate` boolean: True when idempotency reused an existing run.
  - `mode` string, nullable: draft or scheduled.
  - `sourceModel` string, nullable: posts_v1 or campaigns_v2.
  - `run` Run: Publishing run.
    - `id` string, required: Run id.
    - `status` 'draft' | 'created' | 'processing' | 'completed' | 'partial_failed', required
    - `mode` string, nullable: draft or scheduled.
    - `source` string, nullable: api, dashboard, or system source.
    - `totalPosts` integer: Number of posts in the run.
    - `createdAt` string, date-time, nullable: Creation time.
    - `updatedAt` string, date-time, nullable: Last update time.
  - `posts` Post[]: Posts in the run.
    - `id` string, required: Post id.
    - `runId` string, nullable: Run id.
    - `provider` 'x' | 'threads' | 'meta' | 'facebook' | 'instagram_business' | 'instagram' | 'snapchat' | 'tiktok' | 'linkedin' | 'linkedin_page' | 'pinterest' | 'youtube' | 'reddit' | 'discord' | 'telegram' | 'wordpress', required
    - `account` string, required: Connected account handle.
    - `accountId` string, nullable: Connected account id.
    - `status` 'draft' | 'scheduled' | 'publishing' | 'published' | 'action_required' | 'retry_pending' | 'failed' | 'canceled', required
    - `name` string, nullable: Post name or title.
    - `description` string, nullable: Post body text.
    - `publishAtUtc` string, date-time, nullable: UTC publish time.
    - `providerPostId` string, nullable: Provider-side post id after publish.
    - `providerUrl` string, uri, nullable: Provider-side URL when available.
    - `error` string, nullable: Last error message.
    - `attempts` integer: Publish attempt count.
  - `summary` object, nullable

## Other responses

- `400`: Invalid request.
- `401`: Missing, invalid, or unauthorized credentials.
- `404`: Requested resource was not found.
- `422`: Request body or semantic validation failed.

---

[API](https://skmtc.dev/getsocialclaw/apis/socialclaw-api.md) · [All operations](https://skmtc.dev/getsocialclaw/apis/socialclaw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getsocialclaw/apis/socialclaw-api/revisions/a11a6a5b9bc6?raw)