---
title: "POST /api/v1/compose"
method: POST
path: "/api/v1/compose"
tags: ["Composition"]
---

# POST /api/v1/compose

`POST /api/v1/compose`

## Request

- Base URL: `https://xquik.com`
- URL: `https://xquik.com/api/v1/compose`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Uses xai-org/x-algorithm facts to compose and refine text. The score step checks text. It never predicts reach or engagement.

## Request body

- union
  - ComposePrepareRequest: Inputs for preparing source-backed post guidance.
    - `step` 'compose', required
    - `topic` string, required: Subject for the post.
    - `goal` 'engagement' | 'followers' | 'authority' | 'conversation': User goal used for 1 follow-up question.
    - `styleUsername` string: Username from a style analysis saved to this account.
  - ComposeRefineRequest: Inputs for refining a post plan.
    - `step` 'refine', required
    - `topic` string, required: Subject to refine into a post.
    - `goal` 'engagement' | 'followers' | 'authority' | 'conversation', required: User goal interpreted against published ranking signals.
    - `tone` string, required: Requested writing tone.
    - `mediaType` 'photo' | 'video' | 'none': Planned media type.
    - `callToAction` string: Specific action the draft should request.
    - `additionalContext` string: Audience, constraints, sources, or other writing context.
  - ComposeScoreRequest: Inputs for checking a post draft.
    - `step` 'score', required
    - `draft` string, required: Full post text. The endpoint never assigns a ranking score.
    - `hasLink` boolean: Accepted for backward compatibility. No guidance uses it.
    - `hasMedia` boolean: Accepted for backward compatibility. Text checks ignore this field.

## Response `200`

Result for the requested workflow step

- union
  - ComposePrepareResult: Rules, questions, and research guidance for drafting a post.
    - `contentRules` ComposeContentRule[], required: Facts derived only from xai-org/x-algorithm.
      - `rule` string, required
    - `engagementMultipliers` ComposeSignalLabel[], required: Source ranking signals. Repository defaults may vary in production.
      - `action` string, required: Human-readable published signal name.
      - `multiplier` 'Source default. Production value can vary.', required
    - `engagementVelocity` string, required: Publication limit for timing and decay claims.
    - `followUpQuestions` string[], required
    - `intentUrl` string, uri, required: X post intent seeded with the topic.
    - `nextStep` string, required
    - `radarRecommendations` ComposeRadarRecommendation[], required: Deprecated compatibility field. Always empty.
      - `endpoint` string, required: Radar endpoint for this source.
      - `guidance` string, required: Source-specific drafting guidance.
      - `source` 'reddit' | 'github' | 'trustmrr' | 'hacker_news' | 'google_trends' | 'wikipedia' | 'polymarket', required
      - `useFor` string, required: Current-topic research this source supports.
    - `scorerWeights` ComposeScorerSignal[], required: Source signals with production values withheld as null.
      - `context` string, required: Signal direction and production limit.
      - `signal` string, required: Signal name from X's public ranking repository.
      - `weight` unknown, required
    - `source` string, required: Signal source and evidence limits.
    - `topPenalties` string[], required: Negative engagement predictions in the public model.
    - `savedStyles` ComposeSavedStyle[]: Style analyses saved to the account.
      - `tweetCount` integer, required: Whole number from 0.
      - `username` string, required
    - `styleTweets` string[]: Cached examples for the requested style username.
    - `styleNote` string: Next action when no cached style is available.
  - ComposeRefineResult: Source-backed guidance for refining a post.
    - `compositionGuidance` string[], required: Request context and xai-org/x-algorithm guidance.
    - `examplePatterns` ComposeExamplePattern[], required
      - `description` string, required
      - `pattern` string, required
    - `intentUrl` string, uri, required: X post intent generated for the refined topic.
    - `nextStep` string, required
  - ComposeScoreResult: Posting validation without a fabricated ranking score.
    - `checklist` ComposeScoreCheck[], required: Deterministic input validation. Not a reach prediction.
      - `factor` string, required
      - `passed` boolean, required
      - `suggestion` string: Present only when the check fails.
    - `intentUrl` string, uri: Present only when every check passes.
    - `nextStep` string, required
    - `passed` boolean, required
    - `passedCount` integer, required
    - `topSuggestion` string, required
    - `totalChecks` 1, required

## Other responses

- `400`: Invalid input. A value past its maxLength gets this answer, & the message names the field & its limit.
- `401`: Unauthenticated
- `429`: Too many requests right now. Each user gets 500 reads a second. Each minute allows 120 writes & 60 deletes. `x_api_rate_limited` means X limits this read for now. Neither answer costs anything. Wait for the seconds in `Retry-After`, then retry.
- `500`: Unexpected error.
- `default`: Unexpected error.

## Changes

- **2026-10-20** `45942c75fdc2`: 10 warning
  - added the new `topup_in_progress` enum value to the `allOf[#/components/schemas/Error]/error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `429`
  - added the new `topup_in_progress` enum value to the `allOf[#/components/schemas/Error]/error/oneOf[subschema #2: StructuredError]/code` response property for the response status `429`
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `400`
  - added the new `topup_in_progress` enum value to the `error/oneOf[subschema #1: LegacyErrorCode]/` response property for the response status `401`
  - …6 more

[Operation history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/api/v1/compose/post.md)

---

[API](https://skmtc.dev/xquik-dev/apis/xquik-api.md) · [All operations](https://skmtc.dev/xquik-dev/apis/xquik-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xquik-dev/apis/xquik-api/revisions/45942c75fdc2?raw)