Object Formats

Data structures returned by the Sign in with Klap (OAuth) endpoints. All timestamps are in ISO 8601 format (e.g., "2026-10-07T12:00:00.000Z"). Objects can gain new fields over time: ignore fields you don’t know.

Project Object

Represents one long video the user clipped, together with the clips Klap made from it. Returned by the project endpoints under /tasks.

Fields

• id (string): Unique identifier of the project (16 characters). Use it as {project_id}.
• status (string): Current status of the project ("processing", "ready", "error", "expired").
• error_code (string or null): Why the project failed, when status is "error". See Project Error Codes.
• name (string): Name of the project: the video’s title, or the name given when it was created.
• source_url (string): Link to the video the project was made from. For uploaded files, this is a temporary signed storage URL that grants access to the file: don’t display or share it.
• thumbnail_url (string or null): URL of a thumbnail image for the video, or null if none is available.
• created_at (string, ISO 8601 datetime): Timestamp when the project was created.
• estimated_ready_at (string, ISO 8601 datetime): When Klap expects the clips to be ready. It’s an estimate: keep polling if the project is still processing after this time.
• folder_id (string or null): Identifier of the project’s page in the Klap web app (the last part of url).
• url (string or null): Link to the project in the Klap web app.

Example

{
  "id": "Jx7kQp2LmN4vR8tA",
  "status": "ready",
  "error_code": null,
  "name": "My podcast ep. 12",
  "source_url": "https://www.youtube.com/watch?v=s2bVToRdY6A",
  "thumbnail_url": "https://img.youtube.com/vi/s2bVToRdY6A/hqdefault.jpg",
  "created_at": "2026-10-07T12:00:00.000Z",
  "estimated_ready_at": "2026-10-07T12:12:00.000Z",
  "folder_id": "aB3dE5fG",
  "url": "https://klap.app/spaces/aB3dE5fG"
}

Clip Object

Represents one short video generated from a project.

Fields

• id (string): Unique identifier of the clip (12 characters). Use it as {clip_id}.
• name (string): Title of the clip.
• virality_score (number or null): Predicted virality of the clip, from 0 to 100. Higher is better.
• virality_score_explanation (string or null): Explanation of the virality score.
• duration_seconds (integer): Length of the clip in seconds, rounded.
• width (integer): Width of the clip in pixels.
• height (integer): Height of the clip in pixels.
• thumbnail_url (string): URL of a thumbnail image of the clip. No authorization needed.
• embed_url (string): Link to a page that plays the clip.
• editor_url (string): Link that opens the clip in the Klap editor (the user must be signed in to Klap).
• created_at (string, ISO 8601 datetime): Timestamp when the clip was created.

Example

{
  "id": "hT4kq9ZpW2xe",
  "name": "Why most startups fail",
  "virality_score": 87,
  "virality_score_explanation": "Strong hook in the first seconds and a clear, quotable takeaway.",
  "duration_seconds": 42,
  "width": 1080,
  "height": 1920,
  "thumbnail_url": "https://api.klap.app/projects/hT4kq9ZpW2xe/thumbnail",
  "embed_url": "https://klap.app/embed/hT4kq9ZpW2xe",
  "editor_url": "https://klap.app/editor/hT4kq9ZpW2xe",
  "created_at": "2026-10-07T12:11:30.000Z"
}

Export Object

Represents a clip rendered to an MP4 file. Returned by Get Export.

Fields

• id (string): Unique identifier of the export (UUID).
• status (string): Current status of the export ("processing", "ready", "error").
• src_url (string or null): Public URL of the MP4 file. null until the export is ready. Anyone with the link can download the file.
• estimated_ready_at (string, ISO 8601 datetime): When Klap expects the export to be ready.
• project_id (string): ID of the exported clip (named project_id for historical reasons).
• created_at (string, ISO 8601 datetime): Timestamp when the export was started.
• finished_at (string, ISO 8601 datetime): Timestamp when the export finished. Not present until then.
• name (string): Name of the clip when it was exported.
• author_id (string): Klap ID of the user who owns the clip (the sub returned by the user info endpoint).
• folder_id (string or null): Identifier of the clip’s project page in the Klap web app (same as the Project Object’s folder_id).
• descriptions (any): Legacy field, usually null. Ignore it.
• scale (number): Render scale. Not present for default exports.
• watermarked (boolean): Whether the video carries a Klap watermark.

Example

{
  "id": "3f6c1a52-8d4e-4b7a-9c1e-2f5d8a7b6c90",
  "status": "ready",
  "src_url": "https://storage.googleapis.com/klap-renders/3f6c1a52-8d4e-4b7a-9c1e-2f5d8a7b6c90.mp4",
  "estimated_ready_at": "2026-10-07T12:20:42.000Z",
  "project_id": "hT4kq9ZpW2xe",
  "created_at": "2026-10-07T12:20:00.000Z",
  "finished_at": "2026-10-07T12:20:51.000Z",
  "name": "Why most startups fail",
  "author_id": "5f1c2e9a-3b7d-4c8e-9f60-2a1b3c4d5e6f",
  "folder_id": "aB3dE5fG",
  "descriptions": null,
  "watermarked": false
}

Social Account Object

Represents a social media account the user connected in Klap. Returned by List Social Accounts.

Fields

• id (string): The account’s ID on the platform. Use it as account_id when scheduling posts.
• provider (string): Platform of the account ("youtube", "tiktok", "instagram", "linkedin", "facebook").
• name (string): Display name of the account.
• username (string): Handle of the account.
• profile_picture (string): URL of the account’s profile picture. Can be empty.
• settings (object): Account preferences saved in Klap. Can be empty.
• needs_reconnect (boolean): true when the account lost its connection to the platform. The user must reconnect it at https://klap.app/calendar before you can post to it.

If Klap can’t reach the platform when listing accounts, name and username contain the account ID.

Example

{
  "id": "UCx8Zk2mQv7LpR4tN9wB1cDe",
  "provider": "youtube",
  "name": "Startup Stories",
  "username": "startupstories",
  "profile_picture": "https://yt3.ggpht.com/abc123",
  "settings": {},
  "needs_reconnect": false
}