API Reference

Complete documentation for the Francis API. All endpoints are hosted at https://francis.verbatims.cc/api/v1.

Authentication

All API requests require an API key passed via the x-api-key header or Authorization: Bearer header. Keys are prefixed with fcs_ and managed through the dashboard.

Headershttp

# Recommended
x-api-key: fcs_a1b2c3d4...

# Alternative
Authorization: Bearer fcs_a1b2c3d4...

Endpoints

POST/api/v1/detect

Detect the language of a text string. Uses franc-all under the hood for trigram-based detection. Returns an ISO 639-3 language code, confidence score, and alternative candidates.

Request body

textrequired

string

The text to detect.

minLengthoptional

number

Minimum text length for reliable detection. Default 10.

onlyoptional

string[]

Restrict detection to specific ISO 639-3 language codes.

Response

language

string

ISO 639-3 code (eng, fra) or und for undetermined.

score

number

Raw franc score (lower is better).

confidence

number

Computed confidence from 0 to 1 based on score gap and text length.

alternatives

Array<{language, score}>

Top 5 alternative candidates.

Example request

bashbash

$ curl -X POST 'https://francis.verbatims.cc/api/v1/detect'
  -H 'x-api-key: fcs_...'
  -d '{"text": "Bonjour le monde"}'

{ "language": "fra", "confidence": 0.98, "alternatives": ["ita", "spa"] }

POST/api/v1/translate

Translate text into one or more target languages. Uses OpenRouter multi-model AI with automatic fallback. Supports batch translation of up to 10 texts.

Request body

textrequired

string | string[]

Text to translate, or an array of up to 10 texts. Each capped at 5,000 characters.

targetrequired

string | string[]

ISO 639-1 language code(s). Max 10 targets per request.

sourceoptional

string

Source language hint (ISO 639-1). If omitted, the source is auto-detected.

Response

translations

Array

Each entry contains target, text, and optionally detectedSource.

model

string

The OpenRouter model used for translation.

Example request

bashbash

$ curl -X POST 'https://francis.verbatims.cc/api/v1/translate'
  -H 'x-api-key: fcs_...'
  -d '{"text": "Good morning", "target": ["fr", "de"]}'

GET/api/v1/health

Health check endpoint. No authentication required. Returns service status and current timestamp.

Response

boolean

service

"francis"

timestamp

number

GET/api/v1/usage

Retrieve usage statistics for a specific API key. Requires session-based authentication (dashboard login). Returns daily request counts for the last 60 days.

Query parameters

apiKeyIdrequired

string

The API key ID to query.

Error codes

400

Bad Request

Missing or invalid parameters. Check your request body.

401

Unauthorized

Missing or invalid API key.

403

Forbidden

You do not have permission to access this resource.

404

Not Found

The requested resource was not found.

429

Rate Limited

Daily usage cap exceeded. Try again tomorrow or increase your limit.

502

Bad Gateway

Translation failed — all AI models returned errors.

503

Service Unavailable

Service not configured or temporarily unavailable.