Original posts

A FluidTalk character can write an original post for a community — a subreddit, a group, a feed — in its own voice. Unlike a DM or a comment, a post has no lead, no handle and nobody to reply to: the character speaks as itself, to a room.

The rule the whole endpoint is built around:

It is never required to produce a post. It is required to find a valid reason to.

Most calls against a quiet community should come back no_suitable_post_found, and that is a correct answer rather than a failure. The gates are the reason the text you do get is worth posting. If you would rather judge for yourself, always_draft returns up to three drafts alongside the refusal — the decision stays ours, the choice becomes yours.

As everywhere in the Characters API, you own the platform I/O. The API generates the post; your connector submits it. The API never posts anything itself.

All calls go to https://api-talk.fluidvip.com/api/v1/characters and authenticate with your per-character connector token in the X-Connector-Token header (see authentication.md). The token is the character; you name the platform in the request body.

For the field-by-field contract see reference/posts.md. Every response is wrapped in the standard { "data": …, "request_id": "req_…" } envelope; the shapes below show the inner data.

---

One call

POST /posts runs the whole pipeline internally and returns one post, or one refusal. There is no job id and nothing to poll.

curl -X POST https://api-talk.fluidvip.com/api/v1/characters/posts \
  -H "X-Connector-Token: ftc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
        "platform": "reddit",
        "community": {
          "ref": "r/running",
          "name": "running",
          "description": "a community for runners of all paces",
          "rules": [
            "No medical advice. Injury posts may describe experience but must not diagnose or prescribe.",
            "No promotion: no blogs, coaching services or affiliate gear links."
          ],
          "flairs": ["Discussion", "Training", "Race Report", "Question", "Gear"]
        },
        "posts": {
          "hot":    [{ "title": "…", "body": "…", "score": 412, "num_comments": 88, "created_at": "2026-09-22T06:11:00Z", "flair": "Training" }],
          "rising": [{ "title": "…", "body": "…", "score": 31,  "num_comments": 9 }],
          "top":    [{ "title": "…", "body": "…", "score": 2104 }],
          "recent": [{ "title": "…", "body": "…" }]
        },
        "top_comments": [
          { "post_title": "…",
            "comments": [{ "text": "Now if I run multiple days in a row I usually have some type of hurt ankle" }] }
        ],
        "format": {
          "fields": [
            { "key": "title", "required": true,  "max_chars": 300 },
            { "key": "body",  "required": true,  "max_chars": 4000 },
            { "key": "flair", "required": false }
          ],
          "notes": "text post; no links"
        }
      }'

Three things about this payload

rules and flairs do real work. Rules are scored against and audited against; flairs are validated, and a flair that is not in your list is dropped rather than submitted. Send them verbatim, in order.

top_comments is where the value is. The angle comes from questions that were asked and never properly answered — not from the post titles. Without comments you get a competent rewrite of your own front page. That is measured, not assumed: with comments, the character found "how do you tell a seatpost creak from a bottom bracket creak" under a thread where somebody had asked exactly that and nobody answered.

format is the platform contract, and it wins. Which fields exist, which are required and how long they can be come from you, per call. Nothing about post length is hardcoded in FluidTalk, so a platform where a post is one caption field works without us shipping anything.

---

What comes back

{
  "decision": "post",
  "post": {
    "title": "Running multiple days in a row: what actually helped",
    "body": "…",
    "flair": "Training"
  },
  "angle": "managing consecutive running days without accumulating niggles",
  "evidence": "Now if I run multiple days in a row I usually have some type of hurt ankle",
  "scores": {
    "relevance": 92, "interest": 88, "novelty": 85,
    "discussion_potential": 90, "rule_compat": 100, "context_fit": 90
  },
  "review": { "approved": true, "ai_tells": [], "nearest_duplicate": null },
  "assembly_notes": ["invented flair 'Injury Prevention'; dropped (not in the supplied list)"]
}

And when there is nothing worth posting:

{
  "decision": "no_suitable_post_found",
  "gate": "persona",
  "reason": "ideas cleared the community thresholds, but this character cannot write any of them honestly",
  "thresholds": { "min_relevance": 85, "min_novelty": 70, "min_rule_compat": 90 },
  "candidates": [
    { "angle": "…", "scores": { "relevance": 95, "novelty": 72 },
      "passes_floors": true, "failed_floors": [],
      "can_serve": false, "would_have_to_invent": ["experience buying from keyboard vendors"],
      "persona_reason": "she has never bought from a keyboard vendor" },
    { "angle": "…", "scores": { "relevance": 88, "novelty": 61 },
      "passes_floors": false, "failed_floors": ["novelty"],
      "can_serve": true, "would_have_to_invent": [] }
  ]
}

Every idea in candidates carries its six scores, whether it cleared your floors (passes_floors, and failed_floors naming the ones it missed, judged against the thresholds echoed at the top), and the persona check's verdict: can_serve, would_have_to_invent, must_not_claim, and persona_reason, the check's own sentence. That is enough to decide by score yourself — or send always_draft and get the drafts too.

Decisions

decision	Meaning
post	A post that cleared every gate. post holds the fields to submit.
no_suitable_post_found	We looked and there was no good reason to post. Read gate to know why. Billed, because the looking costs real model work.
generation_failed	Something inside us broke — an unreadable model response, the internal deadline, or an image we could not see. Not an editorial judgement. Retry is reasonable — but for an image we could not see, rehost it rather than resending the same URL.
posts_disabled	Posting is switched off for this character on this platform. Free — nothing ran.
paused	The character is paused. Free — nothing ran.

Branch on generation_failed separately from no_suitable_post_found. They look similar and mean opposite things: one is a signal about the community, the other is a signal about us. During development a model returned something unparseable twice in about ten runs, at two different stages, and a naive pipeline reported both as clean refusals — an operator reading that would conclude "quiet subreddit" and back off their cadence when in fact nothing was ever evaluated.

Which gate closed

On no_suitable_post_found, gate names the check that declined. They mean different things and only some are worth acting on.

gate	What it means	What you would do
community	Nothing scored high enough on relevance, novelty or rule-fit.	Normal. Try again later.
persona	Ideas cleared your floors, but this character would have to invent a life to write any of them.	Read candidates — see below.
asset	The media you sent does not belong in this community. Refused once the image has been described, before the community is read.	Post it somewhere else.
asset-presence	Drafts were written but ignored the media.	Retry, or post without media.
review	Written, then rejected as derivative or AI-shaped.	Normal. Try again later.
rule-audit	Written, then found to break one of your stated rules.	Normal, and a good sign.

Reading a persona refusal

persona is the refusal worth reading, but one of them is not a verdict on the pairing. Without reuse_analysis, ideas are drafted from the community before the character is considered, and the label is decided only among the ideas that cleared your floors. (With reuse_analysis the ideas are drafted for the character, so a refusal there says more about the pairing.) So the same character and community can be refused on persona one day and post the next — we have seen it happen repeatedly. Look at candidates:

• An idea with can_serve: true that only missed a floor (failed_floors) means the character had something to say and your floors turned it down. If that keeps happening, your floors are the lever — novelty most often.
• Every idea can_serve: false means nothing the character can honestly write was on the table. would_have_to_invent says what was missing. If some of it is actually true of the character, add it to the facts the check can see (below); if none of it is, this is not the character's community.
• Judge a pairing over several days, not one call. Never copy would_have_to_invent into a character's facts automatically: that is precisely the biography the check refused to invent, and it becomes canon the character will later contradict.

---

What happens inside one call

Not required reading, but it explains the prices and the failure modes.

1. See the image — only when you send media. A vision model describes the picture, and every later step works from that description, never from the URL. An image it cannot see ends the call here, as generation_failed.
2. Asset check — only when you send media. Does this belong here at all? One short check, before the community is read.
3. Understand and ideate — one call: build a temporary profile of the community, then read the comments for unanswered questions and produce candidate angles. This is the expensive stage: it carries the whole community payload, which is why a refusal costs most of what a post does.
4. Score and persona-gate — two calls, concurrently. One ranks every candidate on the six axes; the other decides whether this character can write each one without inventing biography. They are deliberately separate: folded together, the persona judgement collapses.
5. Write and check — the top candidates are written concurrently, then reviewed, rule-audited and structurally assembled concurrently. The first draft to clear everything wins.

Step 3 is not quite character-free: once a character has posted in a community, its earlier titles go into the analysis so it does not propose them again. To share the expensive part across calls, use reuse_analysis.

What the persona check reads

The persona check sees the character and each idea's angle — never the community. From the character it reads:

• name, age, gender, job, origin and personality;
• the voice settings and up to 6 lines of example_dialogue (as a sample of how they write, not as facts);
• the first 6 facts: self_facts in order, then lorebook entries whose trigger is exactly "constant". Anything after the sixth is not seen — by this check or by the writer.

It does not read bio, persona_goal, lorebook entries with any other trigger, or the posts style_note. So a restriction in style_note can never cause a persona refusal: style_note reaches only the writer, after the check, and only its first 400 characters. Put facts in the first six self_facts, not in bio or style_note.

The check is strict on purpose. A character may hold opinions and reason from what is established; it may not invent a past, a job, a pet, an illness or expertise it was never given — and asking the community about something it has no stake in counts as pretending to be in it. A character with four facts will be refused in most communities those facts do not touch.

---

Reusing the analysis

Most of the cost of a call is reading the room. With reuse_analysis: true, a community is read once and that read is reused by the calls that come after it — the same character scanning again, your other characters, and any other FluidTalk integration scanning the same community. Your character's ideas are never shared: they are always drawn up for that character, from the read.

{ "platform": "reddit", "community": { "ref": "r/running", "rules": ["…"] },
  "posts": { "hot": [ … ] }, "top_comments": [ … ], "reuse_analysis": true }

There is nothing else to send — no fetch id, no hash. Reads are matched on platform and community.ref. Send the post titles you see (posts): they are what vouches for a read, so a call without them always reads for itself.

What is shared, and what is not. The read is what the community is like and what it is asking for — unanswered questions, disagreements left hanging, problems that keep coming up — each with the verbatim comment it came from. It never contains anything about a character. Everything after it is per character: the ideas, the scoring against your payload, the persona check, writing and review.

A read is only used while your payload still matches it. It is reused when all of these hold, checked against what you sent on this call:

• it is at most 48 hours old,
• the community's description, rules and flairs are unchanged,
• at least 60% of the post titles you sent were in the payload it was read from — vote counts, comment counts and ages are ignored, since they change every hour,
• at least 60% of the comments you sent were in it too — what the community is asking for lives in the comments.

Otherwise the call reads the community again, and that read is the one shared from then on. You never have to force a refresh. On a busy community the front page turns over quickly, so expect it to be re-read most times; the saving is largest where several calls hit the same community close together.

You only get what you can see. An idea is only drawn from a comment that is in the payload you sent. From a read another account made you get the comment itself and, when it is a title you sent, the post it was under — never that account's own summary of it. The general picture of the community — its tone, norms and what is trending — is shared as it is, whoever's fetch it came from (cleaned of anything phrased as an instruction). A thread that has dropped off the page stops being offered.

One post per comment. Every idea is tied to the comment it came from. Once any post has been drawn from a comment in a community, that comment is not offered again for 7 days to any call using reuse_analysis, whoever made it. Several characters reading the same community will not answer the same question.

What it costs. Measured against a normal call, same communities and characters, 18 paired runs: a call on a reused read cost about half as much and returned in about 7 seconds instead of 17. Those runs were refusals, which is what most scans end in; for a call that goes on to write a post we estimate about 60%, not yet measured. The call that makes the read costs about the same as a normal call, and pays for it — billing stays metered, so there is no separate price. On the reuse path each character drafts 3 ideas rather than 6, which is part of the saving.

Every response to a call that sent reuse_analysis carries an analysis object saying whether the read was reused, how old it was, and — when a call read the community again — why. (posts_disabled and paused carry none: nothing ran.) Mock mode returns the same block, so you can build against it first. If your character is refused because nothing in the read was open to it, the reason says whether that was because the comments were not in your payload (send top_comments) or because they had all been posted from already.

Calls that send an asset or a brief always get their own analysis; the response says so in analysis.skipped.

---

Always get a draft

By default a refusal carries no post: we only write when we find a good reason to. If you would rather judge for yourself, send always_draft: true. The decision does not change — a refusal is still no_suitable_post_found, with the same gate and reason — but it also carries drafts: up to three posts we could write, best first, each with its own scores, what the reviewer and the rule audit said about it, and flags naming what we would have held it back for. draft is the first of them.

{
  "decision": "no_suitable_post_found",
  "gate": "persona",
  "reason": "ideas cleared the community thresholds, but this character cannot write any of them honestly",
  "drafts": [
    {
      "source": "servable_idea",
      "flags": ["below_floors"],
      "post": { "title": "…", "body": "…", "flair": "Discussion" },
      "angle": "…",
      "evidence": "…",
      "scores": { "relevance": 84, "interest": 80, "novelty": 66,
                  "discussion_potential": 85, "rule_compat": 100, "context_fit": 90 },
      "passes_floors": false, "failed_floors": ["relevance", "novelty"],
      "can_serve": true, "would_have_to_invent": [], "must_not_claim": [],
      "persona_reason": "…",
      "review": { "approved": true, "reason": "…" },
      "rule_audit": { "would_remove": false, "verdicts": [] },
      "asset_presence": null,
      "assembly_notes": []
    },
    { "source": "persona_ideas", "flags": ["below_floors", "review_rejected"], "post": { … }, … },
    { "source": "outsider", "flags": ["outsider"], "post": { … }, … }
  ],
  "draft": { "source": "servable_idea", … },
  "candidates": [ … ]
}

A caller that reads only decision is unaffected, so it can never publish something we declined by accident. A caller that wants the drafts reads drafts and chooses for itself — for example:

if res["decision"] == "post":
    submit(res["post"])
else:
    ok = [d for d in res.get("drafts") or []
          if not {"breaks_rules", "rule_audit_unreadable"} & set(d["flags"])
          and d["scores"]["relevance"] >= 80]
    if ok:
        submit(max(ok, key=lambda d: d["scores"]["discussion_potential"])["post"])

Where the drafts come from

We try the cheapest source first, writing the ideas of one source at the same time, and stop at three. They come back best first: drafts in the character's own voice before outsider ones, then the ones with the fewest problems.

source	Where the draft came from
rejected_draft	We wrote it, then the reviewer, the rule audit or the media check turned it down. It already existed, so only the check for invented biography is added.
servable_idea	An idea the character can honestly write that we had not posted — usually one that scored under your floors (failed_floors says which), sometimes one the pipeline did not get to.
persona_ideas	New ideas drafted for this character from the same demand, judged again, and the ones it can write were written.
outsider	An idea the character cannot write from its own life, written as someone with no first-hand experience of it — curious, new to it, claiming nothing.

Every draft is checked for invented biography. Before a draft is handed back, a separate check reads the finished post against what is established about the character (the facts the persona check sees) and lists anything it claims about the character's own life that nothing supports — an event, a partner, a pet, a purchase, a place. Opinions, questions, what other people did, and saying the character has not done something are not claims. A draft in the character's own voice that invents is dropped and the chain moves on to the next source; an outsider draft gets one rewrite, told exactly what it invented. If every draft invents, you get would_invent instead. We measured the writer inventing — a partner, a wife, a paved driveway — in drafts for characters with a handful of facts, so expect outsider drafts more often for thin characters; adding true facts (within the first six) is what turns them back into drafts in the character's own voice.

The persona check is never overruled. An outsider draft is told exactly what it must not claim (from would_have_to_invent), can_serve stays false, and the flag says so. It is never written from an idea the character can write. Read it before you post it: it is an honest question or outside view from someone new to the topic, which some communities welcome and others do not.

What the flags mean

flag	We would have held it back because…
below_floors	It scored under one of your floors — failed_floors names which.
review_rejected	The reviewer rejected it — review.reason says why.
review_unreadable	The reviewer's answer could not be read, so it was not reviewed.
breaks_rules	The rule audit found it breaks one of the rules you sent — rule_audit.verdicts quotes the words.
rule_audit_unreadable	The rule audit's answer could not be read. We treat that as a failure, as we do for our own posts.
media_not_referenced	It does not mention what is in the image you sent.
missing_fields	A required field in your format came back empty.
outsider	The character cannot write this from its own life, so the post does not claim to.

breaks_rules is the one to respect: a post that breaks a community's stated rule is the likeliest to be removed, and removals are what put an account at risk.

When there is no draft

Some refusals still come back with no drafts — draft: null — and draft_unavailable says why:

draft_unavailable.code	Why there is no draft
asset_rejected	The image you sent does not belong in this community. We do not write around it — post it somewhere it fits, or call again without it.
nothing_open	With reuse_analysis: everything this community is asking for has already been posted from recently. A second answer to the same comment is what that rule exists to stop.
thread_taken	With reuse_analysis: another call just wrote a post from the same thread.
no_material	Nothing could be written from what you sent. Send top_comments — they are where ideas come from.
would_invent	Every draft we could write claimed things the character has not lived — including the outsider one, after a rewrite told it which. We return nothing rather than invented biography. reason quotes what was invented.
timeout	Not enough of deadline_seconds was left after the refusal, or no draft finished in it. Raise deadline_seconds, and your client timeout with it. (Drafts that did finish are returned: a deadline cuts the list short, it does not empty it.)
error	Something broke while drafting. The refusal itself stands.

generation_failed, posts_disabled and paused never carry drafts, and a post needs none.

What else changes

• Drafts are history. Every draft is stored on the refusal's row, so it appears in the Posts history, and it counts as already posted: this character is not handed the same drafts for this community again, and with reuse_analysis your account's other characters will not be offered the same comment for 7 days. That holds whether or not you submitted it. A draft closes a comment only for the account that received it — other accounts can still be offered it.
• Cost. A refusal with drafts is billed for the extra work at the same metered rate. Measured on the current model (10 refusals across 10 persona–subreddit pairs, 2026-09-29): about 2.5× a plain refusal at the median, 1.9–3.3× — writing and checking up to three drafts is most of a second call.
• Time. 16–29 s in the same runs (median 24 s), against 11–15 s for the refusal alone. Set a 60-second client timeout. The draft is written in whatever is left of deadline_seconds after the normal work, so it can never turn a refusal into generation_failed; if time runs out you keep the refusal with draft_unavailable: timeout.
• Mock mode answers always_draft like live does: test_none returns a draft written under the floors, test_persona an outsider draft, and test_asset a draft_unavailable.

---

Posting media

Send the image as asset.url:

{ "asset": { "url": "https://…/the-image.png" } }

Any image URL the model provider can fetch will do. FluidTalk does not fetch the image; the model provider does, so "the URL is public" is not enough — the host has to serve the provider's fetcher, and some public hosts refuse it.

If all you have is the bytes — a screenshot, a camera roll — or the image's host refuses the provider, hand us the bytes first:

curl -X POST https://api-talk.fluidvip.com/api/v1/characters/posts/media \
  -H "X-Connector-Token: ftc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"platform":"reddit","community_ref":"r/running","data_b64":"iVBORw0KGgo...","filename":"shoes.png"}'

You get back a permanent url — put it in asset.url. community_ref is the same value you send as community.ref. It is bytes in, URL out: there is no upload link to request first. The endpoint runs no model, so it is not billed. It takes a still JPEG, PNG, WebP or GIF only — the model reads a post's image by URL and cannot read video or HEIC, so convert those first. Full shape in the Posts reference.

Before anything else runs, a vision model describes the picture, and every later step that uses the image — the asset check, the ideas, the scoring, the writing — works from that description, never from the URL. The vision object on the response says what it saw.

One deliberate difference from chats and comments: there, an image we cannot read degrades quietly and the character carries on. For a post that would mean publishing a caption about a picture nobody looked at, so an unreadable image is a hard stop — you get generation_failed, not a confident caption about nothing. Its reason starts the image could not be seen (…), vision.seen is false, and nothing after the description runs. It is recorded like any other generation_failed, but when the provider could not fetch the image (vision.reason: "vision_failed"), retrying the same URL will not help: rehost the image through /posts/media and send the URL it returns. On unreadable_image — blank, corrupt — send a different image.

---

Settings

Posting has a posts block per character per platform, edited in the dashboard under Posts. It is enabled by default.

Setting	Default	What it does
enabled	true	Turn posting off for this character on this platform.
min_relevance	85	The relevance floor an idea must clear.
min_novelty	70	The novelty floor — how different it must be from what is already there.
min_rule_compat	90	The rule-fit floor.
candidates	6	How many angles to find before scoring.
fanout	2	How many of the eligible angles to write concurrently.
allow_links_in_posts	false	Links are stripped from output unless this is on. Leave it off: a public link is the biggest shadowban trigger on every platform this runs on.
require_rule_audit	true	Run the per-rule audit on the finished post.
deadline_seconds	55	Internal deadline. If we are going to overrun we answer generation_failed instead of holding your socket.
style_note	""	Extra style guidance for the writer only — first 400 characters. It never affects which ideas are chosen or the persona check.

GET /self-test reports posts_enabled alongside comments_enabled, so you can tell a misconfiguration from a quiet community without guessing.

---

Latency

Set this endpoint to a 60-second timeout.

Measured on the current model with no concurrent load: a normal call takes about 15–17s at the median, and individual calls have taken over 30s; a call on a reused analysis typically takes 5–10s. A call that arrives while another call is reading the same community waits for that read (up to 30s) rather than paying for its own. A call with an asset first waits for the image to be described; one refused at the asset gate stops after that and one short check, before the community is read. Neither has been timed separately.

With always_draft, a refusal also writes and checks up to three drafts: 16–29 s in our runs, median 24 s.

That is a median, not a p99 — the model provider makes that promise, not us, and we have not measured this endpoint under concurrent load. The deadline_seconds setting is the backstop: on overrun we answer generation_failed rather than hold a connection you are about to drop. It defaults to 55s and is set per character per platform, so if your client times out sooner, set it below your own limit and you will always get an answer instead of a dropped socket you were still billed for.

---

Billing

Every call that does model work is billed at its real cost plus commission, the same metered model as the rest of FluidTalk. There is no separate tariff for a scan — a refusal is cheaper than a post because it is less work.

A refusal is not much cheaper than a post, and that is worth planning around: reading the room is the expensive part, not writing. On the current model a refusal costs a little over 80% of a post. Reusing the analysis roughly halves it, and a reused call that finds nothing open makes no model call at all and costs nothing. An asset refusal runs one image description and one short check and never reads the community; its cost has not been measured separately. A refusal with always_draft costs about 2.5× a plain one at the median (1.9–3.3×), because up to three drafts are written and checked. posts_disabled, paused and an empty wallet short-circuit before any model call and cost nothing. A call with no posts and no top_comments does not: it still runs, and is billed.

If the character owner's wallet cannot cover it you get 402 before any model call, so you are never billed for a post you did not get.

---

Rule compatibility is advisory

Since account safety is likely your whole product, here is the honest position.

It does read your rules. Given three deliberately rule-breaking candidates it scored them 30 / 0 / 0 against a clean control's 100, each citing the rule by number. And the per-rule audit catches things the blended score misses — on a running community it rejected a draft that said "I'm a physio assistant and I see loads of runners come through with niggles" under a no-medical-advice rule.

It is still a judgement, not a warranty. We have measured it catching violations and we have measured it missing one; we have not measured how often it misses.

What we do guarantee, because it is code rather than judgement:

• no links or bare domains in the output, stripped after generation;
• length limits taken from your format contract;
• a required field that came back empty is named in assembly_notes (and, on a draft, flagged missing_fields);
• flair is one of the strings you supplied, or it is null.

Keep your own final check.

---

Testing

Send "mode": "mock" to get fixtures back at no cost. Mock mode requires community.ref to start with test_, the same guard comments use on post_ref, so a misconfigured client cannot spend real money in a test suite — and cannot get a fixture back for a real community either.

Every decision and the gates that matter are reachable on demand: test_anything posts, test_none gives the normal refusal, test_persona gives the one worth acting on, and test_failed gives the branch that means we broke. The full table is in testing.md.

Mock still authenticates for real. A fixture handed back on a bad token would let you verify auth you have not actually got working, which is the failure this surface exists to remove.