API reference

POST /v1/generate

Base URL https://api.searchops.io. This is the only endpoint needed to generate documents.

Headers

Body

Responses

file returns raw bytes with these headers:

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="report.docx"; filename*=UTF-8''report.docx
X-Generation-Time-Ms: 480

base64 and url return JSON:

{
  "status": "success",
  "format": "url",
  "data": "https://api.searchops.io/v1/download/550e8400-e29b-41d4-a716-446655440000",
  "pages": null,
  "generation_time_ms": 480
}

pages is always null. Download links from url live for 24 hours.

Formatting options are not active

The API accepts and validates an options object — font, font_size, header_text, footer_text, page_size and the four margin_* fields — but it does not change the document yet. Styling comes from a fixed template (Roboto, A4).

When you send it, the API says so: JSON responses gain a warnings array, and file responses gain an X-DocxAPI-Warning header. Do not depend on these fields until this note is removed.

Error codes

{ "error": { "code": "INVALID_API_KEY", "message": "Invalid or inactive API key." } }

Every response carries X-Request-Id. Include it when reporting a problem.

Plans and limits

• Only successful generations count against quota. Failed requests are logged, not charged.
• The month is the calendar month in UTC.
• Free plan documents carry a watermark line at the end.
• Paid plans keep working past quota and are billed for overage.
• Extra credits come in blocks of 50 (min 50, max 10,000) and are used after the plan quota.

POST /v1/gutenberg/convert

Converts the same three input formats into WordPress block markup. Consumes one credit from the same balance as the DOCX endpoint.

Body

Response

POST /v1/gutenberg/parse

Takes block markup and returns its structure. Useful for diagnosing a post that is already broken. Requires an API key but does not consume credits. Malformed markup returns 400 INVALID_BLOCK_MARKUP with the specific reason.

Supporting endpoints

GET /v1/download/:id

Serves a file produced with response_format: "url". No authentication — the UUID is the capability, so treat the link as a secret. Returns 404 once the 24 hours elapse.

GET /health

No authentication. Useful for monitoring.

{
  "status": "ok",
  "pandoc_available": true,
  "version": "3.1.3",
  "generation": { "active": 0, "queued": 0, "max_concurrency": 2, "max_queue": 50 }
}

Dashboard endpoints

The dashboard uses a session JWT rather than an API key: /v1/auth/me, /v1/auth/profile, /v1/keys (including /v1/keys/:id/rotate), /v1/usage and /v1/billing/*. You do not need any of them to generate documents.

Quick reference

POST https://api.searchops.io/v1/generate
  header  x-api-key: sk_live_…
  body    { content, input_type?, response_format?, filename?, options? }

input_type       markdown | html | json      default markdown   (alias: input)
response_format  base64 | url | file         default base64     (alias: format)
filename         1–120 chars, .docx added    default document.docx
content          required, ≤ 500 KB

GET  /v1/download/:id     24h link from response_format=url
GET  /health              status + conversion queue