> ## Documentation Index
> Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish Project

> Publish or schedule an exported project to one or more social platforms (YouTube, TikTok, Instagram) in a single call

# Publish Project

Publish or schedule an exported project to one or more connected social platforms (YouTube, TikTok, Instagram).

<Note>
  This endpoint requires authentication. The project must already be exported
  (have a `downloadUrl`), and the social accounts you want to publish to must be
  connected from the [Publishing](https://app.submagic.co/publishing) page in
  the dashboard.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Your Submagic API key starting with `sk-`
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier (UUID) of the exported project to publish
</ParamField>

## Request Body

<ParamField body="scheduledFor" type="string" optional>
  ISO 8601 timestamp to schedule the publication for a future time. Omit to
  publish immediately.
</ParamField>

<ParamField body="platforms" type="object" required>
  Per-platform publishing options. At least one platform must be provided.

  <Expandable title="Platforms" defaultOpen>
    <ParamField body="youtube" type="object" optional>
      YouTube publishing options

      <Expandable title="YouTube">
        <ParamField body="title" type="string" required>
          Video title (max 100 characters)
        </ParamField>

        <ParamField body="description" type="string" required>
          Video description
        </ParamField>

        <ParamField body="tags" type="array" optional>
          Array of tag strings
        </ParamField>

        <ParamField body="firstComment" type="string" optional>
          Pinned first comment to post under the video
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="tiktok" type="object" optional>
      TikTok publishing options

      <Expandable title="TikTok">
        <ParamField body="content" type="string" required>
          Caption / post content
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="instagram" type="object" optional>
      Instagram publishing options

      <Expandable title="Instagram">
        <ParamField body="format" type="string" required>
          Publishing format: `reel` or `story`
        </ParamField>

        <ParamField body="content" type="string" optional>
          Caption text. Required when `format` is `reel`.
        </ParamField>

        <ParamField body="firstComment" type="string" optional>
          Pinned first comment to post under the reel
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Prerequisites

Before publishing a project, ensure:

* **Project is exported**: The project must have a `downloadUrl` (status `completed`)
* **Project ownership**: The project must belong to the authenticated user
* **Accounts connected**: Each requested platform must be connected from the [Publishing](https://app.submagic.co/publishing) page in the dashboard
* **Sufficient credits**: Your account must have enough API credits

## Response

<ResponseField name="id" type="string">
  Unique identifier of the publication
</ResponseField>

<ResponseField name="projectId" type="string">
  The unique identifier of the project being published
</ResponseField>

<ResponseField name="scheduled" type="boolean">
  `true` if the publication was scheduled for a future time, `false` if
  published immediately
</ResponseField>

<ResponseField name="publishedAt" type="string">
  ISO 8601 timestamp of when the publication was published or is scheduled to
  publish
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the publication: `published`, `scheduled`, `processing`, or
  `failed`
</ResponseField>

<ResponseField name="platforms" type="array">
  Array of platforms the project is being published to
</ResponseField>

<RequestExample>
  ```bash cURL - Publish Now theme={null}
  curl -X POST "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000/publish" \
    -H "x-api-key: sk-your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "platforms": {
        "youtube": {
          "title": "How I Doubled My Revenue in 30 Days",
          "description": "In this video I break down the exact playbook I used.",
          "tags": ["business", "marketing", "growth"],
          "firstComment": "Drop a comment if this was helpful!"
        },
        "tiktok": {
          "content": "The exact playbook I used to double my revenue 🚀 #business #marketing"
        }
      }
    }'
  ```

  ```bash cURL - Schedule for Later theme={null}
  curl -X POST "https://api.submagic.co/v1/projects/550e8400-e29b-41d4-a716-446655440000/publish" \
    -H "x-api-key: sk-your-api-key-here" \
    -H "Content-Type: application/json" \
    -d '{
      "scheduledFor": "2026-05-01T15:00:00Z",
      "platforms": {
        "instagram": {
          "format": "reel",
          "content": "New video out now ✨",
          "firstComment": "Tap the link in bio for the full episode!"
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const publishProject = async (projectId, payload) => {
    const response = await fetch(
      `https://api.submagic.co/v1/projects/${projectId}/publish`,
      {
        method: "POST",
        headers: {
          "x-api-key": "sk-your-api-key-here",
          "Content-Type": "application/json",
        },
        body: JSON.stringify(payload),
      }
    );

    const result = await response.json();
    console.log("Publication:", result.id, result.status);
    return result;
  };

  // Publish to YouTube and TikTok now
  const result = await publishProject("550e8400-e29b-41d4-a716-446655440000", {
    platforms: {
      youtube: {
        title: "How I Doubled My Revenue in 30 Days",
        description: "In this video I break down the exact playbook I used.",
        tags: ["business", "marketing", "growth"],
      },
      tiktok: {
        content: "The exact playbook I used to double my revenue 🚀",
      },
    },
  });
  ```

  ```python Python theme={null}
  import requests

  def publish_project(project_id, payload):
      url = f'https://api.submagic.co/v1/projects/{project_id}/publish'
      headers = {
          'x-api-key': 'sk-your-api-key-here',
          'Content-Type': 'application/json'
      }

      response = requests.post(url, headers=headers, json=payload)
      result = response.json()

      print(f"Publication: {result.get('id')} - {result.get('status')}")
      return result

  # Schedule a reel on Instagram
  payload = {
      'scheduledFor': '2026-05-01T15:00:00Z',
      'platforms': {
          'instagram': {
              'format': 'reel',
              'content': 'New video out now ✨',
              'firstComment': 'Tap the link in bio for the full episode!'
          }
      }
  }

  result = publish_project(
      '550e8400-e29b-41d4-a716-446655440000',
      payload
  )
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK - Published Now theme={null}
  {
    "id": "pub_8f3b4c2e-1a9d-4e5f-9b7c-2a4d6e8f1c3b",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "scheduled": false,
    "publishedAt": "2026-04-28T12:34:56.000Z",
    "status": "published",
    "platforms": ["youtube", "tiktok"]
  }
  ```

  ```json 202 Accepted - Scheduled theme={null}
  {
    "id": "pub_8f3b4c2e-1a9d-4e5f-9b7c-2a4d6e8f1c3b",
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "scheduled": true,
    "publishedAt": "2026-05-01T15:00:00.000Z",
    "status": "scheduled",
    "platforms": ["instagram"]
  }
  ```

  ```json 400 BAD_REQUEST - Project Not Exported theme={null}
  {
    "error": "BAD_REQUEST",
    "message": "Project must be exported before it can be published"
  }
  ```

  ```json 402 PAYMENT_REQUIRED - Insufficient Credits theme={null}
  {
    "error": "PAYMENT_REQUIRED",
    "message": "Insufficient API credits to publish"
  }
  ```

  ```json 403 FORBIDDEN - Plan Restriction theme={null}
  {
    "error": "FORBIDDEN",
    "message": "Your plan does not allow publishing via the API"
  }
  ```

  ```json 404 NOT_FOUND - Project Not Found theme={null}
  {
    "error": "NOT_FOUND",
    "message": "Project doesn't exist or doesn't belong to user"
  }
  ```

  ```json 412 PRECONDITION_FAILED - Account Not Connected theme={null}
  {
    "error": "PRECONDITION_FAILED",
    "message": "Some platform accounts are not connected"
  }
  ```
</ResponseExample>

## Tracking Published Posts

After publishing, use the [List Published Projects](/api-reference/list-published-projects)
endpoint to retrieve the status, platform URLs, and analytics of your posts.

<Note>
  **Tip**: To connect a YouTube, TikTok, or Instagram account, visit the
  [Publishing](https://app.submagic.co/publishing) page in the dashboard. Once
  connected, the account is available to all publish requests for that user.
</Note>

<Warning>
  **Important**: Publication to upstream platforms is asynchronous. A `200`
  response means the request was accepted and posts have been dispatched, but
  individual platform delivery (especially for scheduled posts) is finalized in
  the background. Poll the [List Published Projects](/api-reference/list-published-projects)
  endpoint to track per-platform `publishStatus`.
</Warning>