FlowynBETA
LoginSign up

DOCX Parse

Reads a DOCX in document order and returns Markdown or `flowyn.docx_parse.v1` JSON. Paragraphs, headings, lists, and tables come through in order.

What docx parse does

Reads a DOCX in document order and returns Markdown or flowyn.docx_parse.v1 JSON. Paragraphs, headings, lists, and tables come through in order.

When to use docx parse

  • Contract intake
  • Content migration
  • Feeding Word documents to an agent

Authentication

Send an API key as a bearer token. Keys are shown once, belong in a server environment, and are bound to one environment: flw_test_ keys act in test and flw_live_ keys in live.

http
Authorization: Bearer flw_test_••••

Endpoint

http
POST https://api.flowyn.dev/v1/docx/parse

Request

Send an Idempotency-Key so a retried request cannot create a duplicate. The body is JSON.

curl -X POST https://api.flowyn.dev/v1/docx/parse \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: docx-001" \
  -d '{
    "file_id": "9c1e5b7a-2d4f-4a6b-8e3c-1f0a7d2b5c64",
    "output": "markdown"
  }'

Response

Flowyn returns HTTP 202. The response is abridged here; the OpenAPI document lists every field.

Response
{
  "id": "2b7d9e1f-4a6c-4b8d-9f2e-7c1a3e5d8b90",
  "object": "job",
  "operation": "docx_parse",
  "status": "queued",
  "file_id": "9c1e5b7a-2d4f-4a6b-8e3c-1f0a7d2b5c64",
  "request_id": "req_5f2a9c1e7b3d4a6f8e0c2b1d"
}

Lifecycle

  1. Upload the file with POST /v1/files (tus resumable upload). The response is the file with its id.
  2. Call POST /v1/docx/parse with the file_id. Flowyn stores the operation and returns HTTP 202 with a job id before any work starts.
  3. A managed worker claims the job, runs the operation, and records an attempt.
  4. Read GET /v1/file-jobs/{id}. When status is complete, outputs lists the produced files; download one with GET /v1/files/{id}/download.

Status values

StatusMeaning
queuedAccepted, waiting for a worker.
delayedWaiting before a scheduled retry.
processingA worker is running the operation.
retryingThe last attempt failed and another is scheduled.
completeOutputs are stored and listed in outputs.
failedThe operation could not complete; error explains why.
cancelledCancelled before it completed.

Retries

A file operation gets up to 3 attempts. Worker failures and timeouts are retried; an unreadable or unsupported file fails without a retry.

Idempotency

Send Idempotency-Key.

Errors

StatustypeMeaning
400invalid_requestThe body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large).
401unauthorizedMissing, malformed, or revoked API key.
402billing_errorThe monthly credit allowance is used (credit_limit_exceeded). Reads keep working.
403forbiddenThe key lacks the ability this call needs (ability_required).
404not_foundThe id does not exist in this environment.
409conflictFor example idempotency_mismatch: the Idempotency-Key was used with a different body.
422invalid_requestA field value is out of range, for example invalid_timeout.
429rate_limitedToo many requests (rate_limit_exceeded). Wait for Retry-After seconds.
5xxserver_errorFlowyn failed. The body carries an error_id to quote to support.

Limits

  • output is markdown or json
  • Files up to 50 MB
  • Flowyn does not infer business fields from the document

Read it back

Keep the id and read the resource whenever you need its current state.

bash
curl https://api.flowyn.dev/v1/file-jobs/2b7d9e1f-4a6c-4b8d-9f2e-7c1a3e5d8b90 \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Next step

Read Limits and credits.