Agent API

Returns the authenticated agent context. No scope required.

Response

{
  "userId": "uuid",
  "key": {
    "id": "uuid",
    "name": "my-assistant",
    "prefix": "c3ak_live_abc",
    "scopes": ["content:read", "social:generate"]
  }
}

List content items owned by the authenticated user.

Query parameters

?type=video    # filter by content type
&limit=20      # max 100, default 20
&offset=0      # pagination offset

Response

{
  "items": [
    {
      "id": "uuid",
      "type": "video",
      "title": "Product Launch",
      "description": "...",
      "source_url": "https://...",
      "thumbnail_url": "https://...",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

List connected social media accounts.

Response

{
  "connections": [
    {
      "id": "uuid",
      "provider": "youtube",
      "provider_account_id": "UC...",
      "metadata": { "channel_name": "My Channel" },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Generate AI-written titles, descriptions, and hashtags for a content item.

Request body

{
  "contentItemId": "uuid",
  "platforms": ["youtube", "tiktok", "instagram"],
  "userPrompt": "Focus on the summer sale"  // optional
}

Response

{
  "youtube": {
    "title": "...",
    "description": "...",
    "hashtags": ["..."]
  },
  "tiktok": { ... },
  "instagram": { ... }
}

Create a draft social post for human review. Accepts two payload formats.

Request body (format A — canonical)

{
  "contentItemId": "uuid",
  "title": "Summer Sale Highlight",
  "description": "Check out our biggest sale...",
  "hashtags": ["#summer", "#sale"],
  "platforms": [
    {
      "connectionId": "uuid",
      "platformTitle": "Override title for this platform",
      "platformDescription": "Override description",
      "settings": {}
    }
  ]
}

Request body (format B — shorthand)

{
  "contentItemId": "uuid",
  "title": "Summer Sale Highlight",
  "caption": "Check out our biggest sale...",
  "hashtags": ["#summer", "#sale"],
  "platforms": ["tiktok", "youtube"],
  "connectionIds": ["uuid-1", "uuid-2"]
}

Both formats accepted. caption maps to description. Get connection IDs from GET /v1/social/connections.

Response

{
  "draft": {
    "id": "uuid",
    "status": "draft",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Publish a draft social post. Enqueues the post for publishing to all configured platforms. Only drafts with status "draft" can be published. Returns 422 if the post is not a draft or is missing content/platforms.

Response

{
  "postId": "uuid",
  "jobId": "uuid",
  "status": "pending"
}

List draft social posts.

Query parameters

?limit=20   # max 100, default 20
&offset=0   # pagination offset

Response

{
  "drafts": [
    {
      "id": "uuid",
      "title": "Summer Sale Highlight",
      "description": "...",
      "hashtags": ["#summer"],
      "status": "draft",
      "created_at": "2025-01-01T00:00:00Z",
      "content_items": {
        "id": "uuid",
        "title": "Product Launch",
        "type": "video"
      },
      "social_post_platforms": [
        {
          "id": "uuid",
          "status": "pending",
          "social_connections": {
            "id": "uuid",
            "provider": "youtube"
          }
        }
      ]
    }
  ]
}

Get available voices, content sources, and aspect ratios for video generation.

Response

{
  "agent": {
    "id": "short_form_content",
    "name": "Short-Form Content Agent",
    "description": "Create viral videos from Quora, Reddit, or AI-generated content"
  },
  "sourceOptions": [
    {
      "value": "quora",
      "label": "Quora Answer",
      "description": "...",
      "requiredField": "url"
    }
  ],
  "voiceOptions": [
    { "value": "Kore", "label": "Kore", "description": "..." }
  ],
  "aspectRatioOptions": [
    { "value": "9:16", "label": "9:16 (Vertical)" },
    { "value": "16:9", "label": "16:9 (Horizontal)" }
  ],
  "defaults": {
    "sourceType": "quora",
    "voiceId": "Kore",
    "aspectRatio": "9:16",
    "saveToLibrary": true
  }
}

Generate a short-form video. Returns a job ID for polling status.

Request body

{
  "source": {
    "type": "quora",       // quora | reddit | prompt | text
    "url": "https://..."   // required for quora/reddit
  },
  "voiceId": "Kore",       // optional, default "Kore"
  "aspectRatio": "9:16",   // optional, default "9:16"
  "saveToLibrary": true    // optional, default true
}

Response

{
  "success": true,
  "jobId": "uuid",
  "status": "queued",
  "taskName": "projects/.../tasks/..."
}

List render jobs with optional status and type filters.

Query parameters

?status=completed   # filter by job status
&job_type=slideshow # filter by job type
&agent_type=...     # filter by agent type
&limit=50           # max 100, default 50
&offset=0           # pagination offset

Response

{
  "jobs": [
    {
      "id": "uuid",
      "job_type": "slideshow",
      "agent_type": "short_form_content",
      "status": "completed",
      "payload": { ... },
      "pipeline_state": {
        "current_step": null,
        "completed_steps": ["generate", "render"],
        "intermediate_outputs": { ... }
      },
      "error_message": null,
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Get a specific render job by ID.

Response

{
  "job": {
    "id": "uuid",
    "job_type": "slideshow",
    "agent_type": "short_form_content",
    "status": "completed",
    "payload": { ... },
    "pipeline_state": { ... },
    "error_message": null,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-01-01T00:00:00Z"
  }
}

Create a review for human approval.

Request body

{
  "title": "Campaign video for summer sale",
  "contentType": "video",        // pdf | video | image | slides | markdown
  "attachments": [
    { "url": "https://...", "label": "Final cut", "order": 0 }
  ],
  "description": "Review the video before publishing",  // optional
  "metadata": {                                         // optional
    "tags": ["campaign"],
    "prompt": "Original generation prompt",
    "notes": "Extra context"
  }
}

Response

{
  "review": {
    "id": "uuid",
    "title": "Campaign video for summer sale",
    "contentType": "video",
    "status": "pending",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

List reviews with optional status filter.

Query parameters

?status=pending   # filter by review status
&limit=20         # max 100, default 20
&offset=0         # pagination offset

Response

{
  "reviews": [
    {
      "id": "uuid",
      "title": "Campaign video for summer sale",
      "description": "...",
      "contentType": "video",
      "attachments": [
        { "url": "https://...", "label": "Final cut", "order": 0 }
      ],
      "metadata": { ... },
      "status": "pending",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Get a review with its comments.

Response

{
  "review": {
    "id": "uuid",
    "title": "Campaign video for summer sale",
    "description": "...",
    "contentType": "video",
    "attachments": [ ... ],
    "metadata": { ... },
    "status": "pending",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "comments": [
    {
      "id": "uuid",
      "body": "Looks good, but adjust the intro",
      "authorType": "human",
      "agentKeyName": null,
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Add a comment to a review.

Request body

{
  "body": "Updated the intro section as requested"
}

Response

{
  "comment": {
    "id": "uuid",
    "body": "Updated the intro section as requested",
    "authorType": "agent",
    "agentKeyName": "my-assistant",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Update a review's status. Valid transitions: pending → in_review, in_review → approved / rejected / changes_requested, changes_requested → in_review.

Request body

{
  "status": "in_review"
}

Response

{
  "review": {
    "id": "uuid",
    "status": "in_review",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Submit a new revision with updated attachments. Automatically seeds the original as v1 if no revisions exist. Updates the review's attachments to the latest version.

Request body

{
  "attachments": [
    { "url": "https://...", "label": "Updated version" }
  ],
  "note": "Fixed the background color"  // optional
}

Response

{
  "revision": {
    "revisionNumber": 2,
    "note": "Fixed the background color",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

List all revisions for a review, ordered by revision number.

Response

{
  "revisions": [
    {
      "revisionNumber": 1,
      "attachments": [
        { "url": "https://...", "label": "Original" }
      ],
      "note": "Original",
      "agentKeyName": "my-assistant",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Generate a shareable public link for a review. Anyone with the link can view the content, change the review status, and leave comments without logging in. If a share link already exists, returns the existing link and enables it.

Response

{
  "shareToken": "base64url-token",
  "shareUrl": "https://content3.app/review/base64url-token",
  "shareEnabled": true
}

Promote an approved review to a content item. Idempotent — returns the existing content item if already promoted. Returns 422 if the review is not approved.

Request body (all fields optional)

{
  "title": "Override title",       // optional
  "description": "Override desc"   // optional
}

Response

{
  "contentItem": {
    "id": "uuid",
    "type": "video",
    "title": "Campaign video for summer sale",
    "sourceUrl": "https://...",
    "status": "ready",
    "reviewId": "uuid",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Toggle a share link on or off. When disabled, the public link shows a "not found" page.

Request body

{
  "enabled": false   // true to re-enable
}

Response

{
  "shareToken": "base64url-token",
  "shareUrl": "https://content3.app/review/base64url-token",
  "shareEnabled": false
}

Create a product.

Request body

{
  "name": "Summer Collection Hoodie",
  "description": "Lightweight hoodie for summer",
  "url": "https://shop.example.com/hoodie",  // optional
  "hooks": ["trending", "sale"]               // optional
}

Response

{
  "product": {
    "id": "uuid",
    "name": "Summer Collection Hoodie",
    "description": "Lightweight hoodie for summer",
    "url": "https://shop.example.com/hoodie",
    "hooks": ["trending", "sale"],
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

List products.

Query parameters

?limit=20   # max 100, default 20
&offset=0   # pagination offset

Response

{
  "products": [
    {
      "id": "uuid",
      "name": "Summer Collection Hoodie",
      "description": "Lightweight hoodie for summer",
      "url": "https://shop.example.com/hoodie",
      "hooks": ["trending", "sale"],
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ]
}

Draft-Review-Publish

Every post goes through human review before publishing.

Video Generation Flow

Generate a short-form video and route it through review.