REST API · JavaScript SDK · Webhooks

Build translation
into your product

Every document translation feature in Vernacia is available via a production-ready REST API — the same one that powers the product itself. A JavaScript/TypeScript SDK is in private beta for early access.

Key concepts

Three primitives to learn

The Vernacia API is intentionally small. Learn these three resources and you can drive every feature in the product.

Projects

A project owns a source and target language plus its Translation Memory. One project per localization job (e.g., 'German website launch').

Jobs

A job is one file being translated. Submit a job with a file ID, poll for progress, download the translated file when done.

Translation Memory

Every AI translation is saved per project. The next job reuses approved translations — consistency across documents, zero token cost for repeats.

Project
Upload
Job
Translation Memory

Every completed job feeds Translation Memory back into the project — the next job in the same language pair reuses approved translations automatically.

Authentication

Two ways to authenticate

Pick the method that matches your integration. Both grant access to the same endpoints — the difference is who is acting on whose behalf.

JWT

End-user auth

For apps where a human user logs into your frontend. Exchange email/password (or an OAuth flow) for an access token, then attach it to each SDK call.

jwt-auth.ts
import { VernaciaClient } from '@vernacia/sdk-js';

const { accessToken } = await fetch('/auth/login', {
  method: 'POST',
  body: JSON.stringify({ email, password }),
}).then((r) => r.json());

const client = new VernaciaClient({
  accessToken: '...jwt...',
});

API Key

Server-to-server

For backend integrations, cron jobs, and CI pipelines. API keys are long-lived credentials scoped to one workspace. Never ship them to the browser.

api-key.ts
import { VernaciaClient } from '@vernacia/sdk-js';

const client = new VernaciaClient({
  apiKey: process.env.VERNACIA_API_KEY,
  // apiKey: 'vnc_live_...'
});

const me = await client.users.me();
console.log(me.email);

Get an API key in Settings → API Keys.

Quickstart

Your first translation in 60 seconds

Install the SDK, create a client, and translate your first string using the free tools API — no authentication required to get started.

SDK is in private beta

@vernacia/sdk-js is not yet published to npm. Email [email protected] to request access. The REST endpoints below are live today and can be called directly with any HTTP client.

1

Install

install.sh
# Coming soon: npm install @vernacia/sdk-js
2

Translate

quickstart.ts
# import { VernaciaClient } from '@vernacia/sdk-js'; // private beta

# No account needed — try the free-tool endpoints directly:
curl -X POST https://api.vernacia.ai/v1/tools/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, world!","source":"en","target":"de"}'
# => { "translation": "Hallo, Welt!" }

# Full document translation is live via REST today:
curl -X POST https://api.vernacia.ai/v1/projects \
  -H "X-API-Key: vnc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"German website launch","sourceLang":"en","targetLang":"de"}'

curl -X POST https://api.vernacia.ai/v1/projects/:projectId/files/upload \
  -H "X-API-Key: vnc_live_..." \
  -F "file=@./q4-deck.pptx"

curl -X POST https://api.vernacia.ai/v1/projects/:projectId/files/:fileId/translate \
  -H "X-API-Key: vnc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"sourceLang":"en","targetLang":"de"}'
# => 202 Accepted, poll GET /jobs/:id until status is "DONE",
#    then GET /jobs/:id/download

That's it. The tools/* endpoints mirror every free tool on the site — no auth required. Authenticated REST endpoints unlock project management, file upload, job tracking, and glossary sync today; the SDK wraps the same calls once it leaves private beta.

REST endpoints

The full surface area

Every SDK method maps one-to-one to a REST endpoint. Use the SDK for convenience or call the API directly with any HTTP client.

Projects

Auth: JWT or API key
POST/projectsCreate a new translation project
GET/projectsList all projects owned by the caller
GET/projects/:idFetch a single project with its settings
DELETE/projects/:idDelete a project and its Translation Memory

Files

Auth: JWT or API key
POST/projects/:projectId/files/uploadUpload a document (multipart/form-data) to a project
POST/projects/:projectId/files/upload-batchUpload multiple documents in a single request
GET/projects/:projectId/files/:fileId/validatePre-flight check: page count, credit cost, and format support
POST/projects/:projectId/files/:fileId/translateQueue a translation job for an uploaded file — accepts sourceLang, targetLang, model, tone, outputMode
GET/projects/:projectId/files/:fileId/jobsList every translation job (version history) for a file
DELETE/projects/:projectId/files/:fileIdDelete an uploaded file and its outputs

Jobs

Auth: JWT or API key
GET/jobsList translation jobs for the caller
GET/jobs/:idFetch job status, progress, and metadata — use this one
GET/jobs/:id/statusDeprecated alias of /jobs/:id, kept for backwards compatibility
GET/jobs/:id/streamServer-Sent Events stream of job progress until terminal
GET/jobs/:id/downloadDownload the translated output file
POST/jobs/:id/retryRetry a failed job with the same input

Glossary

Auth: JWT or API key
GET/projects/:id/glossaryList glossary terms for a project
POST/projects/:id/glossaryAdd a new glossary term pair
POST/projects/:id/glossary/auto-extract/:jobIdAuto-extract glossary candidates from a completed job
GET/projects/:id/glossary/export?format=csv|tmxExport glossary as CSV or TMX
POST/projects/:id/glossary/importImport glossary from a CSV or TMX file

Webhooks

Auth: JWT or API key
GET/webhooks/endpointsList configured webhook endpoints
POST/webhooks/endpointsCreate a webhook endpoint (returns signing secret once)
PATCH/webhooks/endpoints/:idUpdate endpoint URL, events, or enabled state
DELETE/webhooks/endpoints/:idRemove an endpoint and its delivery history
POST/webhooks/endpoints/:id/rotate-secretRotate the signing secret
POST/webhooks/endpoints/:id/testSend a test event to the endpoint
GET/webhooks/endpoints/:id/deliveriesList recent delivery attempts
POST/webhooks/endpoints/:id/deliveries/:deliveryId/retryManually retry a failed delivery (20/min)

Users

Auth: JWT or API key
GET/users/meFetch the authenticated user profile

Free Tools

No auth
POST/tools/translateTranslate a short block of text
POST/tools/detect-languageDetect the language of any text snippet
POST/tools/extract-termsExtract key terminology from text

Premium

Auth: PRO+
POST/translation/tools/cultural-adaptFlag idioms, tone, and cultural issues for a target market
POST/translation/tools/compare-modelsRun the same prompt through multiple AI models

Full request/response schemas, error codes, and a try-it console live in the interactive API reference.

Rate limits

Fair limits — with headroom

All limits are enforced per user (or per IP for anonymous endpoints) with a sliding-window algorithm. Every 429 response includes Retry-After and X-RateLimit-Reset headers so you can back off gracefully.

Full limits in the API reference

Free tool endpoints

10–20 req/min per IP

Authenticated endpoints

60–120 req/min per user

Premium AI tools

15–30 req/min per user

File uploads

10 uploads/min per user · max file size by plan: 10 MB (Starter), 50 MB (Pro), 200 MB (Enterprise)

SDKs

Use your language of choice

JavaScript/TypeScript is in private beta today. Python is in active development. We're listening to the community on what comes next.

Private beta

JavaScript / TypeScript

Zero runtime dependencies. ESM + CJS. Ships with full TypeScript definitions generated from the OpenAPI schema. Email us for private-beta access.

[email protected]Request beta access
Coming soon

Python

A Pythonic client with async/await support and typed response models. Targeting general availability in the next release.

pip install vernaciaGet notified
Coming soon

Go

An idiomatic Go client with context support and typed response structs. Email us to upvote or contribute.

go get github.com/cloudserveinfotech/vernacia-goGet notified

Building something?

We love seeing what people build on top of the Vernacia API. Hit us up with architecture questions, feature requests, or just a demo — we genuinely enjoy helping developers ship.

[email protected]
Production-ready

Ship with confidence

The API that powers the Vernacia product is the same one you're building against. Every endpoint is monitored, rate-limited, and audit-logged.

GDPR readySOC 2 in progressHIPAA on roadmap99.9% uptime target
Create a free account — get your API key