Publications API

Plain-text docs ↗

Base URL

https://api.samsar.one/v1

Route prefix

/publications

Authentication

Bearer API key/auth token, or customer sub-account key

Execution

Synchronous publication controls

Billing

No additional charge for CRUD and archive

Content type

application/json

Use these endpoints when an external application needs to publish, edit, or revoke a public publication for a completed samsar-js video session. The authenticated account must own the target video session. A singular session needs its final video URL; a branched session needs every path render finalized.

Singular sessions create the existing single-video Publication. A finalized branched session creates an InteractivePublication instead. Interactive publication output contains only the public path videos, a first-frame thumbnail for every path, and the media-relative choice graph needed by an interactive player; it does not contain generation diagnostics or billing data.

Publication fields

Samsar infers the final video URL and many defaults from the session. Send the fields your app owns or cannot infer from the session:

{
  "session_id": "66ff...",
  "title": "Running shoe teaser",
  "description": "Launch-day vertical cut",
  "tags": ["launch", "footwear"],
  "creator_handle": "acme",
  "slug": "running-shoe-teaser",
  "image_hash": "optional-image-hash",
  "splash_image": "https://cdn.example.com/splash.png",
  "image_model": "GPTIMAGE2.5",
  "video_model": "RUNWAYML",
  "original_prompt": "A fast launch video for a new running shoe",
  "aspect_ratio": "9:16",
  "has_subtitles": true,
  "session_language": "en",
  "language_string": "English"
}

Alias support:

• session_id, sessionId, video_session_id, videoSessionId, or id
• aspect_ratio or aspectRatio
• creator_handle or creatorHandle
• image_hash or imageHash
• splash_image or splashImage
• image_model or imageModel
• video_model or videoModel
• original_prompt, originalPrompt, or prompt
• session_language, sessionLanguage, language, or language_code
• language_string or languageString
• has_subtitles, hasSubtitles, enable_subtitles, or enableSubtitles

Request bodies can be sent flat or nested under input.

POST /publications/publish

Create or update a public publication for a completed session.

curl -X POST https://api.samsar.one/v1/publications/publish \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "66ff...",
    "title": "Running shoe teaser",
    "description": "Launch-day vertical cut",
    "tags": ["launch", "footwear"],
    "creator_handle": "acme"
  }'

Success response:

{
  "created": true,
  "publication": {
    "publication_id": "67aa...",
    "session_id": "66ff...",
    "video_url": "https://static.samsar.one/video/66ff/final.mp4",
    "title": "Running shoe teaser",
    "description": "Launch-day vertical cut",
    "tags": ["launch", "footwear"],
    "creator_handle": "acme",
    "aspect_ratio": "9:16",
    "has_subtitles": true,
    "language": "en",
    "session_language": "en",
    "language_string": "English"
  },
  "session": {
    "session_id": "66ff...",
    "is_published": true,
    "published_publication_id": "67aa...",
    "published_video_url": "https://static.samsar.one/video/66ff/final.mp4"
  }
}

POST /publications/edit

Edit an existing publication for a session. Omitted fields keep their current publication values.

curl -X POST https://api.samsar.one/v1/publications/edit \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "66ff...",
    "title": "Running shoe teaser - updated",
    "tags": ["launch", "footwear", "campaign"]
  }'

404 is returned when the session exists but has no publication yet.

POST /publications/revoke

Remove a session publication from the public feed and clear the published fields on the session.

curl -X POST https://api.samsar.one/v1/publications/revoke \
  -H "Authorization: Bearer $SAMSAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "66ff..."
  }'

Success response:

{
  "revoked": true,
  "publication_id": "67aa...",
  "session": {
    "session_id": "66ff...",
    "is_published": false
  }
}

REST aliases

The same operations are also available as session-centric routes:

• POST /publications/session/:sessionId
• PATCH /publications/session/:sessionId
• DELETE /publications/session/:sessionId

Public interactive publication feed

These read routes are unauthenticated and free:

• GET https://api.samsar.one/interactive_publications
• GET https://api.samsar.one/interactive_publications/:publicationId
• Versioned aliases are available under /v1/interactive_publications.

The list supports limit (default 50, maximum 200) and an opaque cursor returned by the previous page:

curl "https://api.samsar.one/interactive_publications?limit=20"

{
  "items": [{
    "id": "67ab...",
    "type": "InteractiveVideo",
    "schema": "interactive_publication.v1",
    "title": "Fork in the road",
    "description": "Choose the hero's next move.",
    "tags": ["interactive", "adventure"],
    "creatorHandle": "acme",
    "datePublished": "2026-07-19T00:00:00.000Z",
    "thumbnailUrl": "https://static.samsar.one/published/66ff/interactive/revisions/8f4d.../paths/cm9vdC4x/thumbnail.png",
    "aspectRatio": "16:9",
    "inLanguage": "en",
    "hasSubtitles": true,
    "manifest": {
      "schema": "interactive_video_manifest.v1",
      "default_path_id": "root.1",
      "timing": {
        "origin": "media",
        "unit": "seconds"
      },
      "tree": {
        "root_node_id": "root",
        "choice_points": [{
          "branch_point_id": "choice-root",
          "parent_node_id": "root",
          "switch_at_seconds": 8,
          "options": [{
            "child_node_id": "root.1",
            "path_name": "Open the door",
            "path_description": "Continue through the doorway.",
            "leaf_path_ids": ["root.1"]
          }]
        }]
      },
      "outputs": {
        "paths": [{
          "path_id": "root.1",
          "contentUrl": "https://static.samsar.one/published/66ff/interactive/revisions/8f4d.../paths/cm9vdC4x/video.mp4",
          "thumbnailUrl": "https://static.samsar.one/published/66ff/interactive/revisions/8f4d.../paths/cm9vdC4x/thumbnail.png",
          "encodingFormat": "video/mp4",
          "duration": 24,
          "is_default": true
        }]
      }
    }
  }],
  "nextCursor": null,
  "hasMore": false,
  "totalCount": 1
}

The timing, tree, and outputs.paths layout follows the completed branched response from status_detailed, so clients can reuse the same choice-graph logic. contentUrl, thumbnailUrl, and encodingFormat use standard media-resource field names. duration and switch_at_seconds are media-relative seconds. A publication is withheld if any path video or thumbnail is unavailable publicly; clients never receive a partial choice graph.

Error responses

• 400 missing or invalid session_id
• 401 invalid API key, customer sub-account key, or auth token
• 403 the session does not belong to the authenticated actor
• 404 session or publication not found
• 409 the session has no final video URL yet

samsar-js

import SamsarClient from 'samsar-js';

const samsar = new SamsarClient({ apiKey: process.env.SAMSAR_API_KEY! });

await samsar.publishPublication({
  session_id: '66ff...',
  title: 'Running shoe teaser',
  tags: ['launch', 'footwear'],
});

await samsar.editPublication({
  session_id: '66ff...',
  title: 'Running shoe teaser - updated',
});

await samsar.revokePublication('66ff...');

const page = await samsar.listInteractivePublications({ limit: 20 });
const interactivePublication = await samsar.getInteractivePublication(page.data.items[0].id);