Build on Coptic Compass public APIs

The public API surface includes the read-only grammar dataset, normalized dictionary search, Shenute AI provider routing, and an OCR proxy for image or document uploads.

Start here

Most integrations should begin with the OpenAPI document, which describes the available public services and their request shapes.

Open API Docs View OpenAPI JSON /api/v1/grammar /api/v1/dictionary/search

Typical workflow

Use /api/openapi.json to inspect contracts for all four public services.
Call /api/v1/grammar to discover grammar endpoints and dataset version.
Fetch /api/v1/grammar/lessons for the published lesson index.
Query /api/v1/dictionary/search for paginated dictionary results.
Use /api/v1/dictionary/search-index when a reduced full dictionary index is needed.
Send POST /api/shenute requests for Shenute AI responses (default provider: thoth).
Send image OCR requests to POST /api/ocr so Coptic Compass forwards them to OCR_SERVICE_URL.

High-value endpoints

Developers

/api/v1/grammar

Discovery index for the public grammar API.

/api/v1/grammar/lessons?status=published

Published lesson index for public integrations.

/api/v1/grammar/manifest

Manifest with dataset-level metadata and counts.

/api/openapi.json

Machine-readable OpenAPI document.

/api/v1/dictionary/search

Paginated normalized dictionary search with query, dialect, part-of-speech, exact-match, and pagination filters.

/api/v1/dictionary/search-index

Reduced dictionary index for client search and analytics drilldowns.

/api/shenute

Shenute AI endpoint with provider routing and fallback handling.

/api/ocr

OCR proxy endpoint that forwards image uploads to OCR_SERVICE_URL.

Integration notes

Grammar responses are read-only and versioned with schemaVersion, datasetVersion, and generatedAt metadata.
The public dataset only exposes published lessons and their related concepts, examples, exercises, footnotes, and sources.
The lesson filter accepts either a lesson slug or a canonical lesson id.
Dictionary search accepts q, dialect, partOfSpeech, exact, limit, and offset filters.
Dictionary payloads are normalized and do not include raw/source-only fields.
For browser apps on another origin, a backend proxy is the safest default.
Shenute AI supports provider values: thoth, openrouter, gemini, and hf.
Image upload and camera capture flows run OCR first and append extracted text under [Image OCR Context] before calling /api/shenute.
Set OCR_SERVICE_URL and optionally OCR_UPLOAD_FIELD when your OCR backend requires a specific multipart field name.
The /api/ocr endpoint proxies multipart OCR uploads and returns upstream OCR responses to the client.

Example request

A minimal server-side fetch that lists published lesson titles.

const response = await fetch(
  "https://www.copticcompass.com/api/v1/grammar/lessons",
);

const payload = await response.json();
const lessonTitles = payload.data.map((lesson) => lesson.title.en);

Dictionary search example

A paginated dictionary search request scoped to the Bohairic dialect.

const response = await fetch(
  "https://www.copticcompass.com/api/v1/dictionary/search?q=ⲙⲟⲓ&dialect=B&limit=10",
);

const page = await response.json();
const firstEntry = page.entries[0];

Related resources

Swagger UI

Interactive reference for exploring every endpoint.

OpenAPI JSON

Import into Postman, SDK generators, or internal tooling.

Grammar API index

Read grammar dataset capabilities and example grammar routes.

Dictionary search API

Search normalized Coptic dictionary entries by Coptic, English, Dutch, Greek, dialect, and part of speech.

Grammar hub

See the public content the API is exposing.

Shenute AI

Reference UI for provider selection plus OCR-backed image and camera messaging.

OCR proxy endpoint

Send multipart OCR requests without exposing your upstream OCR service URL.

Shenute AI request example

A minimal POST request to /api/shenute using THOTH AI as provider.

const response = await fetch("https://www.copticcompass.com/api/shenute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    inferenceProvider: "thoth",
    messages: [
      {
        id: "u1",
        role: "user",
        parts: [{ type: "text", text: "Translate this Coptic sentence." }],
      },
    ],
  }),
});

const streamOrText = await response.text();

OCR integration notes

Clients can call /api/ocr, and Coptic Compass forwards to OCR_SERVICE_URL then returns the upstream OCR response.

# .env.local
OCR_SERVICE_URL=https://your-ocr-service/upload
# Optional for strict OCR backends:
OCR_UPLOAD_FIELD=file

curl -X POST "https://www.copticcompass.com/api/ocr?lang=cop" \
  -F "file=@/path/to/coptic-image.jpg"

# Proxy OCR flow
# 1) client POSTs to /api/ocr
# 2) server forwards to OCR_SERVICE_URL
# 3) upstream OCR response is returned to the client