> ## Documentation Index
> Fetch the complete documentation index at: https://docs.robinzip.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Compress text

> POST /v1/text

Compress text with a preset or a custom operation chain. Every request returns a [job](/concepts/jobs), always the same shape. Small inline inputs are processed inline and the job comes back already `completed` (HTTP **200**, result included); everything else is queued (HTTP **202**) and finishes asynchronously.

**Fast-path eligibility:** inline `text` of at most **50 KB** (UTF-8) with no `webhookUrl`. Everything else is queued.

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer sk_live_...`
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  Optional, 1–255 characters. Returns the existing job if a job with this key was already created. Applies to queued jobs only; fast-path jobs complete inline and are not deduplicated.
</ParamField>

<ParamField body="text" type="string">
  Inline text to process, up to 5,000,000 characters. Provide exactly one of `text` or `fileId`.
</ParamField>

<ParamField body="fileId" type="string">
  Id of an [upload](/concepts/uploads), `.pdf` or `.txt` only.
</ParamField>

<ParamField body="preset" type="string">
  One of `chill`, `medium`, `aggressive`. Either `preset` or `operations` is required.
</ParamField>

<ParamField body="operations" type="array">
  1–10 custom operations, applied in order. See below.
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL to receive `job.completed` / `job.failed` events for this job. Forces the queued path. Requires a plan with webhooks.
</ParamField>

## Presets

| Preset       | Operations                                                                     |
| ------------ | ------------------------------------------------------------------------------ |
| `chill`      | `trim` (intensity 30): light whitespace cleanup                                |
| `medium`     | `trim` (intensity 70): full whitespace, punctuation, and unicode normalization |
| `aggressive` | `trim` (intensity 80) + `json-to-toon`                                         |

## Operations

| Type           | Params                          | Description                                                                            |
| -------------- | ------------------------------- | -------------------------------------------------------------------------------------- |
| `trim`         | `intensity` (0–100, default 50) | Whitespace, punctuation and unicode cleanup, lossless for meaning                      |
| `json-to-toon` | None                            | Convert large JSON blocks to TOON tabular notation (skips blocks too small to benefit) |

`GET /v1/text/presets` and `GET /v1/text/operations` return these definitions as JSON.

## Examples

```bash Fast path (inline text) theme={null}
curl -s https://api.robinzip.app/v1/text \
  -H "Authorization: Bearer $ROBIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello   world...", "preset": "medium"}'
```

```bash Queued (uploaded PDF) theme={null}
curl -s https://api.robinzip.app/v1/text \
  -H "Authorization: Bearer $ROBIN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-2026-07" \
  -d '{"fileId": "665f1c2ab8d4e91a2c3d4e5f", "operations": [{"type": "trim", "params": {"intensity": 80}}, {"type": "json-to-toon"}]}'
```

<ResponseExample>
  ```json 200: completed (fast path) theme={null}
  {
    "success": true,
    "data": {
      "id": "665f1d00b8d4e91a2c3d4e60",
      "status": "completed",
      "result": {
        "outputText": "Hello world...",
        "metrics": {
          "inputSize": 18,
          "outputSize": 15,
          "compressionRatio": 0.8333,
          "processingMs": 2,
          "operationsApplied": ["trim"]
        }
      }
    }
  }
  ```

  ```json 202: queued theme={null}
  {
    "success": true,
    "data": {
      "id": "665f1d00b8d4e91a2c3d4e60",
      "status": "created"
    }
  }
  ```
</ResponseExample>

## Results

One code path handles both: check `status`. If it's `completed`, the result is already in the response. Otherwise poll `GET /v1/jobs/:id` (ideally with [`?wait=25`](/api-reference/jobs-get) to long-poll) or wait for the webhook.

Jobs created from inline `text` return `result.outputText`; jobs created from a `fileId` return `result.outputUrl` pointing to a `.txt` file. PDFs have their text extracted before processing.

## Credits

1 credit per started 100 KB of input, reserved up front and refunded if the job ultimately fails. See [Credits](/concepts/credits).