---
title: "Compose, refine, or score a tweet"
method: POST
path: "/compose"
tags: ["Composition"]
---

# Compose, refine, or score a tweet

`POST /compose`

## Request body

- object
  - `step` 'compose' | 'refine' | 'score', required — Workflow step
  - `topic` string — Tweet topic (compose, refine)
  - `goal` 'engagement' | 'followers' | 'authority' | 'conversation' — Optimization goal
  - `draft` string — Tweet draft text to evaluate (score)
  - `tone` string — Desired tone (refine)
  - `styleUsername` string — Cached style username for voice matching (compose)
  - `additionalContext` string — Extra context or URLs (refine)
  - `callToAction` string — Desired call to action (refine)
  - `mediaType` 'photo' | 'video' | 'none' — Media type (refine)
  - `hasLink` boolean — Whether a link is attached (score)
  - `hasMedia` boolean — Whether media is attached (score)

## Response `200`

Composition result

- object
  - `text` string — Generated or refined tweet text
  - `score` number — Engagement score (0-100)
  - `feedback` string — AI feedback on the draft
  - `suggestions` string[] — Improvement suggestions

## Other responses

- `400` — Invalid input
- `401` — Unauthenticated
- `429` — Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying.

## Changes

- **2026-07-13** `83005363f122` — 4 breaking, 52 info
  - added `subschema #1: LegacyErrorCode, subschema #2: StructuredError` to the `error` response property `oneOf` list for the response status `400`
  - added `subschema #1: LegacyErrorCode, subschema #2: StructuredError` to the `error` response property `oneOf` list for the response status `401`
  - the `error` response's property type/format changed from `string`/`` to ``/`` for status `400`
  - the `error` response's property type/format changed from `string`/`` to ``/`` for status `401`
  - …52 more
- **2026-04-25** `2adc33156b4b` — 4 warning, 7 info
  - added the new `insufficient_credits` enum value to the `error` response property for the response status `400`
  - added the new `insufficient_credits` enum value to the `error` response property for the response status `401`
  - added the new `no_credits` enum value to the `error` response property for the response status `400`
  - added the new `no_credits` enum value to the `error` response property for the response status `401`
  - …7 more
- **2026-04-08** `d40c57a05527` — 4 info
  - added the optional property `feedback` to the response with the `200` status
  - added the optional property `score` to the response with the `200` status
  - added the optional property `suggestions` to the response with the `200` status
  - added the optional property `text` to the response with the `200` status

[Change history](https://skmtc.dev/xquik-dev/apis/xquik-api/changes/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-service-production.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api/revisions/83005363f122/schema)