Skip to main content
The Publishing API lets you publish completed video projects to one or more social media platforms. You can publish immediately or schedule posts for the future. Both endpoints require the publish permission.

​
Publish Video

​
POST /api/v1/publish
endpoint
Publish or schedule a completed video project to social media platforms.

​
Authentication

​
Authorization
string
required
Your Nouvel API key with publish permission. Format: Bearer nvl_xxxx

​
Request Body

​
projectId
string
required
UUID of the project to publish. The project must:
  • Belong to the authenticated user
  • Have status: "completed"
  • Have a final_output_url (generated video)
​
platforms
array
required
Array of platform targets. At least one is required.
​
scheduledAt
string
ISO 8601 datetime to schedule the post for. Must be in the future. If omitted, the post is published immediately.
"2026-02-01T12:00:00Z"

​
Example Requests

curl -X POST https://app.nouvel.ai/api/v1/publish \
  -H "Authorization: Bearer nvl_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "550e8400-e29b-41d4-a716-446655440000",
    "platforms": [
      {
        "platform": "instagram",
        "accountId": "6612f1a2b3c4d5e6f7890123",
        "caption": "Check out our new protein powder! 💪"
      },
      {
        "platform": "tiktok",
        "accountId": "6612f1a2b3c4d5e6f7890456",
        "caption": "This changed my morning routine #fitness #protein"
      }
    ]
  }'

​
Response

{
  "postId": "6612f1a2b3c4d5e6f7891234",
  "status": "publishing",
  "platforms": [
    { "platform": "instagram", "status": "pending" },
    { "platform": "tiktok", "status": "pending" }
  ]
}
​
postId
string
required
Unique identifier for the publish request. Use this to check status via GET /api/v1/publish/:postId.
​
status
string
required
Overall post status. "publishing" for immediate publishes, "scheduled" for future-scheduled posts.
​
platforms
array
required
Per-platform status. Each entry shows the current publishing status for that platform target.

​
Error Codes

CodeDescription
400Missing required fields, invalid JSON, or invalid scheduledAt
401Invalid or missing API key
402Plan doesn’t include API access
403API key missing publish permission, or account doesn’t belong to your org
404Project not found or no organization found
422Project not completed or has no video output
500Publishing provider error

​
Platform-Specific Notes

Requires platformSettings.boardId — a numeric board ID (not a slug). You can find board IDs in the Nouvel dashboard when configuring Pinterest publishing.
{
  "platform": "pinterest",
  "accountId": "...",
  "caption": "Pin description",
  "platformSettings": {
    "boardId": "1119777963540158867"
  }
}
Requires platformSettings.title (max 300 characters) and platformSettings.subreddit. Video posts are published as link posts (Reddit API limitation).
{
  "platform": "reddit",
  "accountId": "...",
  "platformSettings": {
    "title": "Check out this amazing protein powder",
    "subreddit": "supplements"
  }
}
Optionally accepts platformSettings.title and platformSettings.description for the video metadata.
{
  "platform": "youtube",
  "accountId": "...",
  "platformSettings": {
    "title": "Best Protein Powder Review 2026",
    "description": "Full review of the best protein powders..."
  }
}

​
Check Publish Status

​
GET /api/v1/publish/:postId
endpoint
Check the status of a previously submitted publish request.

​
Path Parameters

​
postId
string
required
The postId returned from POST /api/v1/publish.

​
Example

curl https://app.nouvel.ai/api/v1/publish/6612f1a2b3c4d5e6f7891234 \
  -H "Authorization: Bearer nvl_xxxx"

​
Response

{
  "postId": "6612f1a2b3c4d5e6f7891234",
  "status": "published",
  "platforms": [
    {
      "platform": "instagram",
      "status": "published",
      "platformPostUrl": "https://instagram.com/p/ABC123",
      "error": null
    },
    {
      "platform": "tiktok",
      "status": "failed",
      "platformPostUrl": null,
      "error": "Video format not supported"
    }
  ]
}
​
platforms[].status
string
required
Per-platform status. One of: pending, publishing, published, failed, scheduled.
​
platforms[].platformPostUrl
string
URL to the published post on the social platform. Only present when status is published.
​
platforms[].error
string
Error message if the publish failed for this platform. null on success.

​
Error Codes

CodeDescription
401Invalid or missing API key
403API key missing publish permission
404Post not found