HTTP API reference

The API speaks JSON over HTTPS. All the shapes on this page ship as TypeScript types in @amber-pen/sdk, which also handles serialization and error mapping for you.

Authentication and key types

Send either key type as Authorization: Bearer <api-key>. Live ap_live_v1 keys require an active subscription. Verified accounts can create one ap_test_v1 key for free; it calls the same endpoint and returns the same response shapes.

Test-key allowance is shared across the account:

• 20 requests per minute
• 1,000 weighted input characters per request, including dictionary and proper-noun entries
• 200 request units and 50,000 weighted input characters per UTC day

An evaluate request consumes two request units and twice its weighted input length. Successful responses expose minute limits in RateLimit-* headers and daily allowance in X-Test-Daily-* headers. See Testing for free for the complete setup and quota guide.

POST /proofread

Proofreads text and returns the edits needed to construct the corrected version.

curl https://api.amberpen.dev/proofread \
	-H "authorization: Bearer $AMBER_PEN_API_KEY" \
	-H "content-type: application/json" \
	-d '{ "text": "This are a sentnce by AmberPen and cachebuster.", "dictionary": ["cachebuster"], "properNouns": ["AmberPen"] }'

Request body

textId is not a request field: incremental proofreading is handled by the SDK for both proofread and proofreadStream. The SDK diffs the text in your process, strips the identifier, and sends only the chunks that changed. A direct HTTP request body containing textId is rejected with a 400.

Response

Both modes return an edits array. Correct mode returns plain edits:

{
	"mode": "correct",
	"processingTimeMs": 217,
	"edits": [
		{ "id": 0, "start": 5, "end": 8, "original": "are", "replacement": "is" },
		{ "id": 1, "start": 11, "end": 18, "original": "sentnce", "replacement": "sentence" }
	]
}

In evaluate mode the second pass has already reviewed each proposed edit, so the array only contains edits worth applying, and every edit adds three fields: possibleReplacements ranked by relevance, a category, and a one-sentence explanation written in the language of the submitted text.

{
	"mode": "evaluate",
	"processingTimeMs": 434,
	"edits": [
		{
			"id": 0,
			"start": 5,
			"end": 8,
			"original": "are",
			"replacement": "is",
			"possibleReplacements": ["is"],
			"category": "grammar",
			"explanation": "The singular subject “This” takes “is”."
		},
		{
			"id": 1,
			"start": 11,
			"end": 18,
			"original": "sentnce",
			"replacement": "sentence",
			"possibleReplacements": ["sentence", "sentience"],
			"category": "spelling",
			"explanation": "“sentnce” is misspelled."
		}
	]
}

Streaming response

With stream: true, the response uses application/x-ndjson. Every non-empty line is a complete edit array with offsets into the full submitted text. Correct mode emits TextEdit[]. Evaluate mode collects correction proposals in document order, evaluates them five at a time, and emits complete EvaluatedEdit[] batches. A final empty array marks successful completion. Use the SDK's proofreadStream method to parse transport fragments, validate batches, and detect truncated streams.

curl -N https://api.amberpen.dev/proofread \
	-H "authorization: Bearer $AMBER_PEN_API_KEY" \
	-H "content-type: application/json" \
	-H "accept: application/x-ndjson" \
	-d '{ "text": "This are a sentnce.", "mode": "correct", "stream": true }'

[{"id":0,"start":5,"end":8,"original":"are","replacement":"is"}]
[{"id":1,"start":11,"end":18,"original":"sentnce","replacement":"sentence"}]
[]

Edits

The SDK's applyEdits(text, edits) reconstructs the corrected text from a response's edits.

GET /health

Returns { "status": "ok" } when the API is ready to receive requests. No authentication required.

Errors

Failures return a JSON body with a human-readable message:

{
	"error": "Field 'text' must be a string"
}

A failure that interrupts a stream is delivered as a JSON object on its own NDJSON line rather than as an HTTP status, and that object carries a stable code. The terminal empty array is not sent, so a stream that ends without one has failed.

{"error":"Service unavailable, please try again later or contact our support at contact@amberpen.dev","code":"provider_error"}