Run Style Agent File

# PDF, Word (.docx), HTML, DITA, Markdown, and plain text are
# accepted, up to 7 MB. The file is checked as submitted — the
# text is extracted server-side.
#
# Only file_upload is required, and every other field is a form
# field, not JSON. Repeat -F "domain_ids=..." per terminology domain.
#
# Each issue's position (start/end) indexes the extracted text,
# not the bytes you uploaded, so the offsets will not line up
# with your source file. Use position.text for the flagged span,
# or context_surface for the surrounding text, to locate it in
# the original document.
curl -X POST "https://api.markup.ai/style-agent/run-file?wait=true" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file_upload=@/path/to/your/file.pdf" \
  -F "style_guide_id=YOUR_STYLE_GUIDE_ID" \
  -F "content_profile_id=YOUR_CONTENT_PROFILE_ID" \
  -F "document_ref=handbook/chapter-3" \
  -F "document_name=Employee Handbook" \
  -F "domain_ids=YOUR_DOMAIN_ID"

{
  "workflow_id": "string",
  "status": "running",
  "started_at": "2024-01-15T09:30:00Z",
  "request_id": "string",
  "document_ref": "string",
  "check_type": "interactive",
  "assigned": true,
  "batch_id": "string",
  "result": {
    "analysis": {
      "styleGuideId": "string",
      "styleGuideDisplayName": "string",
      "contentProfileId": "string",
      "contentProfileDisplayName": "string",
      "words": 1,
      "sentences": 1,
      "clarityIndex": 1.1,
      "informalityIndex": 1.1,
      "livelinessIndex": 1.1,
      "fleschReadingEase": 1.1,
      "targetId": "string",
      "targetDisplayName": "string"
    }
  },
  "completed_at": "2024-01-15T09:30:00Z",
  "duration_seconds": 1.1
}

Run a Style Agent check on an uploaded document.

Accepts PDF, Word (.docx), HTML, DITA, Markdown, and plain-text files. The file is uploaded unchanged and its text extracted for you, so the check runs against the document as submitted.

Behaves like POST /style-agent/run otherwise: wait=true blocks for the result (201 Created), the default returns 202 Accepted with a workflow id to poll via GET /style-agent/workflows/{workflow_id}. A large file can take longer than the synchronous request window, so prefer polling for those.

Issue positions index the extracted text, not the bytes you uploaded; use each issue’s context_surface to locate it in the original document.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

waitbooleanOptionalDefaults to false

Request

This endpoint expects a multipart form containing a file.

style_guide_idstring or nullOptional>=1 character

Style guide ID to check the document against. target_id is a deprecated alias for this field; send exactly one of the two names.

content_profile_idstring or nullOptional>=1 character

Language-service content profile ID for style checking.

domain_idslist of strings or nullOptional

Terminology domain IDs.

document_refstring or nullOptional1-512 characters

Caller-provided document identifier for tracking across scans.

urlstring or nullOptional>=1 character

Document URL.

document_namestring or nullOptional>=1 character

Document name or title.

webhook_urlstring or nullOptionalformat: "uri"1-2083 characters

Optional webhook URL for async result delivery.

file_uploadfileRequired

The document to analyze. Text (.txt), Markdown (.md), HTML (.html .htm), DITA (.dita, .xml), Word (.docx), and PDF (.pdf) files are accepted. The max file size is 7 MB.

Response

Successful Response

workflow_idstring

Workflow ID for tracking

statusenum

Workflow status

Allowed values:

started_atdatetime

Workflow start time

request_idstring or nullOptional

Request tracking ID

document_refstring or nullOptional

Caller-provided document identifier.

check_typeenumOptional

How this check is counted: 'batch' for a document checked as part of a batch, 'interactive' for a direct /run check.

Allowed values:

assignedbooleanOptionalDefaults to true

Whether the check counts as authoring activity for an author.

batch_idstring or nullOptional

Owning batch id (agbw_<nanoid>); null unless this is a batch check.

resultobject or nullOptional

Execution result (if completed)

completed_atdatetime or nullOptional

Workflow completion time

duration_secondsdouble or nullOptional

Execution duration

Errors

401

Unauthorized Error

403

Forbidden Error

413

Content Too Large Error

422

Unprocessable Entity Error

500

Internal Server Error