Documentation
Caret speaks to a backend you control.
Caret is a compose surface for iOS: speak an intent at the cursor, preview, insert a finished message. Every request goes to the backend you configure — there is no mandatory first-party cloud. These pages document the wire contract between the Caret keyboard and any conforming backend.
Your Agent — implement the Caret APIcaret/v1
The complete contract for backend implementers and agents: base URL and
versioning, auth, Ask (/v1/draft) and
Imagine (/v1/imagine) with request/response
JSON, async polling, idempotency, the error envelope, and migration notes
from the legacy Klaw Keyboard shape.
The three modes
| Mode | What happens | Contract surface |
|---|---|---|
| Dictate | Speech → polished, insert-ready text. Audio is captured by the containing app, chunk-uploaded with SHA-256 verification, transcribed and cleaned server-side. | /v1/dictation/* |
| Ask | An instruction → one insert-ready message, drafted with whatever context your backend can reach. Always previewed before insertion. | /v1/draft |
| Imagine | A spoken or typed prompt → a generated image, delivered through the containing app and the pasteboard. | /v1/imagine |
Design principles of the contract
- Bring your own backend. The keyboard talks to the base
URL and API key configured in the Caret app. Any server that implements
caret/v1works — reference implementations exist, but none is privileged. - Stable error envelope. Every non-2xx response is
{"error": {"code", "message", "retryable"}, "request_id"}with an append-only code list. Clients act onretryablewhen they see an unknown code. - Idempotency everywhere. Mutating requests carry a
client-generated
client_request_id; replays return the original result and never re-run work. - Additive evolution. Unknown JSON fields are ignored on
both sides. Breaking changes require a new path version
(
/v2).
Hosted endpoints
Caret also operates a managed backend at
api.typewithcaret.com (hosted subscription tier, Dictate
only — Ask and Imagine are BYOB surfaces). Its health probe is public:
curl -s https://api.typewithcaret.com/v1/health