Seed to scheduled post

Pick a seed, or plant one

Seeds are the topics content grows from. List what you already have:

GET /api/v1/seeds?search=rates&limit=10

Or save your own:

POST /api/v1/seeds

{
  "title": "What a rate dip means for spring buyers",
  "content": "Rates eased this week. For buyers who paused their search last fall...",
  "category": "purchase"
}

Saving a seed is free and returns 201 with the stored seed and its id. It runs no model; the seed holds your material as you wrote it.

Generate a social post with a visual

POST /api/v1/creations/generate

{
  "type": "social_post",
  "seed_id": "0a1b2c3d-0000-4000-8000-000000000000",
  "include_visual": true,
  "aspect_ratio": "square",
  "media_style": "photorealistic"
}

The response is 201 with the finished creation: caption, alt text, and the generated image as a stored URL. Nothing streams; the call settles when the work is done, and the caption and image together cost one flat social post charge. Prefer your own picture? Pass image_asset_id instead of include_visual, per Bring your own image.

{
  "creation": {
    "id": "5e6f7a8b-0000-4000-8000-000000000000",
    "type": "social_post",
    "url": "https://hub.truetone.ai/creations/social_post/5e6f7a8b-0000-4000-8000-000000000000",
    "body": {
      "type": "social_post",
      "caption": "Rates eased this week, and that changes the math for spring buyers...",
      "altText": "A front porch in morning light",
      "imageUrl": "https://..."
    }
  }
}

The full response also carries creditsCharged, the amount this call actually captured.

Regenerate until it is right

Not quite there? Regenerate in place. The creation keeps its id; the call rewrites and saves in one step, answering 200 because nothing new was created.

POST /api/v1/creations/regenerate

{
  "type": "social_post",
  "creation_id": "5e6f7a8b-0000-4000-8000-000000000000",
  "parts": "caption",
  "change_instructions": "Lead with the question, drop the exclamation points."
}

parts controls what is redone on a social post: caption, image, or both (the default). Each part has its own price, and a both call prices the image at its bundled rate, so the pair together costs less than two standalone calls would. On a both call the save is all-or-nothing: if the image leg fails, the old post stands untouched and everything reserved is released.

See where you can post

GET /api/v1/schedule/targets

{
  "targets": [
    {
      "platform": "linkedin",
      "accountId": "acct_example_1",
      "label": "Jordan Example",
      "readyToPost": true,
      "blockedReason": null
    }
  ],
  "manageUrl": "https://hub.truetone.ai/account/social"
}

Targets are the social accounts already connected in the dashboard; the API never connects new ones. An account that needs attention still appears, with readyToPost: false and a blockedReason telling the person what to fix, at manageUrl.

Schedule it

POST /api/v1/schedule

{
  "type": "social_post",
  "creation_id": "5e6f7a8b-0000-4000-8000-000000000000",
  "scheduled_time": "2026-09-02T15:30:00Z",
  "targets": ["linkedin"]
}

Name targets by platform, or by accountId when you have two accounts on one platform. The time must be at least five minutes out. The post’s caption and image come from the creation itself; nothing in this request can override the content, which is why you tuned it in the step before. Scheduling is free.

Change your mind

DELETE /api/v1/schedule/9c0d1e2f-0000-4000-8000-000000000000

{
  "id": "9c0d1e2f-0000-4000-8000-000000000000",
  "cancelled": true,
  "providerPostWithdrawn": true
}

Cancellation withdraws the post from the publishing provider first and only then removes it from your calendar, so you are never left with a deleted row and a still-live post. If the provider cannot be reached, the call answers 502 distribution_failed with retryable: true and keeps the row so you can try again.