API reference

Posts

Drafts, variants, versions, generation, and revision.

List posts

GET/v1/public/posts

scopescontent:read

Posts with their per-platform variants, newest first. Media URLs are signed and expire after ~6 hours; never cache them.

Path and query parameters

status	enum: draft \| scheduled \| published	Filter by post status
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Filter to posts targeting one platform
from	string	Only posts created at/after this ISO timestamp
to	string	Only posts created before this ISO timestamp
cursor	string	Cursor from a previous page
limit	number	Page size (default 20, max 100)

request

curl "https://api.taka.ai/v1/public/posts?status=draft&limit=10" \
  -H "Authorization: Bearer taka_live_..."

response

{
  "posts": [
    {
      "id": "abc123",
      "name": "Weekend croissant special",
      "kind": "post",
      "status": "draft",
      "needsApproval": false,
      "idea": "Weekend special: fresh croissants",
      "variants": [
        {
          "id": "abc123",
          "platform": "instagram",
          "isPrimary": true,
          "status": "draft",
          "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
          "title": "Weekend croissant special",
          "description": "Behind the counter at Sunrise Bakery",
          "hashtags": [
            "croissants"
          ],
          "altText": "A tray of golden croissants on a wooden counter",
          "media": [
            {
              "id": "abc123",
              "url": "https://media.taka.ai/abc123.jpg?signature=...",
              "type": "image",
              "ratio": 1,
              "altText": "A tray of golden croissants on a wooden counter"
            }
          ],
          "mediaOrigin": "taka",
          "scheduledAt": null,
          "publishedAt": null,
          "permalink": null,
          "generation": {
            "status": "ready",
            "error": null,
            "videoStatus": null
          },
          "score": {
            "value": 82,
            "verdict": "strong",
            "singleFix": "Open with the offer, not the greeting"
          },
          "publishFailure": null,
          "pinned": false
        }
      ],
      "createdAt": "2026-09-01T09:30:00Z",
      "updatedAt": "2026-09-01T09:30:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImFiYzEyMyJ9"
}

Create a draft post

POST/v1/public/posts

scopescontent:write

Creates an empty draft on one platform. Call generate to fill it with AI content, or use posts/from-media for your own media.

Path and query parameters

Idempotency-Key

string

Replay-safe retries: the same key returns the original response for 24h.

Body

platformrequired	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest	Primary platform of the post
name	string	Post name (defaults to the idea, truncated)
idea	string	The idea/brief behind the post. Seeds AI generation when you call generate.

request

curl -X POST https://api.taka.ai/v1/public/posts \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram", "name": "Weekend croissant special", "idea": "Weekend special: fresh croissants"}'

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Get a post

GET/v1/public/posts/{postId}

scopescontent:read

The full post with per-platform variants, media, and quality scores.

Path and query parameters

postIdrequired

string

Post id

request

curl https://api.taka.ai/v1/public/posts/POST_ID \
  -H "Authorization: Bearer taka_live_..."

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Edit a variant's text

PATCH/v1/public/posts/{postId}

scopescontent:write

Direct edit (no credits). body maps to the field the platform publishes. Send null to clear a field; omitted fields are preserved. Editing the primary re-derives other platforms; editing a sibling pins it.

Path and query parameters

postIdrequired

string

Post id

Body

platformrequired	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Which platform variant to edit
body	string \| null	Post body text. Maps to the field the platform actually publishes (caption / message / text / description). Send null to clear.
title	string \| null	Title (YouTube Shorts / Pinterest only)
description	string \| null	Description (YouTube Shorts / Pinterest only)
hashtags	string[]	Without the # prefix
altText	string \| null	Alt text for the image. Send null to clear.

request

curl -X PATCH https://api.taka.ai/v1/public/posts/POST_ID \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform": "instagram", "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.", "hashtags": ["croissants"]}'

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Delete a post

DELETE/v1/public/posts/{postId}

scopescontent:write

Deletes the whole post including every platform variant. Not reversible.

Path and query parameters

postIdrequired

string

Post id

request

curl -X DELETE https://api.taka.ai/v1/public/posts/POST_ID \
  -H "Authorization: Bearer taka_live_..."

response

// 204 No Content

Live metrics for a post

GET/v1/public/posts/{postId}/metrics

scopesanalytics:read

Instagram only today, and only within roughly the 25 most recent posts of the account. Unavailability is stated plainly with a machine reason.

Path and query parameters

postIdrequired

string

Post id

request

curl https://api.taka.ai/v1/public/posts/POST_ID/metrics \
  -H "Authorization: Bearer taka_live_..."

response

{
  "available": true,
  "reason": null,
  "metrics": {
    "platform": "instagram",
    "permalink": "https://www.instagram.com/p/Cabc123/",
    "publishedAt": "2026-09-01T09:30:00Z",
    "caption": "Fresh croissants out of the oven at 7am",
    "likes": 128,
    "comments": 14
  }
}

Create a post from your own media

POST/v1/public/posts/from-media

scopescontent:write

Your uploads are published untouched (1 video = reel, 1 image = post, 2-10 images = carousel). AI editing is disabled for these posts by design. Schedule it with the schedule verb.

Path and query parameters

Idempotency-Key

string

Replay-safe retries: the same key returns the original response for 24h.

Body

attachmentIdsrequired	string[]	Your uploaded attachment ids, in display order. 1 video = reel; 1 image = post; 2-10 images = carousel. Uploads must belong to the same user identity as the API key.
platforms	string[]	Target platforms (validated against what the media shape supports)
caption	string	Caption applied to every variant
name	string	Post name (defaults to the caption, truncated)

request

curl -X POST https://api.taka.ai/v1/public/posts/from-media \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"attachmentIds": ["abc123"], "platforms": ["instagram"], "caption": "Fresh croissants out of the oven at 7am"}'

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Rename a post

PATCH/v1/public/posts/{postId}/name

scopescontent:write

Renames the post. The name is workspace-facing only; it never publishes.

Path and query parameters

postIdrequired

string

Post id

Body

namerequired

string

The new post name

request

curl -X PATCH https://api.taka.ai/v1/public/posts/POST_ID/name \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Weekend croissant special"}'

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Version history of a variant

GET/v1/public/posts/{postId}/versions

scopescontent:read

Version history of a variant, newest first. Any version can be restored as a new tip.

Path and query parameters

postIdrequired	string	Post id
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl https://api.taka.ai/v1/public/posts/POST_ID/versions \
  -H "Authorization: Bearer taka_live_..."

response

{
  "variantId": "abc123",
  "versions": [
    {
      "seq": 3,
      "kind": "ai",
      "label": "After feedback",
      "feedback": "Shorter, and lead with the offer",
      "score": 82,
      "verdict": "strong",
      "createdAt": "2026-09-01T09:30:00Z"
    }
  ]
}

Restore a version

POST/v1/public/posts/{postId}/versions/{seq}/restore

scopescontent:write

Non-destructive: the restored state comes back as a new tip version.

Path and query parameters

postIdrequired	string	Post id
seqrequired	number	Version number to restore
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl -X POST https://api.taka.ai/v1/public/posts/POST_ID/versions/3/restore \
  -H "Authorization: Bearer taka_live_..."

response

{
  "variantId": "abc123",
  "versions": [
    {
      "seq": 3,
      "kind": "ai",
      "label": "After feedback",
      "feedback": "Shorter, and lead with the offer",
      "score": 82,
      "verdict": "strong",
      "createdAt": "2026-09-01T09:30:00Z"
    }
  ]
}

Set the image from your media or brand library

POST/v1/public/posts/{postId}/set-image

scopescontent:write

No credits. Not available on posts made from your own media.

Path and query parameters

postIdrequired

string

Post id

Body

attachmentIdrequired	string	Attachment id (from your media uploads or the brand image library)
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl -X POST https://api.taka.ai/v1/public/posts/POST_ID/set-image \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"attachmentId": "abc123", "platform": "instagram"}'

response

{
  "id": "abc123",
  "name": "Weekend croissant special",
  "kind": "post",
  "status": "draft",
  "needsApproval": false,
  "idea": "Weekend special: fresh croissants",
  "variants": [
    {
      "id": "abc123",
      "platform": "instagram",
      "isPrimary": true,
      "status": "draft",
      "body": "Fresh croissants out of the oven at 7am. Come early, they go fast.",
      "title": "Weekend croissant special",
      "description": "Behind the counter at Sunrise Bakery",
      "hashtags": [
        "croissants"
      ],
      "altText": "A tray of golden croissants on a wooden counter",
      "media": [
        {
          "id": "abc123",
          "url": "https://media.taka.ai/abc123.jpg?signature=...",
          "type": "image",
          "ratio": 1,
          "altText": "A tray of golden croissants on a wooden counter"
        }
      ],
      "mediaOrigin": "taka",
      "scheduledAt": null,
      "publishedAt": null,
      "permalink": null,
      "generation": {
        "status": "ready",
        "error": null,
        "videoStatus": null
      },
      "score": {
        "value": 82,
        "verdict": "strong",
        "singleFix": "Open with the offer, not the greeting"
      },
      "publishFailure": null,
      "pinned": false
    }
  ],
  "createdAt": "2026-09-01T09:30:00Z",
  "updatedAt": "2026-09-01T09:30:00Z"
}

Generate the post with AI (job)

POST/v1/public/posts/{postId}/generate

scopesgenerate

Draws from your credit balance (charged on success only; static 1, carousel 2-10, reel 1). Returns 202 with a job; reels can take ~15 minutes.

Path and query parameters

postIdrequired	string	Post id
Idempotency-Key	string	Replay-safe retries: the same key returns the original response for 24h.

Body

idea	string	Idea/brief for the generation (defaults to the post idea)
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl -X POST https://api.taka.ai/v1/public/posts/POST_ID/generate \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"idea": "Weekend special: fresh croissants", "platform": "instagram"}'

response

{
  "jobId": "01J...",
  "status": "queued",
  "kind": "generate_post",
  "resourceId": "abc123",
  "poll": "/v1/public/jobs/01J..."
}

Revise the post with AI feedback (job)

POST/v1/public/posts/{postId}/revise

scopesgenerate

Semantic revision: the engine keeps what works. The job result carries honesty flags (revisionApplied, noVisibleChange, imageryReverted). Narrate from them, never assume the change landed.

Path and query parameters

postIdrequired	string	Post id
Idempotency-Key	string	Replay-safe retries: the same key returns the original response for 24h.

Body

feedbackrequired	string	Natural-language feedback; the engine keeps what works
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl -X POST https://api.taka.ai/v1/public/posts/POST_ID/revise \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Shorter, and lead with the offer", "platform": "instagram"}'

response

{
  "jobId": "01J...",
  "status": "queued",
  "kind": "generate_post",
  "resourceId": "abc123",
  "poll": "/v1/public/jobs/01J..."
}

Regenerate the image, keep the copy (job)

POST/v1/public/posts/{postId}/regenerate-image

scopesgenerate

New image, same copy. Draws 1 credit and returns a job to poll.

Path and query parameters

postIdrequired	string	Post id
Idempotency-Key	string	Replay-safe retries: the same key returns the original response for 24h.

Body

hint	string	What the new image should change
platform	enum: instagram \| facebook \| linkedin \| tiktok \| youtube_shorts \| pinterest \| x	Defaults to the primary variant

request

curl -X POST https://api.taka.ai/v1/public/posts/POST_ID/regenerate-image \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"hint": "Show the croissants on a wooden counter", "platform": "instagram"}'

response

{
  "jobId": "01J...",
  "status": "queued",
  "kind": "generate_post",
  "resourceId": "abc123",
  "poll": "/v1/public/jobs/01J..."
}