canonical: https://jentic.com/apis/markup.ai/markup-ai

# Markup AI API

Jentic publishes the only available OpenAPI specification for Markup AI API, keeping it validated and agent-ready. Markup AI provides programmatic access to AI-driven content quality tooling, including configurable style guides, automated style checks, suggestion generation, and full text rewrites. Each writing operation runs as a workflow with a polling interface, allowing long-form documents to be analysed asynchronously. The API is intended for content platforms, documentation tools, and AI agents that need to enforce brand voice or grammar rules at scale.

## For AI agents

Run AI-driven style checks, generate suggestions, and produce full rewrites of source text against a configurable style guide via async workflow endpoints.

## Scope

Does not handle text generation from scratch, translation, or text-to-speech - use for style checks, writing suggestions, and rewrites against a configured style guide only.

## Capabilities

- Create and manage style guides that encode brand voice and grammar rules
- Submit text to async style checks and poll workflow IDs for completion
- Generate inline writing suggestions tied to specific style-guide rules
- Produce full document rewrites that conform to a chosen style guide
- Retrieve workflow results once a check, suggestion, or rewrite job finishes
- Iterate on style-guide rules and re-run checks against the same source content

## Use cases

### Editorial Quality Gate

Content teams running marketing or documentation pipelines need an automated quality gate before publishing. Markup AI accepts the source text, runs it against a configured style guide, and returns a workflow ID that the publishing system polls until results are ready. Typical articles complete in 5-30 seconds depending on length.

Example prompt: Submit a 1500-word article to `POST `/v1/style/checks`` with style_guide_id 'sg_brand_voice', then poll `GET `/v1/style/checks/{workflow_id}`` until status is complete.

### AI-Assisted Rewrites in CMS

A CMS plugin can offer one-click 'rewrite to brand voice' on a draft. Markup AI's rewrites endpoint takes the draft plus a style guide ID and returns a full rewritten version. The async workflow model handles long documents without keeping HTTP connections open. Editors review the diff before publishing.

Example prompt: Call `POST `/v1/style/rewrites`` with the draft body and style_guide_id, then fetch the rewritten text from `GET `/v1/style/rewrites/{workflow_id}``.

### Inline Style Suggestions

Authoring tools and email clients can surface inline suggestions as the user types. Markup AI's suggestions endpoint returns rule-tagged change recommendations (e.g., 'shorten this sentence', 'use active voice') so the UI can present accept/reject affordances with rationale.

Example prompt: Submit a paragraph to `POST `/v1/style/suggestions`` with the user's style guide and return the per-sentence suggestions list.

### AI Agent Content Polish

An AI agent that drafts customer emails or knowledge base articles can use Jentic to call Markup AI as a final polish step. Jentic stores the bearer token securely and exposes the style-check, suggestion, and rewrite operations through intent search, so the agent picks the right one without hard-coding endpoint paths.

Example prompt: Search Jentic for 'rewrite content to brand voice', load the Markup AI rewrite schema, and execute it on the draft email before sending.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/style-guides` | List configured style guides |
| GET | `/v1/style-guides/{style_guide_id}` | Fetch a specific style guide |
| POST | `/v1/style/checks` | Submit text for an async style check |
| GET | `/v1/style/checks/{workflow_id}` | Poll a style-check workflow result |
| POST | `/v1/style/suggestions` | Generate inline writing suggestions |
| POST | `/v1/style/rewrites` | Request a full text rewrite |
| GET | `/v1/style/rewrites/{workflow_id}` | Retrieve rewrite workflow output |

## Key resources

- **Style Guides** — Create, list, fetch, and update style guides that define brand voice and grammar rules.
- **Style Checks** — Run async style-conformance checks against source text and retrieve results.
- **Suggestions** — Generate inline rule-tagged writing suggestions for source text.
- **Rewrites** — Produce full rewritten versions of source text aligned to a style guide.
- **Workflows** — Async workflow handles for tracking long-running check, suggestion, and rewrite jobs.

## Why Jentic

- **Setup:** Wiring Markup AI by hand means setting its bearer auth, learning the /v1 style-guide, check, suggestion, and rewrite endpoints, and polling the workflow ids yourself. Through Jentic you install once, import the Markup AI API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Scoping is by operation: you limit the agent to the operations it needs, such as running a style check, requesting suggestions, or fetching a rewrite result, and leave out anything you do not want it calling. Every operation you allow is one you have chosen, so the agent stays inside that set.
- **Credential handling:** Your Markup AI bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'check writing against a style guide' or 'rewrite content to brand voice', and Jentic returns the matching Markup AI operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **LanguageTool API** — LanguageTool is an open grammar and style checker API focused on rule-based corrections.
- **OpenAI API** — OpenAI's chat completions can perform free-form rewrites with prompt-based style instructions.
- **Anthropic Claude API** — Claude is often used to draft content that is then polished by a style-guide tool.

## FAQ

### Why is there no official OpenAPI spec for Markup AI API?

Markup AI does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the Markup AI API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Markup AI API use?

Markup AI uses HTTP bearer-token authentication. Through Jentic, the bearer token is stored encrypted in your Jentic One instance and the `Authorization: Bearer ...` header is set automatically at execution time.

### Can I check content against a custom style guide with the Markup AI API?

Yes. Create a style guide via the `/v1/style-guides` endpoints, then pass its ID to `POST `/v1/style/checks`` along with the source text. The check runs asynchronously and the result is fetched from `/v1/style/checks/{workflow_id}`.

### What are the rate limits for the Markup AI API?

Markup AI does not publish hard rate limits in the spec. Style operations are async workflows so concurrency is naturally bounded - treat 5-10 concurrent in-flight workflows per account as a safe default and back off on 429 responses.

### How do I rewrite a document to match a style guide through Jentic?

Run `pip install jentic`, then use Jentic's search with the query 'rewrite content to brand voice'. Jentic loads the `/v1/style/rewrites` schema and your agent executes it with the document and style_guide_id, then polls `/v1/style/rewrites/{workflow_id}` for the result.

### Are checks, suggestions, and rewrites synchronous or asynchronous?

All three follow the async workflow pattern: the POST returns a workflow_id, and the matching `GET /{workflow_id}` endpoint is polled until the workflow completes. This lets long documents finish without HTTP timeouts.

### Can I limit what my agent is allowed to do with the Markup AI API?

Yes. Because Jentic One is self-hosted, you run it and your own rules decide which Markup AI operations and credentials the agent may use. Scoping is by operation, so you can allow only the calls the agent needs, such as running a style check with POST `/v1/style/checks` or fetching a rewrite result from GET `/v1/style/rewrites/{workflow_id}`, and leave out anything else like creating or updating style guides. Every operation the agent can call is one you have explicitly chosen, and your bearer token is injected at execution time rather than exposed to the agent.