REST API v1

Returns the team the key belongs to, the plan, the credit balance, this period’s plan-quota usage, the default workspace and the scopes the key carries. This is the only endpoint that requires no scope, which makes it the right health check: a key that cannot call it is not a key.

• The key itself is never returned. Only its public id, its name and its scopes.
• usage.metrics carries one row per metered plan line, whether or not it has moved this period, so four meters can be rendered on the first day of the month. limit and remaining are both null on a plan where the line is unlimited: render the word rather than a number that means it. These are the same counters that answer 429 usage_limit_reached, and remaining is measured against the same ceiling that refusal is checked against.

curl "https://looptake.com/api/v1/me" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "team": {
      "id": "e7293116-fd57-4456-8da0-032f4976145f",
      "name": "Northwind Labs",
      "plan": "creator"
    },
    "credits": {
      "balance": 268,
      "grantedThisPeriod": 300,
      "periodEnd": "2026-09-01T00:00:00Z"
    },
    "usage": {
      "periodStart": "2026-08-01",
      "metrics": [
        {
          "metric": "turbo_posts",
          "used": 291,
          "limit": 300,
          "remaining": 9
        },
        {
          "metric": "content_pieces",
          "used": 12,
          "limit": 60,
          "remaining": 48
        },
        {
          "metric": "automations",
          "used": 1,
          "limit": 5,
          "remaining": 4
        },
        {
          "metric": "generations",
          "used": 140,
          "limit": 300,
          "remaining": 160
        }
      ]
    },
    "defaultWorkspace": {
      "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
      "name": "Northwind",
      "websiteUrl": "https://northwind.example"
    },
    "key": {
      "id": "d81ed241-9404-4a1a-8864-242ecc540416",
      "name": "CI publisher",
      "scopes": [
        "generations:read",
        "generations:write",
        "posts:read",
        "posts:write"
      ],
      "createdAt": "2026-07-02T09:14:00Z",
      "lastUsedAt": "2026-08-12T11:02:41Z"
    }
  }
}

The balance is the team’s, not the workspace’s, because credits are billed at the team level. The ledger is every movement in signed units: a grant is positive, a spend is negative, and a refund for a failed generation is a positive entry that names the job it reverses.

• Newest first. The ledger is append-only; an entry is never edited or removed.
• `model` is reserved for the model that produced the media. It is null on every row until a media provider reports one, so do not build cost attribution on it yet.

curl "https://looptake.com/api/v1/credits?type=refund&limit=2" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "balance": 268,
    "ledger": [
      {
        "id": "f4451e86-4d4f-409f-aefb-02e1ca406365",
        "credits": 10,
        "type": "refund",
        "spendingType": "studio_render",
        "model": null,
        "refId": "c02119cb-ed7a-40ed-87fe-c18edc1fa1a2",
        "createdAt": "2026-08-11T18:22:07Z"
      },
      {
        "id": "87d5ca77-433e-4ffc-870a-b33e3c2d4c76",
        "credits": 30,
        "type": "refund",
        "spendingType": "influencer_video_per_second",
        "model": null,
        "refId": "08363fcd-f524-4126-b68d-fd64f2f9c09e",
        "createdAt": "2026-08-04T07:41:55Z"
      }
    ]
  },
  "pagination": {
    "total": 6,
    "page": 1,
    "limit": 2,
    "pages": 3
  }
}

One entry per brand, **archived ones included**, live first. `archivedAt` is null on a workspace that still accepts work and an instant on one that does not. An archived workspace is listed because its id is what `POST /workspaces/{id}/restore` needs. `brandRefreshedAt` is when the site was last crawled and the brand context rebuilt; a null means the workspace has a URL but has not been analysed yet.

• Ordered live first, then the default, then oldest first. A key pinned to one workspace sees only that one, archived or not.

curl "https://looptake.com/api/v1/workspaces" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
      "name": "Northwind",
      "websiteUrl": "https://northwind.example",
      "logoUrl": "https://cdn.looptake.com/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/logo.png",
      "isDefault": true,
      "archivedAt": null,
      "brandRefreshedAt": "2026-08-09T06:00:12Z",
      "createdAt": "2026-07-01T13:55:00Z"
    },
    {
      "id": "d0e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f",
      "name": "Northwind Trade",
      "websiteUrl": null,
      "logoUrl": null,
      "isDefault": false,
      "archivedAt": "2026-08-10T09:12:44Z",
      "brandRefreshedAt": null,
      "createdAt": "2026-07-14T08:30:00Z"
    }
  ]
}

Creating a workspace with a `websiteUrl` queues the first crawl, so the brand context is being built by the time the response arrives. The plan caps how many workspaces a team may hold; the cap is a `429 usage_limit_reached`, not a 400.

• The cap counts live workspaces only, so archiving one frees its slot and restoring one needs a free slot.

curl -X POST "https://looptake.com/api/v1/workspaces" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Northwind",
  "websiteUrl": "https://northwind.example"
}'

{
  "success": true,
  "data": {
    "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "name": "Northwind",
    "websiteUrl": "https://northwind.example",
    "logoUrl": null,
    "isDefault": false,
    "archivedAt": null,
    "brandRefreshedAt": null,
    "createdAt": "2026-08-12T11:04:20Z"
  }
}

The brand context is what every generation is written from: identity, audience, tone, value propositions, content angles, keywords, competitors and palette. Each extracted claim carries the source URL it was read from, so nothing in it is unattributable. An archived workspace answers `200` here with `archivedAt` set, because the read is what a restore starts from.

curl "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "name": "Northwind",
    "websiteUrl": "https://northwind.example",
    "isDefault": true,
    "archivedAt": null,
    "brandContext": {
      "identity": "Inventory forecasting for independent retailers.",
      "audience": "Owner-operators running one to five shops.",
      "tone": "Direct, numerate, no jargon.",
      "valueProps": [
        "Stops dead stock",
        "Reorders before the shelf empties"
      ],
      "contentAngles": [
        "The cost of one stockout",
        "What a good reorder point looks like"
      ],
      "keywords": [
        "inventory forecasting",
        "reorder point",
        "dead stock"
      ],
      "competitors": [
        "Inventory Planner"
      ],
      "palette": [
        "#0b3d2e",
        "#f4f1ea"
      ],
      "sourceUrl": "https://northwind.example",
      "refreshedAt": "2026-08-09T06:00:12Z"
    }
  }
}

Every field is optional and a field you leave out is left alone, so renaming a brand does not clear its logo. Send `websiteUrl: null` or `logoUrl: null` to clear one; `name`, `slug` and `timezone` cannot be cleared, because the columns behind them are not nullable. Changing `websiteUrl` does **not** re-read the site. The brand context is derived by `POST /brand/analyze`, and pointing at a new address without asking for a crawl would leave the two disagreeing silently. `timezone` is the one to get right early: it is `UTC` until you set it, and it is what an automation’s posting times are interpreted in. Sending an empty body is `invalid_input` rather than a 200 that changed nothing.

• Changing `websiteUrl` leaves the brand context alone. Call POST /brand/analyze afterwards to read the new site.

curl -X PATCH "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Northwind Supply",
  "timezone": "Europe/Lisbon"
}'

{
  "success": true,
  "data": {
    "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "name": "Northwind Supply",
    "websiteUrl": "https://northwind.example",
    "logoUrl": null,
    "isDefault": true,
    "archivedAt": null,
    "brandRefreshedAt": "2026-08-12T09:00:00Z",
    "createdAt": "2026-07-01T09:00:00Z"
  }
}

Stops a brand without losing it. Nothing inside is cancelled: posts keep their slots, automations keep their status, connected accounts stay connected. What changes is that a scheduled post is **withheld** at its slot rather than published, and a launched automation refuses to schedule its next run. Both are checked at the moment the work would run, so a post already going out is not interrupted. The answer carries the two counts that stops, and restoring puts the withheld work back. See `POST /workspaces/{id}/restore` for how each half resumes.

• Archiving the team’s default workspace is `409` while any other workspace is still active: choose the new default with POST /workspaces/{id}/default first, because promoting one for you would silently repoint every request that omits `workspaceId`.
• Archiving the last active workspace is allowed. The team then has no default, and every call that omits `workspaceId` answers `400 invalid_input` until one is set or named.
• A workspace that is already archived is `409`. Archiving frees the plan’s workspace slot.
• While it is archived, every call that would schedule work or spend credits in it answers `409 conflict`: POST /posts, POST /content/{format}, POST /influencers, POST /influencers/{id}/videos, POST /automations and POST /automations/{id}/launch. Reads, cancellations, DELETE /posts/{id}, DELETE /influencers/{id} and suggestion generation are unaffected; a guard that blocked stopping things would trap you in the state you were leaving.

curl -X POST "https://looptake.com/api/v1/workspaces/d0e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f/archive" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "d0e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "name": "Northwind Trade",
    "isDefault": false,
    "archivedAt": "2026-08-10T09:12:44Z",
    "withheldPosts": 12,
    "withheldAutomations": 1
  }
}

Un-archives a brand. Every post that was withheld and whose slot passed while the workspace was archived is put back on the publish queue by this call: a withheld publish is a job that already ran, so clearing the flag alone would leave those posts in the calendar with nothing to publish them, while a post whose slot is still ahead keeps the job it already had. It does **not** become the default again, because the team may have chosen another one in the meantime, so that is a separate call.

• A workspace that is not archived is `409`.
• Restoring into a full plan is `429 usage_limit_reached`: archiving freed the slot, so restoring needs one back.
• An automation whose launch was refused while the brand was archived is resumed by calling POST /automations/{id}/launch again, which accepts a launched run that scheduled nothing. It is a second call rather than part of this one because a launch carries the sandbox setting of the credential that made it, and nothing records that for a launch that never ran.

curl -X POST "https://looptake.com/api/v1/workspaces/d0e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f/restore" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "d0e2f3a4-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "name": "Northwind Trade",
    "isDefault": false,
    "archivedAt": null,
    "withheldPosts": 0,
    "withheldAutomations": 0
  }
}

Points every request that omits `workspaceId` at this workspace, clearing whatever held it. One default per team, and an archived workspace cannot hold it.

• A key pinned to one workspace is refused with `403 forbidden_scope`, whatever scopes it carries. The default is team-wide, so honouring it would let a key that can read one brand redirect every other credential’s unqualified traffic into it.
• An archived workspace is `409`. Restore it first.

curl -X POST "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/default" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "name": "Northwind",
    "isDefault": true,
    "archivedAt": null,
    "withheldPosts": 0,
    "withheldAutomations": 0
  }
}

The look every render in this workspace gets: caption colours, font and position, the logo, an outro card, a watermark and the voice. A workspace with no kit answers the defaults, with `null` colours and `updatedAt: null`.

curl "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/brand-kit" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "logoAssetId": "a3c1e2d4-5f60-4718-8a9b-0c1d2e3f4a5b",
    "primaryColor": "#ff0066",
    "secondaryColor": "#1a1a1a",
    "textColor": "#ffffff",
    "font": "body",
    "captions": {
      "preset": "karaoke",
      "fill": "#ffffff",
      "stroke": "#000000",
      "highlight": "#ff0066",
      "position": "bottom"
    },
    "voiceId": "narrator-1",
    "outro": {
      "text": "Follow @northwind",
      "logo": true
    },
    "watermark": true,
    "updatedAt": "2026-08-12T09:00:00Z"
  }
}

A field you leave out keeps its value and `null` clears it. The kit applies to renders that start after the change. `logoAssetId` must name an image asset (PNG) in this workspace. `font` is `display`, `body` or `mono`. `captions.position` is `top`, `middle` or `bottom`. Colours are `#rrggbb`.

• A colour that is not `#rrggbb`, an unknown font or a logo from another workspace is `400 invalid_input`.

curl -X PATCH "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/brand-kit" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "primaryColor": "#ff0066",
  "captions": {
    "highlight": "#ff0066"
  },
  "watermark": true
}'

{
  "success": true,
  "data": {
    "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "logoAssetId": "a3c1e2d4-5f60-4718-8a9b-0c1d2e3f4a5b",
    "primaryColor": "#ff0066",
    "secondaryColor": "#1a1a1a",
    "textColor": "#ffffff",
    "font": "body",
    "captions": {
      "preset": "karaoke",
      "fill": "#ffffff",
      "stroke": "#000000",
      "highlight": "#ff0066",
      "position": "bottom"
    },
    "voiceId": "narrator-1",
    "outro": {
      "text": "Follow @northwind",
      "logo": true
    },
    "watermark": true,
    "updatedAt": "2026-08-12T09:00:00Z"
  }
}

Removes the kit, so later renders use the house look.

curl -X DELETE "https://looptake.com/api/v1/workspaces/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/brand-kit" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "removed": true
  }
}

The ids returned here are the ids `selectedAccounts` takes on a post or an automation. `status` is worth checking before a scheduled run: an `expired` token fails at publish time, and a post scheduled against one will report a per-target failure rather than being rejected up front.

curl "https://looptake.com/api/v1/accounts?platform=tiktok" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "ff9d429b-07c5-4320-a98c-ac6e1791b828",
      "platform": "tiktok",
      "handle": "@northwind",
      "displayName": "Northwind",
      "avatarUrl": "https://cdn.looptake.com/ff9d429b-07c5-4320-a98c-ac6e1791b828/avatar.jpg",
      "ownerType": "brand",
      "influencerId": null,
      "scopes": [
        "video.publish",
        "user.info.basic"
      ],
      "status": "connected",
      "expiresAt": "2026-10-02T00:00:00Z"
    }
  ]
}

Synchronous: the response carries the finished suggestions, each with its on-screen caption, platform body, hashtags, hook score, the angle it came from and, for a Turbo format, the deck that renders it. Generating costs no credits on any plan, which is why this is the one endpoint with a tight rate limit rather than a price.

• The deck is omitted from the list shape and returned in full by GET /generations/{id}.
• Ten requests per 300 seconds per key. A batch of ten counts as one request.
• Every suggestion carries a brand-safety `review`: `pass`, `flagged`, or `withheld`. A withheld suggestion is returned with the phrase that caused it and cannot be accepted. The batch is never shortened, so `count` suggestions come back whatever the review found.

curl -X POST "https://looptake.com/api/v1/generations" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "count": 2,
  "format": "walloftext"
}'

{
  "success": true,
  "data": [
    {
      "id": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
      "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
      "format": "walloftext",
      "caption": "One stockout costs more than a year of forecasting",
      "postCaption": "The maths nobody runs before they run out.",
      "hashtags": [
        "#retail",
        "#inventory",
        "#smallbusiness"
      ],
      "why": "The pricing objection, answered with the cost of the alternative.",
      "angle": "The cost of one stockout",
      "score": 78,
      "status": "pending",
      "review": {
        "verdict": "pass",
        "findings": []
      },
      "createdAt": "2026-08-12T11:05:02Z"
    },
    {
      "id": "be40861b-3bd3-4b0a-b35f-1aa8835e78eb",
      "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
      "format": "walloftext",
      "caption": "Your reorder point is a guess. Here is the number.",
      "postCaption": "Three inputs, one number, no spreadsheet.",
      "hashtags": [
        "#inventory",
        "#retailtips"
      ],
      "why": "Teaches the concept the product automates.",
      "angle": "What a good reorder point looks like",
      "score": 71,
      "status": "pending",
      "review": {
        "verdict": "withheld",
        "findings": [
          {
            "rule": "unsupported_claim",
            "severity": "withhold",
            "origin": "rule",
            "quote": "Your reorder point is a guess. Here is the number.",
            "detail": "`guaranteed` asserts something about the product that nothing in the brand context says"
          }
        ]
      },
      "createdAt": "2026-08-12T11:05:02Z"
    }
  ]
}

No brand profile needed. The agent writes a brief, scores hook candidates, writes the script, picks the format, adds an AI still and voice, times the captions and renders 9:16. Returns at once; poll GET /videos/{id}. Text-only videos are free. A still costs 3 credits and voice 1 credit per 15 seconds; unused credits come back when the video is done, and all of them on failure.

• Studio formats such as talking heads use POST /content/{kind}.
• If the team cannot cover the still and no voice is asked for, the video is made without the still and costs nothing.

curl -X POST "https://looptake.com/api/v1/videos" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "prompt": "Three mistakes new runners make, and the fix for each",
  "length": "30s"
}'

{
  "success": true,
  "data": {
    "id": "3f2b8f4e-6a51-4c55-9d0b-5c0f1b7e2a10",
    "workspaceId": "91e14cbf-2c80-4b3b-a6bf-776bbde6b54c",
    "prompt": "Three mistakes new runners make, and the fix for each",
    "length": "30s",
    "format": null,
    "status": "queued",
    "stage": "hook",
    "stages": [
      "hook",
      "script",
      "visuals",
      "voice",
      "captions",
      "music",
      "render"
    ],
    "progress": 0,
    "viralScore": null,
    "hooks": [],
    "outputs": [],
    "creditsReserved": 3,
    "creditsSpent": 0,
    "statusUrl": "https://looptake.com/api/v1/videos/3f2b8f4e-6a51-4c55-9d0b-5c0f1b7e2a10"
  }
}

Give a TikTok, YouTube or Instagram link. We read its public title, caption and author (oEmbed, or the page tags), the agent extracts the structure (hook pattern, beats, pacing, format, on-screen text) and writes a new video on your topic with the same shape, through the same pipeline as POST /videos. The source video is never downloaded or reused. With no `topic`, the workspace brand is the topic. Poll GET /videos/{id}; `source.structure` shows what was copied. Costs as POST /videos.

curl -X POST "https://looptake.com/api/v1/remix" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "url": "https://www.tiktok.com/@runcoach/video/7412345678901234567",
  "topic": "Meal prep for night-shift nurses"
}'

{
  "success": true,
  "data": {
    "id": "5c1d7a0e-1f2b-4c3d-8e9f-0a1b2c3d4e5f",
    "kind": "remix",
    "prompt": "Meal prep for night-shift nurses",
    "source": {
      "url": "https://www.tiktok.com/@runcoach/video/7412345678901234567",
      "platform": "tiktok",
      "topic": "Meal prep for night-shift nurses"
    },
    "status": "queued",
    "stage": "hook",
    "progress": 0,
    "creditsReserved": 3,
    "statusUrl": "https://looptake.com/api/v1/videos/5c1d7a0e-1f2b-4c3d-8e9f-0a1b2c3d4e5f"
  }
}

Send a video asset or a public media URL. The worker fetches it, transcribes it with timestamps, the agent picks the best self-contained moments (strong hook, clear payoff, 15 to 60 seconds), and each one is cut, reframed to 9:16 (centre crop over a blurred fill) and given word-timed captions in your brand kit style. Each clip is a content item with a viral score. Costs 1 credit per started minute of source: the known length is reserved, or up to 60 minutes when it is not known, and the rest comes back. Poll GET /videos/{id}.

• Each output carries `startMs`, `endMs`, `title`, `hook`, `viralScore`, `contentId` and `previewUrl`.
• A source longer than the reservation fails and every credit comes back.

curl -X POST "https://looptake.com/api/v1/clips" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "mediaUrl": "https://cdn.example.com/podcast-ep-12.mp4",
  "count": 5
}'

{
  "success": true,
  "data": {
    "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
    "kind": "clip",
    "prompt": "Clips from podcast-ep-12.mp4",
    "count": 5,
    "status": "queued",
    "stage": "ingest",
    "stages": [
      "ingest",
      "transcribe",
      "select",
      "cut"
    ],
    "progress": 0,
    "creditsReserved": 60,
    "statusUrl": "https://looptake.com/api/v1/videos/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
  }
}

Send JSON `{ csv }` or `{ rows }`, a `text/csv` body, or a multipart form with a `file` field. Columns: `prompt` (required), `length`, `format`, `schedule_at`, `accounts`, `voice`, `language`, `made_for_kids`. Every row is checked first; one bad row creates nothing and the 400 names every bad row and line. A row with `schedule_at` and `accounts` (account ids or platform names) is scheduled to post when its video is ready; YouTube needs `made_for_kids`. Poll GET /videos/bulk/{id}. Each row costs as POST /videos.

curl -X POST "https://looptake.com/api/v1/videos/bulk" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "csv": "prompt,length,schedule_at,accounts\n\"Three tips for new runners\",30s,2026-11-02T09:00:00Z,tiktok\n"
}'

{
  "success": true,
  "data": {
    "batchId": "2b4c6d8e-0f1a-4b3c-9d5e-7f8a9b0c1d2e",
    "total": 1,
    "queued": 1,
    "running": 0,
    "ready": 0,
    "failed": 0,
    "progress": 0,
    "done": false,
    "statusUrl": "https://looptake.com/api/v1/videos/bulk/2b4c6d8e-0f1a-4b3c-9d5e-7f8a9b0c1d2e",
    "videos": [
      {
        "id": "6e5d4c3b-2a19-4807-b6f5-e4d3c2b1a090",
        "prompt": "Three tips for new runners",
        "status": "queued",
        "stage": "hook",
        "progress": 0,
        "scheduleAt": "2026-11-02T09:00:00Z"
      }
    ]
  }
}

Counts by status, the average `progress`, `done` once every row is `ready` or `failed`, and each row’s status and outputs.

curl "https://looptake.com/api/v1/videos/bulk/2b4c6d8e-0f1a-4b3c-9d5e-7f8a9b0c1d2e" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "batchId": "2b4c6d8e-0f1a-4b3c-9d5e-7f8a9b0c1d2e",
    "total": 2,
    "queued": 0,
    "running": 1,
    "ready": 1,
    "failed": 0,
    "progress": 70,
    "done": false,
    "videos": []
  }
}

Suggestions owned by an automation are excluded, because an automation holds hundreds and they belong to its review queue rather than to yours. Read those through GET /automations/{id}/posts instead.

curl "https://looptake.com/api/v1/generations?status=pending&limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
      "format": "walloftext",
      "caption": "One stockout costs more than a year of forecasting",
      "hashtags": [
        "#retail",
        "#inventory"
      ],
      "score": 78,
      "status": "pending",
      "reviewVerdict": "pass",
      "automationId": null,
      "createdAt": "2026-08-12T11:05:02Z"
    }
  ],
  "pagination": {
    "total": 34,
    "page": 1,
    "limit": 1,
    "pages": 34
  }
}

Adds the three things the list shape omits: the rationale, the deck, and the brand-safety review in full. The deck is the render blueprint: normalised geometry, slides, text boxes, transitions and captions. It is editable, and an edited deck sent to POST /posts renders exactly what you sent. The review carries one finding per problem, each with the phrase it is about; the list shape carries only `reviewVerdict`.

curl "https://looptake.com/api/v1/generations/6522d1ec-2c11-4d3a-b078-6f6cfe9f217b" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
    "format": "walloftext",
    "caption": "One stockout costs more than a year of forecasting",
    "postCaption": "The maths nobody runs before they run out.",
    "hashtags": [
      "#retail",
      "#inventory",
      "#smallbusiness"
    ],
    "why": "The pricing objection, answered with the cost of the alternative.",
    "angle": "The cost of one stockout",
    "score": 78,
    "status": "pending",
    "review": {
      "verdict": "pass",
      "findings": []
    },
    "deck": {
      "version": 1,
      "ratio": "9:16",
      "durationMs": 8000,
      "fps": 30,
      "background": {
        "kind": "clip",
        "src": "a7273471-d932-4f9a-958e-79abdd1f3fd7"
      },
      "slides": [
        {
          "startMs": 0,
          "endMs": 8000,
          "boxes": [
            {
              "id": "hook",
              "text": "One stockout costs more than a year of forecasting",
              "rect": {
                "x": 0.08,
                "y": 0.18,
                "w": 0.84,
                "h": 0.34
              }
            }
          ]
        }
      ],
      "captions": {
        "enabled": true,
        "style": "karaoke",
        "position": 0.78
      }
    }
  }
}

Turns a suggestion into a renderable content piece and returns its `contentId`. Accepting counts against the plan’s saved-post quota; generating did not. A Turbo format is renderable immediately, a Studio format begins its render, and either way the id is what POST /posts takes as `contentId`.

• Accepting a suggestion twice returns the same content id rather than a second piece.
• A suggestion whose brand-safety review withheld it is 409 `conflict`, and no quota is consumed. POST /posts with a `suggestionId` refuses it the same way. Read GET /generations/{id} for the finding, then edit the copy or generate another.

curl -X POST "https://looptake.com/api/v1/generations/6522d1ec-2c11-4d3a-b078-6f6cfe9f217b/accept" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "contentId": "c02119cb-ed7a-40ed-87fe-c18edc1fa1a2",
    "generationId": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
    "format": "walloftext",
    "renderStatus": "pending",
    "creditsSpent": 0
  }
}

Rewrites the hook and keeps everything else, so the only difference between the variants is the line that has to stop the scroll. Angle, deck, format and hashtags are carried over. Each variant is a suggestion in its own right, with its own id and its own hook score.

curl -X POST "https://looptake.com/api/v1/generations/6522d1ec-2c11-4d3a-b078-6f6cfe9f217b/variants" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "count": 2
}'

{
  "success": true,
  "data": [
    {
      "id": "ba2bfff0-0078-45f8-8352-0967f185cba5",
      "remixSource": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
      "caption": "The stockout you did not budget for",
      "score": 74,
      "status": "pending",
      "reviewVerdict": "pass"
    },
    {
      "id": "e70157dd-5ee2-4667-a594-61f9c20ebaf7",
      "remixSource": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
      "caption": "Empty shelf, full warehouse. Both cost the same.",
      "score": 81,
      "status": "pending"
    }
  ]
}

Exactly one content source, resolved in a fixed order: `suggestionId`, then `contentId`, then `deck` with `format`, then `videoUrl` or `images`. Sending two sources is not an error; the first one in that order wins, which keeps the resolution deterministic. A post that has to produce its video before it can publish returns 202 and a `statusUrl`: a deck has to be rendered, and a `videoUrl` or `images` post has to be fetched into our own storage first.

• `approvalStatus` is on this response because it is the only place the common case sees it: a scheduled post with nothing to render is 201 and terminal, so nothing polls `statusUrl` afterwards. `pending` means a person still has to release it and the scheduled time passing does not publish it or cancel it. `null` means no approval was demanded of this post, which is not the same as approved and is not a block: read a missing value as neither.
• A post built from a `deck`, a `videoUrl` or `images` returns 202 rather than 201. Poll `statusUrl` until the status is terminal.
• The media behind `videoUrl` and `images` is fetched once, when the post is created, and published from our copy. A URL that redirects to a private address, answers with something that is not a video or an image, or is larger than 200 MB is refused, and `renderStatus` becomes `failed` with the reason on the post.
• A video is measured after it is fetched and checked against each selected platform: a video longer than YouTube Shorts accepts, or in an aspect ratio Instagram will not publish, fails the post before anything reaches a platform.
• A post that names a YouTube account and does not send `declarations.madeForKids` is refused here, before anything is rendered or charged. YouTube requires that answer on every upload and it is the account holder’s to give: we send what you state, and nothing when you state nothing.
• A field this endpoint does not have is a 400, not a field we ignore. A misspelled key and a capability this build does not carry are both refused at the door, so `altText` and `hashtagPlacement` are refusals rather than fields we store and never send. `firstComment` was on that list until 2026-08-19 and is not any more: it is a real field now, inside `perPlatform`, on the two networks whose API can post a comment. At the TOP level it is still a 400, and deliberately so, a first comment is per network because one of the three cannot post one at all. The same rule already applied inside `perPlatform`; since 2026-08-19 it applies to the whole body.
• Honours `Idempotency-Key`. The same key with the same body replays the stored response; the same key with a different body is a 409.
• Sixty requests per 300 seconds per key.

curl -X POST "https://looptake.com/api/v1/posts" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "suggestionId": "6522d1ec-2c11-4d3a-b078-6f6cfe9f217b",
  "selectedAccounts": {
    "tiktok": [
      "ff9d429b-07c5-4320-a98c-ac6e1791b828"
    ],
    "youtube": [
      "1c74c860-000b-4136-88a7-a17f31019346"
    ]
  },
  "schedule": "scheduled",
  "scheduledTime": "2026-09-01T15:00:00Z",
  "timezone": "Europe/Lisbon",
  "declarations": {
    "madeForKids": false,
    "brandedContent": true,
    "aiGenerated": true,
    "containsSyntheticMedia": true
  }
}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "scheduled",
    "renderStatus": "pending",
    "scheduledTime": "2026-09-01T15:00:00Z",
    "timezone": "Europe/Lisbon",
    "approvalStatus": "pending",
    "statusUrl": "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef",
    "targets": [
      {
        "accountId": "ff9d429b-07c5-4320-a98c-ac6e1791b828",
        "platform": "tiktok",
        "status": "scheduled"
      },
      {
        "accountId": "1c74c860-000b-4136-88a7-a17f31019346",
        "platform": "youtube",
        "status": "scheduled"
      }
    ]
  }
}

Takes the body of `POST /posts` and answers with the publish request each selected account would be sent: the exact caption-and-hashtag text, the derived YouTube title, the visibility, the TikTok switches and the declarations, built by the same function the publisher builds it with. Nothing is written, nothing is queued and nothing is charged. The two refusals that are per platform arrive per target rather than as a status: a caption too long for one of your accounts and an unstated `declarations.madeForKids` are `refusal` on that target and `200` overall, so you see every account’s answer at once instead of the first one. Everything else refuses exactly as `POST /posts` does.

• `bodyText` is the string the platform receives, caption and hashtags joined. It is `null` where the platform receives no text at all, which today is a TikTok target in `inbox` mode: that endpoint takes the video and nothing else, and the creator writes the caption in the app.
• `title` is set only for a platform that has a title field, which is YouTube. Write one with `perPlatform.youtube.title` and it is what you see here and what is uploaded; write nothing and it is the first line of the caption cut to YouTube’s 100 units, which is what this product did before a title could be written. Either way this is where you see which line that is.
• `firstComment` is the text that network receives as a comment under the post, or `null` where it receives none. It is the one field here that is not part of the publish request: no network carries a comment on the call that creates the post, because a comment needs the id that call returns, so this is always a second call made after the post is live. `null` on a TikTok target is the whole reason to preview it, TikTok has no comment endpoint, `POST /posts` refuses a first comment for it outright, and this is where you see that before you schedule.
• `privacy` is `public` on every target. Nothing on the request, the post row or the job payload can set it in this build, so the preview reports the value rather than offering a choice.
• `notSent` lists request fields this build accepts and sends to no platform. `thumbnailUrl` is one: it is fetched, stored and shown in the dashboard, and no platform receives it, so each of them picks its own frame. `images[1:]` is the other: every image you send is fetched and stored, and only the first becomes the post media, because the publish plan carries one asset and no client here has a photo-carousel call.
• `measured` is false unless you send a `contentId` whose render has finished. A video that has not been fetched or rendered yet has no length and no shape, so the two checks that read them have not run. They run at ingest, and again in the publisher.
• `refusal` carries the platform’s own sentence, produced by the publisher’s own pre-flight. A target with a refusal will not publish; the rest of the post still will.
• A field this endpoint does not have is a 400, not a field we ignore. A misspelled key and a capability this build does not carry are both refused at the door, so `altText` and `hashtagPlacement` are refusals rather than fields we store and never send. `firstComment` was on that list until 2026-08-19 and is not any more: it is a real field now, inside `perPlatform`, on the two networks whose API can post a comment. At the TOP level it is still a 400, and deliberately so, a first comment is per network because one of the three cannot post one at all. The same rule already applied inside `perPlatform`; since 2026-08-19 it applies to the whole body.
• Sixty requests per 300 seconds per key, shared with the rest of `/posts`.

curl -X POST "https://looptake.com/api/v1/posts/preview" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "selectedAccounts": {
    "tiktok": [
      "ff9d429b-07c5-4320-a98c-ac6e1791b828"
    ],
    "youtube": [
      "1c74c860-000b-4136-88a7-a17f31019346"
    ]
  },
  "caption": "One stockout costs more than a year of forecasting",
  "hashtags": [
    "retail",
    "ops"
  ],
  "perPlatform": {
    "tiktok": {
      "caption": "Your stockroom is lying to you",
      "hashtags": [
        "fyp"
      ]
    }
  },
  "declarations": {
    "brandedContent": true,
    "aiGenerated": true,
    "containsSyntheticMedia": false
  }
}'

{
  "success": true,
  "data": {
    "measured": false,
    "durationSeconds": null,
    "ratio": null,
    "notSent": [
      "thumbnailUrl",
      "images[1:]"
    ],
    "targets": [
      {
        "accountId": "ff9d429b-07c5-4320-a98c-ac6e1791b828",
        "platform": "tiktok",
        "publishMode": "publish",
        "uploadSource": "url",
        "bodyText": "Your stockroom is lying to you #fyp",
        "title": null,
        "privacy": "public",
        "interaction": {
          "disableComment": false,
          "disableDuet": false,
          "disableStitch": false
        },
        "firstComment": null,
        "declarations": [
          {
            "field": "declarations.brandedContent",
            "stated": true
          },
          {
            "field": "declarations.brandOrganic",
            "stated": null
          },
          {
            "field": "declarations.aiGenerated",
            "stated": true
          }
        ],
        "refusal": null
      },
      {
        "accountId": "1c74c860-000b-4136-88a7-a17f31019346",
        "platform": "youtube",
        "publishMode": "publish",
        "uploadSource": "bytes",
        "bodyText": "One stockout costs more than a year of forecasting #retail #ops",
        "title": "One stockout costs more than a year of forecasting",
        "privacy": "public",
        "interaction": null,
        "firstComment": null,
        "declarations": [
          {
            "field": "declarations.madeForKids",
            "stated": null
          },
          {
            "field": "declarations.containsSyntheticMedia",
            "stated": false
          }
        ],
        "refusal": {
          "message": "YouTube requires `declarations.madeForKids` on every upload and this post does not state it"
        }
      }
    ]
  }
}

One CSV, up to 100 rows, in one transaction. The columns are `caption` and `videoUrl`, which every row must fill, plus the optional `scheduledTime` and `hashtags`; column order is free and a heading this endpoint does not know is a 400 rather than a column nobody reads. Every row is checked before anything is written, the caption against each platform that receives it, the video URL against the same rules `POST /posts` applies, the time against the calendar, and a single bad row imports nothing and comes back naming **every** row that is wrong, not the first. Imported posts are **held as drafts** unless you ask for `schedule: "scheduled"`, so uploading a file never publishes anything on its own.

• All of the file or none of it. The rows are written in one transaction, so there is no state where some of your file is in the calendar and the rest is in your spreadsheet. The alternative, import the 99 and report the 1, was weighed and rejected on the remedy rather than on the principle: a half-filled calendar is repaired by working out which rows landed and deleting them one at a time, which is the work this endpoint exists to remove. This one is repaired by fixing the line and uploading again.
• A rejected file answers `400 invalid_input` whose `message` is a header line followed by one line per bad row, each spelled `line {n}: {reason}`, in file order, with `{n}` counting physical lines from 1 so it is the number your editor shows. Every reason is a fixed sentence: no byte of your file is echoed back. The list is never truncated, because the row ceiling already bounds it.
• The columns are `caption`, `videoUrl`, `scheduledTime` and `hashtags`. `caption` and `videoUrl` are required in the header and in every row; the other two are optional columns and a row may leave either cell empty. A duplicated heading is a 400, because which cell a row means stops being decidable. `hashtags` may be separated by spaces or by commas, whichever your sheet already uses.
• Every row names its video by URL, and there is no way to import a post without one: this build cannot attach media to a post after it exists, so a caption-only row would sit in the calendar for ever unable to publish. Each URL is fetched into our own storage exactly as `POST /posts` fetches one, through the same guard and the same 200 MB limit, after the transaction commits. A URL that turns out not to be a video fails that post’s render and leaves the rest of the file alone.
• At most 100 rows, and a file with more is a 400 naming the ceiling. The number is the work behind a row rather than the size of anybody’s spreadsheet: each row is a content insert, a post insert, up to three target inserts and a fetch of up to 200 MB, all while you wait. A quarter of daily content is about 90 rows.
• A file whose header names no data rows under it is a 400, as is an empty `csv`. Neither is treated as an import of nothing.
• Honours `Idempotency-Key`, and this is the endpoint where it matters most: it is the longest call this API serves, so a client timeout during the commit is the likeliest retry in the product, and a retry that repeated would be a second hundred posts.
• Sixty requests per 300 seconds per key, shared with the rest of `/posts`. One call here is up to a hundred posts where `POST /posts` is one, so this bucket is a hundredfold louder than the rest of the group.

curl -X POST "https://looptake.com/api/v1/posts/import" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "csv": "caption,videoUrl,scheduledTime,hashtags\nOne stockout costs more than a year of forecasting,https://cdn.example/stockout.mp4,2026-09-01 15:00,retail ops\nYour stockroom is lying to you,https://cdn.example/stockroom.mp4,2026-09-02 15:00,retail\n",
  "selectedAccounts": {
    "tiktok": [
      "ff9d429b-07c5-4320-a98c-ac6e1791b828"
    ]
  },
  "schedule": "draft",
  "timezone": "Europe/Lisbon",
  "declarations": {
    "aiGenerated": true
  }
}'

{
  "success": true,
  "data": {
    "validateOnly": false,
    "rows": 2,
    "imported": 2,
    "schedule": "draft",
    "timezone": "Europe/Lisbon",
    "posts": [
      {
        "line": 2,
        "scheduledTime": "2026-09-01T14:00:00Z",
        "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
        "status": "draft",
        "statusUrl": "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef"
      },
      {
        "line": 3,
        "scheduledTime": "2026-09-02T14:00:00Z",
        "id": "0f8c4b6f-4d0b-4a09-9a51-b6d0f2a6a2f3",
        "status": "draft",
        "statusUrl": "https://looptake.com/api/v1/posts/0f8c4b6f-4d0b-4a09-9a51-b6d0f2a6a2f3"
      }
    ]
  }
}

Everything scheduled, publishing, published or failed, newest scheduled time first. `from` and `to` filter on the scheduled time rather than the creation time, which is what a calendar sync wants. Every row names the presenter it was published as, or null when it was published for the brand.

• `approvalStatus` carries the verdict alone on this shape; `GET /posts/{id}` carries the whole record, including who decided and why. `null` means no approval was demanded of this post and it publishes at its time like any other.
• An `approval` value that is not one of the three is 400 `invalid_input` rather than an ignored parameter. A filter that quietly returned everything would answer a review queue with a whole workspace, and the page would look like it worked.

curl "https://looptake.com/api/v1/posts?approval=pending&limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
      "contentId": "c02119cb-ed7a-40ed-87fe-c18edc1fa1a2",
      "status": "scheduled",
      "renderStatus": "ready",
      "schedule": "scheduled",
      "scheduledTime": "2026-09-01T15:00:00Z",
      "timezone": "Europe/Lisbon",
      "ownerType": "brand",
      "influencerId": null,
      "automationId": null,
      "approvalStatus": "pending",
      "targets": [
        {
          "platform": "tiktok",
          "accountId": "ff9d429b-07c5-4320-a98c-ac6e1791b828",
          "status": "scheduled"
        }
      ]
    }
  ],
  "pagination": {
    "total": 18,
    "page": 1,
    "limit": 1,
    "pages": 18
  }
}

One target row per connected account, each with its own status, platform post id, public URL, error and analytics snapshot. A post is `partial` when some targets published and others did not, which is a state a single status field cannot express and a per-target row can.

• One short link is minted per platform the post goes to, so `utm_source` answers "how many came from TikTok" rather than only "how many came from this post". Following one is a 302, never a 301: browsers cache a 301, which would stop the second click from ever being counted.
• Terminal for polling: `posted`, `partial`, `failed` and `cancelled`. A `renderStatus` of `failed` is terminal too. There is no `completed`: a post is done when every target it named has settled, and `partial` is the word for a mixed result.
• `firstComment` appears on a target only when one was written for that network, so a post composed without one reads exactly as it did before the field existed. Its `state` is `pending`, `posted`, `failed` or `unresolved`, and `needsAttention` is `true` for the last two, both mean the same thing to you: **the post is live and the comment is not**, so somebody has to add it by hand. The post is still `posted` in that case, deliberately: the video is on the account and re-publishing it would put it out twice, so the verdict on the comment sits beside the post rather than changing it. `unresolved` means one attempt was made and we never learned how it went; it is not retried, because a duplicate comment under your own video is worse than a missing one and neither network offers a way to ask. `text` carries what was meant to go under the post, so it can be copied straight across.
• Analytics are refreshed on a schedule, so `fetchedAt` is part of the reading.

curl "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "partial",
    "renderStatus": "ready",
    "caption": "The maths nobody runs before they run out.",
    "hashtags": [
      "#retail",
      "#inventory"
    ],
    "scheduledTime": "2026-09-01T15:00:00Z",
    "declarations": {
      "madeForKids": false,
      "brandedContent": true,
      "brandOrganic": null,
      "aiGenerated": true,
      "containsSyntheticMedia": true
    },
    "targets": [
      {
        "accountId": "ff9d429b-07c5-4320-a98c-ac6e1791b828",
        "platform": "tiktok",
        "status": "posted",
        "platformPostId": "7412998812",
        "postUrl": "https://www.tiktok.com/@northwind/video/7412998812",
        "error": null,
        "analytics": {
          "views": 4820,
          "likes": 311,
          "comments": 24,
          "shares": 61,
          "saves": 88,
          "fetchedAt": "2026-09-02T09:00:00Z"
        }
      },
      {
        "accountId": "1c74c860-000b-4136-88a7-a17f31019346",
        "platform": "youtube",
        "status": "failed",
        "platformPostId": null,
        "postUrl": null,
        "error": "The account’s token expired. Reconnect and retry.",
        "firstComment": {
          "state": "failed",
          "text": "#retail #inventory #ops",
          "commentId": null,
          "error": "the post published, but its first comment did not: youtube: this account was connected without the `https://www.googleapis.com/auth/youtube.force-ssl` permission, so it cannot post a first comment. Reconnect it and accept every permission, or remove the first comment from this post.",
          "needsAttention": true
        },
        "analytics": null
      }
    ],
    "attributionLinks": [
      {
        "id": "5e1e2ad1-9b56-4a0d-92b6-04f8dc3d19b6",
        "slug": "k3Bq7Zra",
        "url": "https://looptake.com/go/k3Bq7Zra",
        "targetUrl": "https://northwind.example",
        "utmSource": "tiktok",
        "utmMedium": "social",
        "utmCampaign": "looptake",
        "clicks": 138,
        "lastClickAt": "2026-09-02T08:41:03Z",
        "createdAt": "2026-09-01T14:59:58Z"
      }
    ]
  }
}

Changes what a post says and what its account holder has declared about it, keeping the post. Without it a typo costs the id: DELETE and a second POST /posts mint a new one, and the approval, the short links already printed in the caption, the webhook deliveries your own system stored and the suggestion it was accepted from all end up pointing at a post that no longer exists. Accepted while the post is `draft`, `queued` or `scheduled` and no account has started; once a platform call is in flight the answer is 409, because the words are already on their way. Declarations were write-once until 2026-08-19: they were set at creation and no statement changed them, so a wrong AI disclosure cost the id that everything else here exists to keep.

• A body naming none of the four fields is 400 `invalid_input`. All four are replacements rather than merges: `hashtags` sets the whole list, `perPlatform` sets the whole set of overrides, `declarations` sets the whole object, and the way to add one is to send the collection you want.
• Editing an `approved` post puts it back to `pending`, and it is withheld until somebody agrees again. An approval is a judgement about specific words, so replacing the words replaces the thing that was agreed to, the same reason POST /posts/{id}/reschedule re-opens a decision, applied to what the post says rather than to when it says it. Re-sending the caption a post already has changes nothing and leaves the decision standing.
• A `pending` post keeps waiting, a `rejected` post keeps its refusal, rewriting is exactly what a refused post needs, and a post nobody was asked about is unaffected.
• The publisher checks, as it claims each account, that the post still says what it is about to send. A post being uploaded right now refuses the edit; an edit that lands a moment earlier makes that attempt stand down and re-read, so the words that reach the platform are always the words that were stored.
• It does not move the slot and it does not change which accounts a post goes to. POST /posts/{id}/reschedule is the first; the second is not an operation this API has. It does not replace the video either: no statement in this build writes a post’s media, so footage that is wrong is still a cancel and a new post.
• Editing a declaration on a LAUNCHED automation is still not possible: PATCH /automations/{id} answers 409 once a run has generated, and the posts it already scheduled keep the answers they were created with. Each of those posts is editable here, one at a time, which is the repair. There is no operation that restates a declaration across a whole run.
• A post that is `publishing`, `posted`, `partial`, `failed` or `cancelled` answers 409 `conflict`. A post you cannot read, no such id, or another team’s, is 404 `not_found`.
• A field this endpoint does not have is a 400, not a field we ignore. A misspelled key and a capability this build does not carry are both refused at the door, so `altText` and `hashtagPlacement` are refusals rather than fields we store and never send. `firstComment` was on that list until 2026-08-19 and is not any more: it is a real field now, inside `perPlatform`, on the two networks whose API can post a comment. At the TOP level it is still a 400, and deliberately so, a first comment is per network because one of the three cannot post one at all. The same rule already applied inside `perPlatform`; since 2026-08-19 it applies to the whole body.

curl -X PATCH "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "caption": "The maths nobody runs before they run out of stock."
}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "scheduled",
    "caption": "The maths nobody runs before they run out of stock.",
    "hashtags": [
      "#retail",
      "#inventory"
    ],
    "perPlatform": {
      "tiktok": {
        "caption": "Your stockroom is lying to you",
        "hashtags": null,
        "title": null
      }
    },
    "declarations": {
      "madeForKids": null,
      "brandedContent": null,
      "brandOrganic": null,
      "aiGenerated": true,
      "containsSyntheticMedia": null
    },
    "approval": null,
    "updatedAt": "2026-08-18T14:22:09Z"
  }
}

Only while the post is `draft`, `queued` or `scheduled`, **and** no account has started: the guard is a `not exists` over the target rows, not a check on the post's own status, because `posts.status` still reads `scheduled` for the whole of a platform round trip. Once any target is in flight the call is already out and the answer is 409.

• Any other status returns 409 `conflict`. The content piece is untouched and can be scheduled again.

curl -X DELETE "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "cancelled",
    "cancelledAt": "2026-08-12T11:20:44Z"
  }
}

Releases a post whose `approval.status` is `pending`, and queues its publish immediately, so a slot approved after its scheduled time still goes out rather than being lost. Behind `posts:approve`, which `posts:write` deliberately does not imply: the credential that schedules a post is not always the one that may release it. There is no un-approving as an operation, because that would be a lie once the publisher holds the post, and `DELETE /posts/{id}` is the one that honestly stops one. Two things re-open an approved decision and neither is a decision: `POST /posts/{id}/reschedule` puts the post back to `pending` because a reviewer decides in front of a slot, and `PATCH /posts/{id}` does the same when it changes what the post says, because an approval is a judgement about specific words.

• An API key cannot decide, whatever scopes it holds: the call answers 403 `forbidden_scope`. A decision has to name a person and a key acts for a team, so a null decider would put an approval on the record nobody can be asked about. Decisions come from a signed-in member holding `posts:approve`, or from an external reviewer link.
• A post nobody was asked about, whose `approval` is `null` rather than `pending`, is 409 `conflict` rather than 404: the post exists, you can read it, and it is the state that refuses.
• A post that is already publishing or published is 409. So is approving a `rejected` post: re-open it with `POST /posts/{id}/reject` first, which puts it back to `pending`.

curl -X POST "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef/approve" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Checked the claim in line two against the pricing page."
}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "scheduled",
    "approval": {
      "status": "approved",
      "decidedAt": "2026-08-13T09:12:44Z",
      "decidedBy": "b4a0d51c-6f7e-42a8-9c31-8d5f0a7be213",
      "note": "Checked the claim in line two against the pricing page.",
      "reviewLinkId": null
    }
  }
}

Refuses a `pending` post, which keeps its slot and its row and simply never publishes. Sent against a post that is already `rejected`, it re-opens it: the decision goes back to `pending` and through the queue again. That is the only route back, because there is no transition from `rejected` straight to `approved`. Overturning a refusal in one write would leave no trace that a refusal ever happened.

• Same credential rule as approve: a key is 403 `forbidden_scope`, because a decision has to name a person.
• The second call on a rejected post answers `"status": "pending"`. It is the same endpoint on purpose: a separate re-open route would be a second way to spell one transition.
• Nothing is cancelled or deleted. A rejected post keeps its calendar slot, and the publisher skips it with the reason attached.

curl -X POST "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef/reject" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "The claim in line two is not one we can make."
}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "scheduled",
    "approval": {
      "status": "rejected",
      "decidedAt": "2026-08-13T09:14:02Z",
      "decidedBy": "b4a0d51c-6f7e-42a8-9c31-8d5f0a7be213",
      "note": "The claim in line two is not one we can make.",
      "reviewLinkId": null
    }
  }
}

Changes when a post goes out, keeping the post. Without this the only way to change a slot is DELETE and a second POST /posts, which mints a new id and drops everything pointing at the old one, the short links already printed in a caption, the approval a reviewer gave, the suggestion it was accepted from. Accepted while the post is `draft`, `queued` or `scheduled`; once it is `publishing` the platform call is in flight and the answer is 409. The publisher queued for the old instant is moved with the row, in the same transaction, so a post pulled forward goes out at the new time rather than the old one.

• Moving a post whose `approval.status` is `approved` puts it back to `pending`, and the post is withheld until somebody agrees again. A reviewer decides in front of the slot, so a yes is a yes to this post at this time; the alternative, cancel and recreate, needs a fresh approval too and loses the post’s id as well. The decision fields are cleared and `note` records the move.
• A `pending` post keeps waiting and a `rejected` post keeps its refusal. A post nobody was asked about, whose `approval` is `null`, is unaffected.
• An `asap` post, one created without a `scheduledTime`, which reads as `queued`, becomes `scheduled` at the instant you name.
• A `draft` is moved and **stays a draft**. Giving a post a date is something you do while still writing it, so this call writes the instant and leaves the hold in place; `POST /posts/{id}/publish` is what releases it, and it then goes out at the instant this call set.
• A post that is `publishing`, `posted`, `partial`, `failed` or `cancelled` answers 409 `conflict`: the post exists and you can read it, and it is the state that refuses. A post you cannot read, no such id, or another team’s, is 404 `not_found`, the same answer every other read of it gives.

curl -X POST "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef/reschedule" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledTime": "2026-09-04T09:00:00Z",
  "timezone": "Europe/Lisbon"
}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "scheduled",
    "scheduledTime": "2026-09-04T09:00:00Z",
    "timezone": "Europe/Lisbon",
    "approval": null,
    "updatedAt": "2026-08-18T10:41:07Z"
  }
}

Stops holding a post you saved unfinished, so it goes out at the time it already carries. This is the only thing that releases a draft: no sweep, no worker and no other endpoint moves a post off `draft`, which is what makes `schedule: "draft"` on POST /posts a saved post rather than one that quietly publishes itself. It takes no body and it does not choose a time. The draft already answered that question when it was created, a draft carrying a `scheduledTime` becomes `scheduled` and publishes at that instant, and one carrying none becomes `queued` and publishes as soon as its render finishes. POST /posts/{id}/reschedule is the operation that sets a slot, and it deliberately leaves a draft held, so the two never write the same column for the same click.

• `posts:write` and not `posts:approve`. Deciding a draft is finished is the author’s act, and it does not bypass a reviewer: a draft released in a workspace that requires approval lands `pending` and waits, exactly as a scheduled post does. Read `approval` on the response before telling anybody it is going out.
• A post that is not a draft answers 409 `conflict`, including a draft you have already released, which is what makes a double press safe. A post you cannot read is 404 `not_found`, the same answer every other read of it gives.
• The publisher is queued here only when there is one to queue: a draft still rendering has a publish job waiting on its render already, and it picks the post up when the video lands.

curl -X POST "https://looptake.com/api/v1/posts/973821cf-5cc7-44f7-8795-e68da31c59ef/publish" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "success": true,
  "data": {
    "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
    "status": "queued",
    "scheduledTime": null,
    "timezone": "Europe/Lisbon",
    "approval": null,
    "updatedAt": "2026-08-19T10:41:07Z"
  }
}

The same posts as GET /posts, grouped by local day in the workspace timezone rather than returned as a flat list. This is the shape a calendar view needs, and it is a separate endpoint so a month view is one request instead of a paginated crawl.

• `from` and `to` are both required. An unbounded calendar request is rejected as `invalid_input`.
• Each entry carries `approvalStatus` beside `status`, because they are different axes and a month drawn from `status` alone shows `scheduled` for posts that will not publish. `null` means no approval was demanded of that post. Four fields per entry and no more: open `GET /posts/{id}` for the caption, the targets and who decided.

curl "https://looptake.com/api/v1/calendar?from=2026-09-01&to=2026-09-02" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "timezone": "Europe/Lisbon",
    "days": [
      {
        "date": "2026-09-01",
        "posts": [
          {
            "id": "973821cf-5cc7-44f7-8795-e68da31c59ef",
            "scheduledTime": "2026-09-01T15:00:00Z",
            "status": "scheduled",
            "approvalStatus": "pending"
          }
        ]
      },
      {
        "date": "2026-09-02",
        "posts": []
      }
    ]
  }
}

An automation is a cadence plus a target set. Creating one leaves it in `draft`: nothing is generated and nothing is scheduled until you call generate, and nothing publishes until you call launch. That three-step shape is what makes a month of posts reviewable rather than a thing that started while you were reading about it.

curl -X POST "https://looptake.com/api/v1/automations" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "September daily",
  "cadence": {
    "postsPerDay": 1,
    "days": 30,
    "startDate": "2026-09-01",
    "times": [
      "15:00"
    ],
    "timezone": "Europe/Lisbon"
  },
  "selectedAccounts": {
    "tiktok": [
      "ff9d429b-07c5-4320-a98c-ac6e1791b828"
    ]
  }
}'

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "name": "September daily",
    "status": "draft",
    "cadence": {
      "postsPerDay": 1,
      "days": 30,
      "startDate": "2026-09-01",
      "times": [
        "15:00"
      ],
      "timezone": "Europe/Lisbon"
    },
    "ownerType": "brand",
    "createdAt": "2026-08-12T11:25:00Z"
  }
}

Every automation the workspace holds, with its status and its cadence. The status tells you which call is legal next: `draft` takes generate, `review` takes launch, `launched` takes extend, pause or cancel, and `paused` takes resume or cancel.

curl "https://looptake.com/api/v1/automations?limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
      "name": "September daily",
      "status": "launched",
      "cadence": {
        "postsPerDay": 1,
        "days": 30,
        "startDate": "2026-09-01",
        "times": [
          "15:00"
        ],
        "timezone": "Europe/Lisbon"
      },
      "postCount": 30,
      "createdAt": "2026-08-12T11:25:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 1,
    "pages": 3
  }
}

Adds the settings, the selected accounts and the counts the list shape leaves out: how many posts were generated, how many are still awaiting review and how many have published. It also returns all five of the run’s `declarations`, which you need before you PATCH: that call replaces the object as a whole, so an editor that cannot read the stored answer would have to invent one, and an unstated `madeForKids` reads back as `null` rather than as `false`.

curl "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "name": "September daily",
    "status": "launched",
    "cadence": {
      "postsPerDay": 1,
      "days": 30,
      "startDate": "2026-09-01",
      "times": [
        "15:00"
      ],
      "timezone": "Europe/Lisbon"
    },
    "selectedAccounts": {
      "tiktok": [
        "ff9d429b-07c5-4320-a98c-ac6e1791b828"
      ]
    },
    "settings": {
      "formats": [
        "walloftext",
        "slideshow"
      ],
      "mentionBusiness": true
    },
    "ownerType": "brand",
    "influencerId": null,
    "tiktokMode": "direct",
    "declarations": {
      "madeForKids": null,
      "brandedContent": true,
      "brandOrganic": null,
      "aiGenerated": true,
      "containsSyntheticMedia": null
    },
    "counts": {
      "generated": 30,
      "scheduled": 28,
      "posted": 2,
      "failed": 0
    }
  }
}

Only while the automation is in `draft`. Once it has generated posts, editing the cadence would mean rewriting a schedule a person has already reviewed, so the call is a 409 and the correct move is to cancel and create a new one.

• Any status other than `draft` returns 409 `conflict`.

curl -X PATCH "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "cadence": {
    "postsPerDay": 2,
    "days": 30,
    "startDate": "2026-09-01",
    "times": [
      "09:00",
      "18:00"
    ],
    "timezone": "Europe/Lisbon"
  }
}'

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "draft",
    "cadence": {
      "postsPerDay": 2,
      "days": 30,
      "startDate": "2026-09-01",
      "times": [
        "09:00",
        "18:00"
      ],
      "timezone": "Europe/Lisbon"
    }
  }
}

Moves the automation to `generating`, writes one suggestion per slot in the cadence, and lands it in `review`. Nothing is published by this call. Poll GET /automations/{id} until the status leaves `generating`.

• Terminal statuses for this poll: `review`, or `cancelled` if the run was cancelled mid-generation.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/generate" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "generating",
    "slots": 30,
    "statusUrl": "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f"
  }
}

Extends the cadence past its original end and generates the new slots at the same rhythm. This is how a run becomes continuous without a second automation and without a gap in the calendar.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/extend" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "days": 14
}'

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "generating",
    "days": 44,
    "addedSlots": 14
  }
}

Schedules every post the run generated and moves it to `launched`. This is the call that publishes, so it honours `Idempotency-Key`: a retried launch after a timeout replays the stored response rather than scheduling the month twice.

• Only from `review`. Launching a draft returns 409 `conflict`.
• A run whose `selectedAccounts` include YouTube must carry `declarations.madeForKids` before it can launch, and a 400 here names the field. The check is at launch because this is the last request before a month of posts exists: after it, every slot is created by a background job with nobody left to ask.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/launch" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "launched",
    "scheduled": 30,
    "firstPostAt": "2026-09-01T15:00:00Z"
  }
}

Stops a running cadence without throwing its calendar away. Nothing is cancelled: every post keeps its row, its slot and the publisher already queued for it, and each one is withheld at the moment it would go out rather than being deleted now. Resuming moves the rest of the calendar forward by however long the hold lasted, so a run held for a week comes back a week later in the same rhythm.

• Only from `launched`. A run that has not launched has no calendar to hold, and a 409 says so.
• Never refused because the workspace is archived. Stopping is never blocked: a guard that would not let you hold a run inside an archived brand would trap you in the state you were leaving.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/pause" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "paused",
    "heldPosts": 22,
    "pausedAt": "2026-09-08T11:04:00Z"
  }
}

Moves every post the run still had waiting forward by exactly the length of the hold and puts the run back to `launched`. The spacing is preserved, so two posts a day is still two a day. Resuming onto the original instants would publish every slot that passed during the hold at once, which is the thing a hold is pressed to prevent. `heldForSeconds` is what the calendar moved by.

• Only from `paused`. Anything else is a 409, including a second resume: the move is a compare-and-set, so two resumes in flight shift the calendar once.
• Refused with a 409 while the workspace is archived, because a resumed post in an archived brand is withheld again at its own slot. Restore the brand first.
• Refused with a 409 when the run belongs to an influencer whose consent has been withdrawn since it launched. The videos were rendered before the hold, so this is the last check between a withdrawn likeness and an audience.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/resume" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "launched",
    "resumedPosts": 22,
    "heldForSeconds": 604800,
    "firstPostAt": "2026-09-16T15:00:00Z"
  }
}

Cancels the run and every post it scheduled that has not published yet. Posts that already went out are left alone, because unpublishing is not something an API can promise on three platforms.

curl -X POST "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/cancel" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
    "status": "cancelled",
    "cancelledPosts": 28,
    "keptPosts": 2
  }
}

The review queue while the run is in `review`, and the run’s history after it launches. These posts are deliberately excluded from GET /generations, so this is the only way to read them.

curl "https://looptake.com/api/v1/automations/4ecde50a-7af3-43b9-b66e-a36422c7e51f/posts?limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "98653bae-8565-4cac-a3b8-7fb296ca356d",
      "status": "scheduled",
      "format": "slideshow",
      "scheduledTime": "2026-09-03T15:00:00Z",
      "caption": "Three numbers that decide your reorder point."
    }
  ],
  "pagination": {
    "total": 30,
    "page": 1,
    "limit": 1,
    "pages": 30
  }
}

The influencers this workspace has created, with the attributes that describe them and the voice each one speaks with. The plan caps how many a team may hold.

curl "https://looptake.com/api/v1/influencers?niche=retail&limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
      "name": "Mara",
      "imageUrl": "https://cdn.looptake.com/d076f17e-4529-48a3-b5fe-860bc329c5b4/portrait.jpg",
      "description": "Shop owner turned operations nerd.",
      "niche": "retail",
      "gender": "female",
      "age": 34,
      "ethnicity": "mixed",
      "tags": [
        "retail",
        "operations"
      ],
      "voiceId": "voice_warm_en_3",
      "status": "ready",
      "consentStatus": "attested",
      "consentPermitsRender": true
    }
  ],
  "pagination": {
    "total": 4,
    "page": 1,
    "limit": 1,
    "pages": 4
  }
}

Renders a preview of the character from the reference image and the attributes, and costs 10 credits. The influencer is reusable after that: every video you render from it costs per second, not per character. `subject` is optional in the schema and decisive in effect: a body that does not say what the image is gets treated as `real_person`, which is the strict branch, and a `real_person` with no `consent` block is refused with 400 before anything is charged. Send `subject: "synthetic"` for a wholly invented character and nothing else is needed; send `real_person` and attest, with the release lodged through POST /influencers/consent-artefacts first. The permissive default was the alternative, and it would have made the whole control opt-in.

• Costs 10 credits. A failed preview is refunded automatically by the worker that detected it.
• A body with no `subject` is read as `real_person` and refused with 400 `invalid_input` when it carries no `consent`. This is a change: a script written before consent tooling shipped, which sent only `name` and `imageUrl`, now fails. Nothing is charged by the refusal.
• `consent.artefact` names an upload that must already exist. The object is `head`ed and read once to record its SHA-256, so an id whose upload never happened is refused rather than attached to an attestation.
• `consentStatus` is `attested` for an attested real person, `not_required` for a synthetic one, and `null` only on rows created before this control existed. Recording an attestation is not verification of the subject: nothing here contacts the person in the photograph.

curl -X POST "https://looptake.com/api/v1/influencers" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Mara",
  "imageUrl": "https://cdn.example.com/mara.jpg",
  "subject": "real_person",
  "consent": {
    "subjectName": "Mara Okonkwo",
    "statement": "Signed likeness release, worldwide, 12 months, on file.",
    "artefact": {
      "id": "3f8a6c21-0d94-4f7a-9c62-51a0b7e4d8f3",
      "filename": "release.pdf",
      "kind": "written_release"
    }
  },
  "description": "Shop owner turned operations nerd.",
  "niche": "retail",
  "tags": [
    "retail",
    "operations"
  ]
}'

{
  "success": true,
  "data": {
    "id": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "name": "Mara",
    "status": "ready",
    "voiceId": "voice_warm_en_3",
    "subject": "real_person",
    "consentStatus": "attested",
    "creditsSpent": 10,
    "createdAt": "2026-08-12T11:31:12Z"
  }
}

The first call of the real-person flow: it returns a presigned `PUT` URL, you upload the document to it, and then you name the returned `artefactId` in the `consent` block of POST /influencers or POST /influencers/{id}/consent. Nothing is recorded here and no credits are charged, because an artefact is not evidence of anything until an attestation points at it, and charging for the upload would put a price on the compliant path. The declared `bytes` is signed into the URL, so the bucket itself refuses a body of any other length.

• The URL is good for 30 minutes. One left in a browser tab overnight is dead, because a URL that outlives the sitting it was minted in is a standing write grant to an evidentiary prefix.
• Up to 32 MiB (33,554,432 bytes). The cap is what this endpoint will read back to digest, not what a bucket can hold.
• The object is stored under a retention class that never expires and that the storage layer refuses to delete, and it has no public URL. Evidence that expires with the media is not evidence.

curl -X POST "https://looptake.com/api/v1/influencers/consent-artefacts" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kind": "written_release",
  "filename": "release.pdf",
  "bytes": 184320
}'

{
  "success": true,
  "data": {
    "artefactId": "3f8a6c21-0d94-4f7a-9c62-51a0b7e4d8f3",
    "filename": "release.pdf",
    "kind": "written_release",
    "bytes": 184320,
    "uploadUrl": "https://uploads.looptake.com/invoice/e7293116-fd57-4456-8da0-032f4976145f/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/consent/3f8a6c21-0d94-4f7a-9c62-51a0b7e4d8f3/release.pdf?sig=…",
    "contentType": "application/pdf",
    "expiresAt": "2026-08-12T12:01:12Z"
  }
}

Records one decision about an influencer that already exists, append-only: `attest` needs a statement and a lodged artefact, while `withdraw` and `refuse` need a statement and no document at all, because the stricter direction has to be the easier one to take. They may still carry one, and it is stored: a revocation letter is real evidence and belongs on the record rather than in an inbox. From a withdrawal or a refusal, every path that would spend credits on the likeness answers 409: a new video, a studio render carrying `influencerId`, a post published as that influencer, creating an automation for it, and launching one. Consent can be given again later with a fresh artefact, and the history keeps both records.

• `artefact` is required only when `action` is `attest`. A withdrawal or a refusal may carry one and it is stored exactly as an attestation’s is: verified against the bucket, measured, digested, and filed under the prefix that refuses deletion. A revocation letter or an email saying no is real evidence of why consent ended, and an earlier release accepted the field on those two actions and silently discarded it.
• Demanding paperwork before we will stop using somebody’s likeness would make the stricter direction the harder one to take, so `artefact` stays optional on `withdraw` and `refuse` and always will be. Sending one that cannot be verified is a 400 and writes nothing at all, rather than half-recording the decision; the message says so, and re-sending the same request without `artefact` records the withdrawal immediately.
• `runningAutomations` is what a withdrawal deliberately does not stop. Launched runs keep publishing this likeness on their own timetable until you cancel each one with POST /automations/{id}/cancel. Cancelling a month of your calendar as a side effect of a status change is a decision that belongs to you, and it is one you cannot undo.
• Media already published stays live, keeps its analytics and keeps naming the influencer, so the set that needs a decision is listable.
• The whole history is on GET /influencers/{id} as `consentRecords`, and each decision is also written to the audit log, which the application can never delete from.

curl -X POST "https://looptake.com/api/v1/influencers/d076f17e-4529-48a3-b5fe-860bc329c5b4/consent" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "withdraw",
  "subjectName": "Mara Okonkwo",
  "statement": "The subject withdrew their consent by email on 12 August."
}'

{
  "success": true,
  "data": {
    "influencerId": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "consentStatus": "withdrawn",
    "consentPermitsRender": false,
    "record": {
      "id": "7c1d3a90-2f5b-4e08-badc-9a6f24e17c55",
      "action": "withdraw",
      "subject": "real_person",
      "subjectName": "Mara Okonkwo",
      "statement": "The subject withdrew their consent by email on 12 August.",
      "artefact": null,
      "attestedBy": {
        "type": "api_key",
        "id": "d81ed241-9404-4a1a-8864-242ecc540416",
        "label": "CI publisher"
      },
      "recordedAt": "2026-08-13T10:02:19Z"
    },
    "runningAutomations": [
      {
        "id": "4ecde50a-7af3-43b9-b66e-a36422c7e51f",
        "name": "September daily",
        "status": "launched"
      }
    ]
  }
}

The full character record: the voice it speaks with, the accounts it publishes from, and the whole consent history rather than only the current answer. A withdrawal that hid the attestation it withdrew would be a record of the present, and what anyone asks this endpoint is what happened.

• `consentPermitsRender` is published beside `consentStatus` because the null case is the surprising one. `null` means unrecorded (the character was created before this control existed), and unrecorded still renders. Only a recorded `withdrawn` or `refused` stops it, so a reader who has to re-derive that from the status alone gets the grandfather rule wrong.
• `consentRecords` is append-only and ordered newest first, so a likeness attested, withdrawn and attested again carries all three and `consentRecords[0]` is the decision in force. The artefact is published as a key, a size and a digest and never as a URL: it is a signed release naming a private individual, and an endpoint that handed out a link to it would turn a compliance record into a disclosure. The digest is what makes it checkable: the document in the bucket is the document that was lodged.
• The listing does not carry `consentRecords`. Read this endpoint for the history, and note that recording an attestation is not verification of the subject: nothing here contacts the person in the photograph.

curl "https://looptake.com/api/v1/influencers/d076f17e-4529-48a3-b5fe-860bc329c5b4" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "name": "Mara",
    "imageUrl": "https://cdn.looptake.com/d076f17e-4529-48a3-b5fe-860bc329c5b4/portrait.jpg",
    "description": "Shop owner turned operations nerd.",
    "niche": "retail",
    "gender": "female",
    "age": 34,
    "ethnicity": "mixed",
    "tags": [
      "retail",
      "operations"
    ],
    "voiceId": "voice_warm_en_3",
    "status": "ready",
    "consentStatus": "attested",
    "consentPermitsRender": true,
    "previewVideoUrl": "https://cdn.looptake.com/d076f17e-4529-48a3-b5fe-860bc329c5b4/preview.mp4",
    "creditsSpent": 10,
    "error": null,
    "createdAt": "2026-08-12T11:31:12Z",
    "consentRecords": [
      {
        "id": "7c1d3a90-2f5b-4e08-badc-9a6f24e17c55",
        "action": "attest",
        "subject": "real_person",
        "subjectName": "Mara Okonkwo",
        "statement": "Signed likeness release, worldwide, 12 months, on file.",
        "artefact": {
          "key": "invoice/e7293116-fd57-4456-8da0-032f4976145f/91e14cbf-2c80-4b3b-a6bf-776bbde6b54c/consent/3f8a6c21-0d94-4f7a-9c62-51a0b7e4d8f3/release.pdf",
          "kind": "written_release",
          "bytes": 184320,
          "sha256": "9f2c4d7b1a83e60c5518d9f4a7b2e0c36d81f5a94e73b02c6f1d8a45b93e7c20"
        },
        "attestedBy": {
          "type": "api_key",
          "id": "d81ed241-9404-4a1a-8864-242ecc540416",
          "label": "CI publisher"
        },
        "recordedAt": "2026-08-12T11:31:12Z"
      }
    ],
    "accounts": [
      {
        "id": "1c561cb8-4ea0-4fed-84af-bf13a6efe8e9",
        "platform": "tiktok",
        "handle": "@mara.stock"
      }
    ]
  }
}

Removes the presenter and gives back the plan slot it was holding. The cap counts presenters you hold rather than presenters you are using, so a character you have finished with, or one whose subject has withdrawn consent, occupies a paid slot until you delete it. Every video rendered from the presenter is deleted with it. Posts already published are not: they keep their media, their analytics and their place in the calendar. What they lose is the presenter: the link is cleared on every one of them, so `GET /posts?influencerId=` answers nothing for a presenter you have deleted. List first, delete second.

• Nothing is refunded. The credits bought a preview that rendered, and a delete that gave them back would make create-and-delete a free loop. A preview or a video still rendering when you delete it is the one case that does return credits, and it returns them through the ordinary failure path rather than through this call: the render finds its row gone, fails terminally, and the automatic refund runs.
• `videosDeleted` and `consentRecordsDeleted` are counted inside the transaction that removed them, so they are the number of rows that actually went rather than an estimate taken beforehand.
• `postsUnlinked` is spelled differently because it is a different thing: those posts are not deleted, and every one of them is still live. What they lose is the name of the presenter they went out as, and this call is the last moment anything can count them. If you need the list rather than the number, take `GET /posts?influencerId=` before you delete.
• Deleting a real-person presenter deletes its consent history too, which is how a subject asking to be erased is erased. What survives is an audit entry naming the presenter id, who deleted it, the consent status at the time and these two counts, plus the earlier entry recording that a release was attested and the digest of the document. Neither carries the subject name. The release itself stays in storage under a retention class that refuses deletion.
• Works in an archived workspace. Calls that spend credits are refused there; a call that gives capacity back is not, because a guard on that would trap you in the state you were leaving.

curl -X DELETE "https://looptake.com/api/v1/influencers/d076f17e-4529-48a3-b5fe-860bc329c5b4" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "deleted": true,
    "videosDeleted": 4,
    "consentRecordsDeleted": 2,
    "postsUnlinked": 12
  }
}

Queues a lip-synced video of the influencer delivering your script, and returns immediately. The cost is 5 credits per second of finished video, so a 20-second read is 100 credits. Poll GET /videos/{id} until the status is terminal.

• Terminal statuses: `ready` and `failed`. A failure refunds the reserved credits automatically.
• Honours `Idempotency-Key`, because the call spends credits.

curl -X POST "https://looptake.com/api/v1/influencers/d076f17e-4529-48a3-b5fe-860bc329c5b4/videos" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "script": "A stockout does not cost you one sale. It costs you the customer who came for it.",
  "language": "en",
  "duration": 12
}'

{
  "success": true,
  "data": {
    "id": "08363fcd-f524-4126-b68d-fd64f2f9c09e",
    "influencerId": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "status": "queued",
    "durationS": 12,
    "creditsReserved": 60,
    "statusUrl": "https://looptake.com/api/v1/videos/08363fcd-f524-4126-b68d-fd64f2f9c09e"
  }
}

Every video rendered for this character, newest first, with its status and what it cost.

curl "https://looptake.com/api/v1/influencers/d076f17e-4529-48a3-b5fe-860bc329c5b4/videos?limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "08363fcd-f524-4126-b68d-fd64f2f9c09e",
      "status": "ready",
      "language": "en",
      "durationS": 12,
      "videoUrl": "https://cdn.looptake.com/08363fcd-f524-4126-b68d-fd64f2f9c09e/video.mp4",
      "thumbnailUrl": "https://cdn.looptake.com/08363fcd-f524-4126-b68d-fd64f2f9c09e/thumb.jpg",
      "creditsSpent": 60,
      "createdAt": "2026-08-12T11:33:40Z"
    }
  ],
  "pagination": {
    "total": 9,
    "page": 1,
    "limit": 1,
    "pages": 9
  }
}

Poll this after POST /videos, POST /remix, POST /clips or POST /influencers/{id}/videos. A prompt-first video reports `status` (`queued`, `running`, `ready`, `failed`), `stage`, `progress`, `viralScore` (0-100), `hooks` and `outputs` (content ids and preview URLs); it needs `generations:read`. An influencer video reports `queued`, `processing`, `ready` or `failed` and needs `influencers:read`.

curl "https://looptake.com/api/v1/videos/08363fcd-f524-4126-b68d-fd64f2f9c09e" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": {
    "id": "08363fcd-f524-4126-b68d-fd64f2f9c09e",
    "influencerId": "d076f17e-4529-48a3-b5fe-860bc329c5b4",
    "script": "A stockout does not cost you one sale. It costs you the customer who came for it.",
    "language": "en",
    "durationS": 12,
    "mode": "studio",
    "status": "ready",
    "videoUrl": "https://cdn.looptake.com/08363fcd-f524-4126-b68d-fd64f2f9c09e/video.mp4",
    "thumbnailUrl": "https://cdn.looptake.com/08363fcd-f524-4126-b68d-fd64f2f9c09e/thumb.jpg",
    "creditsSpent": 60
  }
}

`turboEnabled` marks the clips and images you have offered to the Turbo formats. It is a label on your own library and a filter on this call; nothing in this build draws on the pool automatically yet. `url` is ours once the file has been stored: a short-lived signed link that this call re-signs for you when it has expired, so a URL you read here always works. For an asset we could not store it stays the address you gave.

curl "https://looptake.com/api/v1/assets?kind=video&turboEnabled=true&limit=1" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": "a7273471-d932-4f9a-958e-79abdd1f3fd7",
      "kind": "video",
      "category": "b-roll",
      "name": "Warehouse aisle, slow pan",
      "url": "https://cdn.looptake.com/a7273471-d932-4f9a-958e-79abdd1f3fd7/clip.mp4",
      "bytes": 4812004,
      "width": 1080,
      "height": 1920,
      "durationMs": 9200,
      "turboEnabled": true
    }
  ],
  "pagination": {
    "total": 62,
    "page": 1,
    "limit": 1,
    "pages": 62
  }
}

Fetches the file, stores it in our own bucket, and reads its real dimensions and duration out of the file’s own header rather than trusting what you declared. All of that is asynchronous: the 201 carries the row with the URL you gave, and `url`, `width`, `height`, `durationMs` and `bytes` are replaced moments later, so poll `GET /assets` if you need them. Measurements stay `null` for a container this build cannot parse; `null` means "not established", never zero. Images and video are stored (MP4, MOV, WebM, PNG, JPEG, GIF, WebP); an `audio` or `font` asset, and any URL that does not answer, keeps the address you gave and is never measured.

curl -X POST "https://looptake.com/api/v1/assets" \
  -H "Authorization: Bearer $LOOPTAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://cdn.example.com/aisle.mp4",
  "kind": "video",
  "name": "Warehouse aisle, slow pan",
  "category": "b-roll",
  "turboEnabled": true
}'

{
  "success": true,
  "data": {
    "id": "a7273471-d932-4f9a-958e-79abdd1f3fd7",
    "kind": "video",
    "name": "Warehouse aisle, slow pan",
    "category": "b-roll",
    "url": "https://cdn.looptake.com/a7273471-d932-4f9a-958e-79abdd1f3fd7/clip.mp4",
    "bytes": null,
    "width": null,
    "height": null,
    "durationMs": null,
    "turboEnabled": true
  }
}

The three things you can correct after the upload. Every field is optional and a field you leave out is left alone, so renaming a clip does not clear the grouping it is filed under. Send `category: null` to clear the grouping; `name` cannot be cleared, because an asset always has one. Sending an empty body is `invalid_input` rather than a 200 that changed nothing.