Docs menu
API reference

Ideas

Topic seeds and suggested posts.

List ideas

GET/v1/public/ideas
scopescontent:read

Topics with their suggested posts. A fresh account has none (call generate first). Suggested posts are ephemeral suggestions, not stable resources.

request
curl https://api.taka.ai/v1/public/ideas \
  -H "Authorization: Bearer taka_live_..."
response
{
  "ideas": [
    {
      "id": "abc123",
      "headline": "Weekend specials worth the walk",
      "status": "active",
      "createdAt": "2026-09-01T09:30:00Z",
      "posts": [
        {
          "postId": "abc123",
          "shape": "StaticImage",
          "status": "ready",
          "preview": "Fresh croissants out of the oven at 7am"
        }
      ]
    }
  ]
}

Generate idea topics (job)

POST/v1/public/ideas/generate
scopescontent:write

Topic seeds cost no credits. Poll the job; ideas land in GET /ideas.

Path and query parameters
Idempotency-KeystringReplay-safe retries: the same key returns the original response for 24h.
Body
countnumberHow many ideas to generate (default 3, max 10)
directionstringSteer the ideas (e.g. "holiday specials")
request
curl -X POST https://api.taka.ai/v1/public/ideas/generate \
  -H "Authorization: Bearer taka_live_..." \
  -H "Content-Type: application/json" \
  -d '{"count": 3, "direction": "holiday specials"}'
response
{
  "jobId": "01J...",
  "status": "queued",
  "kind": "generate_post",
  "resourceId": "abc123",
  "poll": "/v1/public/jobs/01J..."
}

Pick an idea

POST/v1/public/ideas/{ideaId}/pick
scopesgenerate

Marks the idea picked and, if it has fewer than 3 suggested posts, spawns up to 3 in the background (this draws credits). Poll GET /ideas to watch them land, then promote one.

Path and query parameters
ideaIdrequiredstringIdea id
request
curl -X POST https://api.taka.ai/v1/public/ideas/IDEA_ID/pick \
  -H "Authorization: Bearer taka_live_..."
response
{
  "idea": {
    "id": "abc123",
    "headline": "Weekend specials worth the walk",
    "status": "active",
    "createdAt": "2026-09-01T09:30:00Z",
    "posts": [
      {
        "postId": "abc123",
        "shape": "StaticImage",
        "status": "ready",
        "preview": "Fresh croissants out of the oven at 7am"
      }
    ]
  },
  "postsGenerating": true
}

Dismiss an idea

POST/v1/public/ideas/{ideaId}/dismiss
scopescontent:write

Dismisses the idea so it stops appearing in the list.

Path and query parameters
ideaIdrequiredstringIdea id
request
curl -X POST https://api.taka.ai/v1/public/ideas/IDEA_ID/dismiss \
  -H "Authorization: Bearer taka_live_..."
response
// 204 No Content

Promote a suggested post into a real draft

POST/v1/public/ideas/posts/{postId}/promote
scopescontent:write

The post becomes a normal draft, visible in GET /posts.

Path and query parameters
postIdrequiredstringPost id
request
curl -X POST https://api.taka.ai/v1/public/ideas/posts/POST_ID/promote \
  -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"
}