Compose tweet

Free - does not consume credits

curl -X POST https://xquik.com/api/v1/compose \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "step": "compose",
    "topic": "launching my new SaaS product",
    "goal": "engagement"
  }' | jq

Headers

x-api-key

string

required

Your API key. Session cookie authentication is also supported.

Content-Type

string

required

Must be application/json.

Body

step

string

required

Workflow step. One of compose, refine, or score.

topic

string

Tweet topic. Used in compose and refine steps.

goal

string

Optimization goal: engagement, followers, authority, or conversation.

styleUsername

string

Cached style username for voice matching. Used in compose step.

tone

string

Desired tone for the tweet. Used in refine step.

additionalContext

string

Extra context or URLs. Used in refine step.

callToAction

string

Desired call to action. Used in refine step.

mediaType

string

Media type: photo, video, or none. Used in refine step.

draft

string

Tweet text to evaluate. Used in score step.

hasLink

boolean

Whether a link is attached. Used in score step.

hasMedia

boolean

Whether media is attached. Used in score step.

Workflow

The compose API follows a 3-step workflow:

compose: Returns algorithm weights, content rules, penalties, and follow-up questions
refine: Returns composition guidance, example patterns, media strategy, and CTA advice
score: Evaluates a draft against algorithm checks with pass/fail results

Response

contentRules

object[]

Algorithm content rules. Each item has a rule string.

scorerWeights

object[]

Algorithm scorer weights. Each item has context, signal, and weight fields.

followUpQuestions

string[]

Follow-up questions to refine the composition.

engagementMultipliers

object[]

Engagement multipliers. Each item has action and multiplier fields.

engagementVelocity

string

Engagement velocity description.

intentUrl

string

X intent URL for posting the tweet.

nextStep

string

Instructions for the next API call in the workflow.

savedStyles

object[]

Saved style profiles. Present when you omit styleUsername and cached styles exist.

savedStyles[].username

string

Cached style username.

savedStyles[].tweetCount

number

Number of cached tweets available for that style.

source

string

Algorithm source attribution.

styleNote

string

Style fallback note. Present when a requested style is not cached and the request can continue without refreshing it.

styleTweets

string[]

Cached example tweets used for voice matching. Present when styleUsername matches a cached style.

topPenalties

string[]

Top algorithm penalties to avoid.

{
  "contentRules": [{ "rule": "Keep under 280 characters" }, { "rule": "Front-load the hook" }],
  "scorerWeights": [{ "context": "tweet", "signal": "hook", "weight": 2 }],
  "engagementMultipliers": [{ "action": "reply", "multiplier": "1.5x" }],
  "engagementVelocity": "First 30 minutes are critical for algorithmic reach",
  "topPenalties": ["External links reduce reach by ~50%"],
  "followUpQuestions": [
    "What tone do you want? (casual, professional, bold)",
    "Will you attach media (photo, video, none)?",
    "What call-to-action do you prefer?"
  ],
  "intentUrl": "https://x.com/intent/tweet?text=...",
  "nextStep": "Call with step: refine, providing tone, goal, and topic",
  "source": "X algorithm analysis"
}

compositionGuidance

string[]

Composition guidance tips.

examplePatterns

object[]

Example tweet patterns. Each item has pattern and description fields.

intentUrl

string

X intent URL for posting the tweet.

nextStep

string

Instructions for the next API call in the workflow.

{
  "compositionGuidance": [
    "Lead with a personal story or metric.",
    "End with an open question."
  ],
  "examplePatterns": [
    { "pattern": "Hook -> Context -> CTA", "description": "Surprising metric, 1-2 sentences, open question" }
  ],
  "intentUrl": "https://x.com/intent/tweet?text=...",
  "nextStep": "Write your draft and call with step: score"
}

totalChecks

number

Total number of algorithm checks evaluated.

passedCount

number

Number of checks that passed.

passed

boolean

Overall pass/fail result.

topSuggestion

string

Top improvement suggestion.

checklist

object[]

Individual check results.

Show check item

factor

string

Check factor name.

passed

boolean

Whether this check passed.

suggestion

string

Improvement suggestion. Omitted if passed.

nextStep

string

Instructions for next steps.

intentUrl

string

X intent URL. Present only when all checks pass.

{
  "totalChecks": 11,
  "passedCount": 9,
  "passed": false,
  "topSuggestion": "Add a specific detail or metric to the first line.",
  "checklist": [
    { "factor": "No external links in body", "passed": true },
    { "factor": "No hashtags", "passed": true },
    { "factor": "No excessive capitalization", "passed": true },
    { "factor": "Conversation-driving CTA", "passed": true },
    { "factor": "Optimal length (50-280 characters)", "passed": true },
    { "factor": "Media attached", "passed": true },
    { "factor": "No excessive punctuation", "passed": true },
    { "factor": "No emojis", "passed": true },
    { "factor": "No em dashes or double dashes", "passed": true },
    { "factor": "Sufficient substance", "passed": false, "suggestion": "Add a specific detail or metric" },
    { "factor": "Link-in-reply strategy", "passed": false, "suggestion": "Move the link to a reply instead" }
  ],
  "nextStep": "Revise your draft and score again"
}

{ "error": "invalid_input", "message": "step is required. Must be \"compose\", \"refine\", or \"score\"." }

Invalid JSON returns invalid_json. Valid JSON with a missing or unsupported step, missing topic for compose, missing goal, tone, or topic for refine, or missing draft for score returns invalid_input.

{ "error": "unauthenticated" }

Missing or invalid API key.

{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }

Too many requests. Wait for the Retry-After header before retrying.

Next steps: Save Draft to save a composed tweet for later, or Analyze Style to match another account’s voice.

Overview

X API

X Write

Trends

Radar

Account

API Keys

Credits

X Accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Compose tweet

Headers

Body

Workflow

Response

Overview

X API

X Write

Trends

Radar

Account

API Keys

Credits

X Accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Documentation Index

​Headers

​Body

​Workflow

​Response

Headers

Body

Workflow

Response