Bouw voort op de publieke API's van Coptic Compass

De publieke API-laag omvat de alleen-lezen grammaticadataset, genormaliseerde woordenboekzoekfunctie, Shenute AI-providerroutering en een OCR-proxy voor afbeelding- of documentuploads.

Begin hier

De meeste integraties starten best bij het OpenAPI-document, waar de publieke services en requestvormen worden beschreven.

Open API-docs Bekijk OpenAPI JSON /api/v1/grammar /api/v1/dictionary/search

Typische workflow

Gebruik /api/openapi.json om de contracten voor alle vier publieke services te bekijken.
Roep /api/v1/grammar aan om grammatica-endpoints en datasetversie te ontdekken.
Gebruik /api/v1/grammar/lessons voor de index van gepubliceerde lessen.
Query /api/v1/dictionary/search voor gepagineerde woordenboekresultaten.
Gebruik /api/v1/dictionary/search-index wanneer een beperkte volledige woordenboekindex nodig is.
Verstuur POST /api/shenute voor Shenute AI-antwoorden (standaardprovider: thoth).
Stuur OCR-requests voor afbeeldingen naar POST /api/ocr zodat Coptic Compass ze doorstuurt naar OCR_SERVICE_URL.

Belangrijke endpoints

Ontwikkelaars

/api/v1/grammar

Ontdekkingsindex voor de publieke grammatica-API.

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

Index van gepubliceerde lessen voor publieke integraties.

/api/v1/grammar/manifest

Manifest met datasetmetadata en aantallen.

/api/openapi.json

Machineleesbaar OpenAPI-document.

/api/v1/dictionary/search

Gepagineerde genormaliseerde woordenboekzoekfunctie met query-, dialect-, woordsoort-, exact-match- en pagineringsfilters.

/api/v1/dictionary/search-index

Beperkte woordenboekindex voor clientzoekfunctie en analytische drilldowns.

/api/shenute

Shenute AI-endpoint met providerkeuze en fallback-afhandeling.

/api/ocr

OCR-proxyendpoint dat afbeelding-uploads doorstuurt naar OCR_SERVICE_URL.

Integratienotities

Grammaticaresponses zijn alleen-lezen en bevatten schemaVersion, datasetVersion en generatedAt.
De publieke dataset bevat alleen gepubliceerde lessen en de bijbehorende begrippen, voorbeelden, oefeningen, voetnoten en bronnen.
De lesson-filter accepteert zowel een slug als een canonieke les-id.
Woordenboekzoekopdrachten accepteren q, dialect, partOfSpeech, exact, limit en offset als filters.
Woordenboekpayloads zijn genormaliseerd en bevatten geen ruwe of alleen-bronvelden.
Voor browser-apps op een andere origin is een backendproxy de veiligste standaardoptie.
Shenute AI ondersteunt providers: thoth, openrouter, gemini en hf.
Bij upload van afbeeldingen of cameracaptures draait OCR eerst; de geëxtraheerde tekst wordt toegevoegd onder [Image OCR Context] vóór de call naar /api/shenute.
Stel OCR_SERVICE_URL in en optioneel OCR_UPLOAD_FIELD als uw OCR-backend een vaste multipart-veldnaam vereist.
Het endpoint /api/ocr proxyt multipart OCR-uploads en geeft het upstream OCR-resultaat terug aan de client.

Voorbeeldrequest

Een minimale server-side fetch-aanroep die de titels van gepubliceerde lessen ophaalt.

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);

Voorbeeld woordenboekzoekopdracht

Een gepagineerde woordenboekzoekopdracht beperkt tot het Bohairisch.

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];

Verwante bronnen

Swagger UI

Interactieve referentie om alle endpoints te verkennen.

OpenAPI JSON

Importeer in Postman, SDK-generators of interne tooling.

Grammatica-API-index

Lees de mogelijkheden van de grammaticadataset en voorbeeldroutes voor grammatica.

Woordenboekzoek-API

Zoek genormaliseerde Koptische woordenboeklemma's op Koptisch, Engels, Nederlands, Grieks, dialect en woordsoort.

Grammatica-overzicht

Bekijk de publieke inhoud die de API ontsluit.

Shenute AI

Referentie-UI met providerkeuze en OCR-ondersteunde afbeeldings- en cameraberichten.

OCR-proxyendpoint

Verstuur multipart OCR-requests zonder uw upstream OCR-service-URL te publiceren.

Voorbeeld Shenute AI-request

Een minimale POST-request naar /api/shenute met THOTH AI als 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-integratienotities

Clients kunnen /api/ocr aanroepen; Coptic Compass stuurt door naar OCR_SERVICE_URL en geeft de upstream OCR-response terug.

# .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