Question 1

Wat is de Cathopic API?

Accepted Answer

Onze API is een RESTful-service waarmee je de katholieke mediabibliotheek van Cathopic rechtstreeks in je toepassingen kunt integreren. Toegang tot duizenden afbeeldingen, video’s en grafische materialen via programmering. Wat je kunt doen Zoeken en browsen door onze volledige catalogus Licentiebronnen voor je eindgebruikers automatisch Downloaden in meerdere formaten geoptimaliseerd voor verschillende gebruikssituaties Toegang tot rijke metadata inclusief tags, beschrijvingen en liturgische informatie REST-architectuur Gebouwd op standaard REST-principes: Basis-URL: https://api.cathopic.com Datumnformaat: JSON-verzoeken en -antwoorden Authenticatie: API-sleutel via x-api-key header HTTP-methode: POST voor alle endpoints Vier kern-endpoints POST /resources - Zoek in de catalogus POST /resource - Haal details op over een specifiek item POST /confirm - Licentieer een bron en ontvang download-URL’s POST /remove - Stop met licentiëring wanneer het niet langer nodig is (alleen website) Volledige documentatie Alles wat je nodig hebt is online beschikbaar: Interactieve API-referentie: api.cathopic.com/docs Codevoorbeelden in meerdere talen Gedetailleerde specificaties van parameters Aan de slag Neem contact op met ons team om API-toegang aan te vragen Genereer je API-sleutel in Instellingen → API Voeg een betaalmethode toe voor gebruiksverrekening Begin met bouwen Bekijk de andere vragen in deze sectie voor details over authenticatie, facturering en best practices. API-licentieovereenkomst Alle API-gebruik is onderworpen aan onze API-licentieovereenkomst. Belangrijke punten om te begrijpen: Alleen digitaal gebruik: Inhoud mag alleen worden weergegeven in web- en e-mailomgevingen Geen bestandsdownloads: Eindgebruikers kunnen de originele bestanden niet downloaden of exporteren Verboden gebruik: AI/ML-training, printmateriaal en offline gebruik zijn strikt verboden Facturering op basis van gebruik: Betaal alleen voor daadwerkelijk contentgebruik door je eindgebruikers Door de API te gebruiken, accepteer je alle voorwaarden in de licentieovereenkomst Voordat je de API integreert: Bekijk de volledige API-licentieovereenkomst Begrijp de beperkingen en verplichtingen Zorg ervoor dat je gebruikssituatie voldoet aan de vereisten voor alleen digitaal Plan je integratie om gebruik nauwkeurig bij te houden voor facturering Voor meer details, zie: Wat kan ik bouwen met de API? (inclusief gedetailleerde beperkingen) Hoe werken licenties via de API? (volledige licentiedetails) Hoe wordt API-gebruik gefactureerd? (uitleg van het factureringsmodel)

Question 2

Wat kan ik bouwen met de API?

Accepted Answer

De Cathopic API stelt je in staat om katholieke visuele content direct te integreren in je applicatie, website of platform. Het gebruik van de API wordt echter strikt geregeld door onze API-licentieovereenkomst, die het gebruik beperkt tot specifieke digitale omgevingen. Wat je kunt bouwen Beheer- en administratiesystemen voor kerk en parochie Laat parochies katholieke afbeeldingen toevoegen aan hun kerkbulletins en nieuwsbrieven Maak het mogelijk om evenementen te promoten met relevante visuele content Voorzie liturgische afbeeldingen die aansluiten bij de kerkelijke kalender Maak digitale displays voor parochiale aankondigingen Platformen voor katholieke content Bouw blogplatforms voor katholieke schrijvers met geïntegreerde afbeeldingen Ontwikkel katholieke nieuwssites met relevante visuals Ontwikkel devotie-apps met dagelijkse afbeeldingen en gebeden Ontwerp catechetische platformen met visuele onderwijsmiddelen Hulpmiddelen voor e-mailmarketing Laat pastorale diensten nieuwsbrieven maken met katholieke afbeeldingen Maak het mogelijk voor religieuze organisaties om e-mailcampagnes te ontwerpen Voorzie templates met geïntegreerde Cathopic-content Ondersteun fondsenwervingscampagnes met passende visuals Websitebouwers en CMS Integreer katholieke afbeeldingen in websitebouwplatforms Lever contentmodules voor katholieke organisaties Schakel slepen-en-neerzetten in voor het selecteren van afbeeldingen uit Cathopic Maak templates die specifiek zijn voor katholieke pastorale diensten Beheer van evenementen en sociale media Help pastorale diensten socialmediagrafieken te maken (zonder bestanden te downloaden) Ontwerp systemen voor evenementuitnodigingen met katholieke afbeeldingen Bouw contentkalenders met visuals van het liturgisch seizoen Laat organisaties posts plannen met passende afbeeldingen Belangrijke beperkingen die je moet volgen De API-licentie verbiedt bepaalde toepassingen strikt. Het overtreden van deze beperkingen kan leiden tot onmiddellijke beëindiging: ❌ AI/ML-training (PERMANENT VERBODEN) Kan niet worden gebruikt om AI/ML-modellen te trainen, te finetunen of om welke AI/ML-modellen dan ook te voeden Kan geen embeddings, datasets of afgeleide extracten voor AI maken Deze beperking blijft onbeperkt gelden, zelfs na beëindiging van de overeenkomst Van toepassing op alle vormen van machine learning en kunstmatige intelligentie ❌ Bestandsdownloads en exports Eindgebruikers kunnen content niet downloaden of opslaan als bestanden Kan geen functionaliteit bieden voor “downloaden” of “exporteren” Content moet gehost blijven door Cathopic of in een geautoriseerde cache Alleen web-geoptimaliseerde URL’s kunnen worden gebruikt, niet de originele bestanden ❌ Print en offline gebruik Kan niet worden gebruikt in drukwerk, brochures of posters Geen offline advertenties of fysieke producten Strikt beperkt tot digitale web- en e-mailomgevingen Kan niet worden opgenomen in PDF’s die bedoeld zijn om te printen ❌ Doorverkoop en herdistributie Kan geen producten maken die Cathopic-content doorverkopen of herdistribueren Kan geen stockfotomarktplaatsen bouwen met onze API Kan content niet aanbieden als een losstaand product Moet worden geïntegreerd als onderdeel van een grotere dienst ❌ Wijziging en afgeleide werken Kan content niet aanpassen, transformeren of afgeleide werken maken Kan geen filters toepassen of ingrijpende wijzigingen aanbrengen Moet content tonen zoals geleverd door de API Basis-cropping en het aanpassen van de grootte zijn toegestaan voor lay-outdoeleinden Alleen web- en e-mailomgevingen Content die via de API wordt geopend, kan alleen worden gebruikt in: Websites: Publieke of private webpagina’s Webapplicaties: Hulpmiddelen en platformen die in de browser draaien E-mail: Nieuwsbrieven, campagnes en transactionele e-mails Blogs: Online contentmanagementsystemen Web-embeds: Gecontroleerde iframe of via API geleverde content Belangrijk: Content moet uitsluitend worden weergegeven in web-geoptimaliseerde resolutie. Originele bestanden met hoge resolutie zijn nooit toegankelijk via de API. Technische vereisten Je applicatie moet: HTTPS gebruiken: Alle API-aanroepen en contentlevering moeten beveiligd zijn Watermerkverwerking implementeren: Begin met content met watermerk; vraag alleen content zonder watermerk aan wanneer dat nodig is Gebruik nauwkeurig bijhouden: Log alle contentgebruik voor factureringsdoeleinden Roep het /confirm-endpoint aan: Wanneer de eindgebruiker bevestigt dat hij/zij content gaat gebruiken Roep het /remove-endpoint aan: Wanneer content niet langer in gebruik is (stopt met factureren) Ongeautoriseerde toegang voorkomen: Bescherm je API-gegevens Respecteer de rate limits: Volg de limieten die voor je account zijn ingesteld Je wettelijke verplichtingen Wanneer je de API integreert, moet je: Je Gebruiksvoorwaarden bijwerken om eindgebruikers te informeren: Content kan niet worden gedownload of gebruikt buiten je applicatie Content kan niet worden gebruikt voor AI/ML-doeleinden Content is eigendom van Cathopic en haar makers Gebruik wordt bijgehouden voor facturering en naleving Implementeer technische controles om te voorkomen dat: Downloads met rechtsklik (waar haalbaar) Directe URL-toegang tot de originele bestanden Browserextensies die downloads mogelijk maken Houd gebruikslogs bij voor: Factureringsverificatie Nalevingsaudits Geschillenbeslechting Voorbeelden van toegestane integraties ✅ Parochie-kerkbulletinbouwer Parochies maken digitale bulletins met katholieke afbeeldingen Content wordt weergegeven op de website en in e-mailnieuwsbrieven Er wordt geen downloadfunctionaliteit aangeboden Facturering houdt het gebruik bij per parochie en per afbeelding ✅ Platform voor e-mail van een pastorale dienst Religieuze organisaties ontwerpen e-mailcampagnes Afbeeldingen worden rechtstreeks in e-mails geleverd via API-URL’s Gefactureerd per e-mail die met content wordt verzonden Geen opslag van bestanden op apparaten van eindgebruikers ✅ Katholiek CMS-platform Websitebouwer met geïntegreerde Cathopic-bibliotheek Gebruikers bladeren en selecteren afbeeldingen voor hun pagina’s Content wordt ingebed via via API geleverde URL’s Gefactureerd per dag gebruik per gebruiker Voorbeelden van verboden integraties ❌ Door AI aangedreven afbeeldingsgenerator Cathopic-content gebruiken om AI-modellen te trainen Datasets maken voor machine learning Vergelijkbare afbeeldingen genereren op basis van onze content ❌ Ontwerptool voor print Gebruikers toestaan om printbare posters te maken Download aanbieden voor printen met hoge resolutie PDF’s maken met Cathopic-content voor print ❌ Stockfotomarktplaats Cathopic-content doorverkopen als losstaande producten Afgeleide stockfotocollecties maken Content herdistribueren naar meerdere klanten Voordat je begint met bouwen Belangrijke lectuur: Lees de volledige API-licentieovereenkomst Bestudeer de technische documentatie op api.cathopic.com/docs Begrijp het factureringsmodel in detail (zie Hoe wordt API-gebruik gefactureerd?) Plan je integratie om aan alle beperkingen te voldoen Neem contact met ons op via support als je vragen hebt Onthoud: Door toegang te krijgen tot of gebruik te maken van de API, aanvaard je alle voorwaarden in de API-licentieovereenkomst. Niet-naleving kan leiden tot onmiddellijke beëindiging en juridische gevolgen.

Question 3

Wat zijn de rate limits?

Accepted Answer

We handhaven momenteel geen strikte limieten voor verzoeken per seconde. Wel wordt verwacht dat je fair use toepast om de servicekwaliteit voor iedereen te behouden. Huidige aanpak In plaats van harde limieten moedigen we verantwoord gebruik aan: Spreid je verzoeken op een redelijke manier Gebruik exponential backoff wanneer er fouten optreden Cache antwoorden om overbodige calls te vermijden Neem contact met ons op als je veel verkeer verwacht Best practices Cacheer agressief: Sla zoekresultaten op voor veelvoorkomende queries Bewaar mediagegevens lokaal nadat je ze hebt opgehaald Roep niet /confirm meerdere keren aan voor dezelfde gebruiker/resource Bundel je bewerkingen: Groepeer gerelateerde verzoeken samen Voeg kleine vertragingen toe tussen batches Beperk het aantal gelijktijdige verbindingen (10-20 is redelijk) Behandel fouten op een soepele manier: Implementeer retry-logica met exponential backoff Probeer niet meteen opnieuw bij een mislukking Log fouten voor monitoring Verwachte responstijden /resources search: meestal 200-500ms /resource details: minder dan 100ms /confirm licensing: 300-800ms Stel je client-timeout in op minstens 30 seconden om af en toe tragere responstijden op te vangen. Als je tegen limieten aanloopt Dan ontvang je een 429 Too Many Requests fout. Als dit gebeurt: // Implement exponential backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, i) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } return response; } catch (error) { if (i === maxRetries - 1) throw error; } } } Monitor je gebruik Volg API-activiteit in Instellingen → API: Bekijk het totaal aantal verzoeken Controleer actieve licenties Bekijk gebruikstrends Let op ongebruikelijke patronen Heb je hogere limieten nodig? Als je legitieme use case veel verzoeken vereist (>1M verzoeken/maand), neem contact op met ons team om te bespreken: Je applicatie en verkeerspatronen Verwachte hoeveelheid verzoeken Gegarandeerde rate limits indien nodig

Question 4

Hoe wordt API-gebruik gefactureerd?

Accepted Answer

De Cathopic API gebruikt een pay-as-you-go factureringsmodel op basis van werkelijk contentgebruik door uw eindgebruikers. Alle factureringsvoorwaarden worden beheerst door onze API-licentieovereenkomst. Twee factureringsmodellen De facturering hangt af van hoe uw eindgebruikers de content gebruiken: 1. Websitegebruik (Days of Use-model) Van toepassing wanneer content wordt weergegeven op websites, blogs of webapplicaties Bereken per kalenderdag dat een eindgebruiker specifieke content opent Formule: Totaal aantal Days of Use × (Onderhandeld maandtarief ÷ 30) Doorberekening per dag zorgt ervoor dat u alleen betaalt voor werkelijk gebruik Apart bijgehouden per eindgebruiker en per contentitem 2. E-mailgebruik (Per Email-model) Van toepassing wanneer content is opgenomen in e-mailberichten In rekening gebracht per verzonden e-mailbericht (niet per ontvanger) Eenmalige facturering per e-mail die de content bevat Tarief onderhandeld tijdens het opzetten van API-toegang Hoe facturering start en stopt Watermarked content is gratis Content verschijnt aanvankelijk met een watermerk Watermarked preview genereert geen kosten Ideaal om eindgebruikers te laten bladeren voordat ze beslissen Kan worden gebruikt voor testen en proefdoeleinden Facturering start wanneer het watermerk wordt verwijderd De eindgebruiker beslist om de content te gebruiken zonder watermerk Uw applicatie roept POST /confirm aan met: media_id: de content-id usage_type: ofwel "website" of "email" client_identifier: de unieke ID van uw eindgebruiker De API retourneert permanente URL’s voor content zonder watermerk De facturering begint onmiddellijk vanaf dit moment U moet deze URL’s en gebruiksgegevens opslaan voor factureringsregistratie Facturering stopt wanneer de content wordt verwijderd De eindgebruiker verwijdert of stopt met het gebruiken van de content Uw applicatie roept POST /remove aan met: media_id: de content-id client_identifier: de ID van de eindgebruiker Facturering voor dat specifieke gebruik stopt U moet de URL’s zonder watermerk uit uw database verwijderen Voorbeeld facturering website Stel dat u een maandtarief heeft onderhandeld van voor onbeperkt contentgebruik: Scenario: Parochie A toont Afbeelding #12345 op hun homepage Dag 1: U roept /confirm aan → facturering start Dagen 1-15: Afbeelding blijft op de homepage (15 dagen gebruik) Dag 16: Parochie verwijdert de afbeelding, u roept /remove aan → facturering stopt Berekening: 15 dagen × ( ÷ 30 dagen) = In rekening gebracht: voor dit specifieke gebruik Als Parochie B dezelfde afbeelding ook 10 dagen gebruikt, wordt dat apart bijgehouden en komt er nog meer bij. Voorbeeld facturering e-mail Stel dat u een tarief heeft onderhandeld van --.05 per e-mail: Scenario: Het ministerie verstuurt een nieuwsbrief met Afbeelding #67890 Actie: U roept /confirm aan met usage_type: "email" Resultaat: Eenmalige kosten van --.05 voor die e-mail Ontvangers: Maakt niet uit of het naar 100 of 10.000 mensen wordt gestuurd In rekening gebracht: --.05 totaal (niet per ontvanger) Maandelijkse factureringslimieten Uw overeenkomst kan maandelijkse factureringslimieten bevatten: Beschermt u tegen onverwacht hoge rekeningen Zodra de limiet is bereikt, kan extra gebruik gratis zijn of tegen een verlaagd tarief Het specifieke limietbedrag wordt onderhandeld tijdens het opzetten van API-toegang Van toepassing op de totale maandelijkse kosten over alle eindgebruikers Facturatie en betaling Factuurschema Facturen worden maandelijks uitgegeven binnen de eerste 10 dagen van elke maand Dit dekt al het gebruik van de vorige maand Gedetailleerde uitsplitsing van gebruik per eindgebruiker en per contentitem Verzonden naar het e-mailadres dat is gekoppeld aan uw API-account Betaalverwerking Betalingen worden uitsluitend verwerkt via Stripe Automatische afschrijving van uw geregistreerde betaalmethode U moet te allen tijde geldige betaalinformatie bijhouden Ontvangstbewijzen worden automatisch verstrekt na een succesvolle betaling Mislukte betalingen Als betaling mislukt, doet het systeem 4 pogingen opnieuw U ontvangt e-mailmeldingen over betalingsproblemen Als alle pogingen mislukken, wordt de API-toegang opgeschort Toegang wordt onmiddellijk hersteld bij een succesvolle betaling Onbetaalde facturen kunnen rente oplopen Uw verantwoordelijkheden voor tracking U moet nauwkeurige gegevens bijhouden van: Gebruikslogs: wanneer de content is bevestigd en verwijderd Eindgebruikers-ID’s: welke gebruikers welke content hebben geopend Content-ID’s: welke media-items zijn gebruikt Gebruikstypes: website versus e-mail voor elk gebruik Datums: start- en einddatums voor websitegebruik URL’s: opgeslagen URL’s zonder watermerk voor actief gebruik Deze logs zijn essentieel voor: Het verifiëren van maandelijkse facturen Het oplossen van factureringsgeschillen Nalevingsaudits door Cathopic Uw eigen interne rapportage Het raadplegen van gebruiksrapporten U kunt uw API-gebruik in realtime bijhouden: Ga naar Instellingen → API Bekijk de sectie "On-demand usage" Bekijk statistieken van de huidige factureringsperiode: Totale kosten die tot nu toe zijn opgebouwd Aantal websitegebruiken Aantal e-mailgebruiken Klik op "View detailed report" voor een uitsplitsing per: Eindgebruiker (client_identifier) Contentitem Gebruikstype Datumbereik Individuele kosten Exporteer rapporten als CSV voor uw administratie Tariefonderhandelingen API-prijzen worden op maat gemaakt voor elke klant: Tarief wordt onderhandeld tijdens het proces voor het aanvragen van API-toegang Op basis van uw verwachte volume aan gebruik Op basis van uw specifieke use case en het type integratie Kan volumekortingen bevatten voor applicaties met hoog gebruik Factureringslimieten kunnen worden onderhandeld om voorspelbare kosten te bieden Om prijzen te bespreken: Bezoek onze supportpagina Selecteer "API access request" Beschrijf uw integratie en het verwachte gebruik Ons team zal een aangepaste offerte verstrekken Het volledige licentiebegrip begrijpen Facturering is slechts één aspect van de API-overeenkomst. Bekijk de volledige voorwaarden: Lees de volledige API-licentieovereenkomst Begrijp de gebruiksbeperkingen (alleen digitaal, geen AI/ML, geen downloads) Weet wat uw verplichtingen zijn voor tracking en rapportage Bekijk bepalingen over intellectueel eigendom en beëindiging Voor technische details over implementatie: Bekijk de /confirm en /remove endpoints op api.cathopic.com/docs Begrijp hoe u gebruik berekent voor uw specifieke integratie Bekijk best practices voor nauwkeurige factureringsregistratie Onthoud: Nauwkeurige tracking van gebruik is uw verantwoordelijkheid. Houd gedetailleerde logs bij om correcte facturering en naleving van de licentieovereenkomst te garanderen.

Question 5

Hoe vraag je ontwikkelaars-toegang aan voor de API en OAuth

Accepted Answer

Cathopic beoordeelt één keer een ontwikkelaarsaccount. Die ene goedkeuring ontgrendelt zowel de commerciële API als het beheer van OAuth-toepassingen; je dient geen afzonderlijke aanvragen in. Na goedkeuring maak en beheer je je API-sleutels en OAuth-inloggegevens vanuit Cathopic Instellingen. Ontwikkelaars hebben nooit een Cathopic-serveropdracht of toegang tot infrastructuur nodig. 1. Bereid je Cathopic-account voor Maak een Cathopic-account aan, verifieer het e-mailadres en zorg dat de gebruikersnaam en e-mail in de aanvraag exact overeenkomen met dat account. 2. Dien de ontwikkelaarsaanvraag in Open het Cathopic contactformulier. Kies Ontwikkelaars-toegang aanvragen. Bevestig de Cathopic-gebruikersnaam en beschrijf het product, de organisatie en het beoogde gebruik van de catalogus. Verzend het formulier. De aanvraag verschijnt in Cathopic’ interne beoordelingsdashboard. 3. Ontvang de beslissing Cathopic beoordeelt het account en het gebruiksdoel. Bij goedkeuring ontvangt de ontwikkelaar een e-mail met de volgende stappen en een link naar Instellingen → Developer / API → OAuth-toepassingen. Als er meer informatie nodig is, neemt Cathopic contact op via het e-mailadres uit de aanvraag. 4. Maak de toepassing aan Kies een vertrouwelijke webapplicatie wanneer het product een beveiligde backend heeft, of een publieke PKCE-applicatie voor clients die alleen in de browser draaien, mobiel of desktop. Vul de publieke naam, beschrijving, website, privacybeleid, beveiligingscontact, exacte callback-URL’s in en alleen de scopes die het nodig heeft. 5. Bewaar de inloggegevens De client-ID identificeert de integratie en wordt gedeeld door alle gebruikers van dat product. Gebruikersautorisatie en tokens blijven gescheiden voor elk Cathopic-account. Een vertrouwelijk clientgeheim wordt slechts één keer getoond en moet worden versleuteld op de server van de applicatie. Neem het nooit op in browsercode, gegenereerde websites, logs, supportberichten of een publieke repository. Op dezelfde pagina kan de goedgekeurde ontwikkelaar callbacks en scopes bewerken, een vertrouwelijk geheim roteren of de toepassing intrekken.

Question 6

Hoe werken API-sleutels?

Accepted Answer

API-sleutels zijn uw authenticatiegegevens voor toegang tot de Cathopic API. Begrijpen hoe ze werken is essentieel voor een veilige en effectieve API-integratie. Wat is een API-sleutel? Een API-sleutel is een unieke geheime token die uw toepassing identificeert en toestemming geeft om toegang te krijgen tot de Cathopic API: Een lange alfanumerieke reeks (bijv., sk_live_abc123xyz789...) Werkt als zowel authenticatie als autorisatie Koppelt aan uw Cathopic-account en facturatie Kan actief of inactief zijn Levenscyclus van de sleutel Aanmaken: Genereer sleutels in Instellingen → API Geef elke sleutel een beschrijvende naam ("Productiewebsite", "Staging", "Mobiele app") Kopieer de volledige sleutel meteen—die wordt slechts één keer getoond Bewaar veilig (omgevingsvariabelen, secrets manager, wachtwoordmanager) Gebruik: Neem op in de x-api-key HTTP-header bij elke aanvraag Sleutels worden bij elke aanvraag server-side gevalideerd Al het API-gebruik wordt bijgehouden en gefactureerd aan uw account Deactiveren: Sleutels kunnen tijdelijk worden uitgeschakeld zonder verwijdering Handig voor het oplossen van problemen of het pauzeren van een specifieke integratie Kan op elk moment opnieuw worden geactiveerd Verwijderen: Verwijdert de sleutel permanent Kan niet ongedaan worden gemaakt of worden hersteld Alle aanvragen met die sleutel zullen onmiddellijk mislukken Richtlijnen voor sleutelbeheer Beveiliging: Maak nooit sleutels vast in versiebeheer: Gebruik .env bestanden en voeg ze toe aan .gitignore Maak sleutels nooit zichtbaar in client-side code: API-sleutels mogen alleen server-side worden gebruikt Gebruik omgevingsvariabelen: Bewaar sleutels in process.env.CATHOPIC_API_KEY of een equivalent Roteer regelmatig: Wijzig sleutels periodiek (per kwartaal of na wijzigingen in het team) Gebruik aparte sleutels per omgeving: Verschillende sleutels voor development, staging en productie Organisatie: Beschrijvende namen: Noem sleutels naar hun doel: "Productiewebsite", "iOS-app", "Emailsysteem" Documenteer eigenaarschap: Houd bij welk teamlid elke sleutel heeft aangemaakt Regelmatige audits: Bekijk actieve sleutels maandelijks en verwijder ongebruikte sleutels Meerdere API-sleutels U kunt meerdere API-sleutels aanmaken voor verschillende doeleinden: Per omgeving: Afzonderlijke sleutels voor development, staging en productie Per toepassing: Verschillende sleutels voor website, mobiele app en interne tools Per teamlid: Individuele sleutels voor ontwikkelaars (makkelijker te volgen en in te trekken) Alle sleutels onder uw account delen dezelfde facturatie. Gebruik vanuit alle sleutels wordt gecombineerd in uw maandelijkse factuur. Monitoring van sleutelgebruik Volg activiteit voor elke sleutel: Ga naar Instellingen → API Bekijk de lijst met alle sleutels met de datum van het laatste gebruik Klik op een sleutel om gedetailleerde gebruiksstatistieken te zien Houd toezicht op onverwachte activiteit Wat te doen als een sleutel is gecompromitteerd Als u denkt dat een API-sleutel is blootgesteld: Verwijder of deactiveer de sleutel onmiddellijk in Instellingen → API Genereer een nieuwe vervangende sleutel Werk uw toepassing bij met de nieuwe sleutel Bekijk gebruikslogs op verdachte activiteiten Neem contact op met support als u ongeautoriseerd gebruik ziet Voorbeeld: sleutels veilig opslaan Node.js met omgevingsvariabelen: // .env-bestand (voeg toe aan .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Uw code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }) }); Python met omgevingsvariabelen: import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'} )

Question 7

Hoe authenticeer ik verzoeken?

Accepted Answer

Alle verzoeken aan de Cathopic API moeten worden geauthenticeerd met je API-sleutel. Zo authenticeer je je API-aanroepen correct. Authenticatiemethode De Cathopic API gebruikt API-sleutel-authenticatie via HTTP-headers: Naam van de header: x-api-key Waarde van de header: Je volledige API-sleutel Vereist voor: Alle API-endpoints Hoofdlettergevoelig: Headernamen en -waarden moeten exact overeenkomen Voorbeeld van basis-authenticatie cURL: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Virgin Mary", "page": 1, "page_size": 20, "order": "popular" }' JavaScript (fetch): const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': process.env.CATHOPIC_API_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }) }); const data = await response.json(); console.log(data); JavaScript (axios): const axios = require('axios'); const response = await axios.post( 'https://api.cathopic.com/resources', { query: 'Virgin Mary', page: 1, page_size: 20, order: 'popular' }, { headers: { 'x-api-key': process.env.CATHOPIC_API_KEY } } ); console.log(response.data); Python (requests): import os import requests api_key = os.environ.get('CATHOPIC_API_KEY') response = requests.post( 'https://api.cathopic.com/resources', headers={ 'x-api-key': api_key, 'Content-Type': 'application/json' }, json={ 'query': 'Virgin Mary', 'page': 1, 'page_size': 20, 'order': 'popular' } ) data = response.json() print(data) PHP (cURL):

Question 8

Hoe roteer ik een API-sleutel?

Accepted Answer

Het regelmatig roteren van API-sleutels is een belangrijke beveiligingspraktijk. Zo roteert u uw sleutels veilig zonder uw service te verstoren. Waarom API-sleutels roteren? Beveiligingsbest practice: Beperkt de blootstelling als een sleutel ooit gecompromitteerd is Wijzigingen bij teamleden: Wanneer ontwikkelaars vertrekken of van rol veranderen Vermoeden van compromis: Als u denkt dat een sleutel mogelijk is blootgesteld Naleving (compliance): Sommige beveiligingsbeleid vereisen periodieke sleutelrotatie Wijzigingen in de omgeving: Bij migratie van infrastructuur of refactoring Standaardrotatieproces (zonder downtime) Stap 1: Maak een nieuwe sleutel Log in op Instellingen → API Klik op "Nieuwe API-sleutel aanmaken" Geef een beschrijvende naam (bijv. "Production Web v2") Kopieer de nieuwe sleutel meteen — deze wordt slechts één keer getoond Sla deze veilig op Stap 2: Werk uw applicatie bij Implementeer de nieuwe sleutel in uw applicatie (omgevingsvariabelen, secrets manager, enz.) Herstart uw applicatie om de nieuwe sleutel te laden Controleer of de nieuwe sleutel correct werkt Houd eventuele fouten in de gaten Stap 3: Bewaak de overgang Houd beide sleutels tijdelijk actief Controleer Instellingen → API om de "Laatst gebruikt"-datums te zien Wacht tot de oude sleutel geen recente activiteit meer toont Zorg dat alle instanties/services zijn overgeschakeld naar de nieuwe sleutel Stap 4: Verwijder de oude sleutel Zodra is bevestigd dat de oude sleutel niet langer wordt gebruikt Verwijder of deactiveer de oude sleutel in Instellingen → API Documenteer de rotatie voor uw administratie Snel rotatieproces (als er sprake is van compromis) Als een sleutel zeker gecompromitteerd is en u direct moet handelen: Verwijder eerst de gecompromitteerde sleutel in Instellingen → API Maak een nieuwe vervangende sleutel Implementeer snel de nieuwe sleutel in alle applicaties Accepteer een korte downtime om ongeautoriseerde toegang te voorkomen Controleer gebruikslogs op verdachte activiteiten Neem contact op met support als dat nodig is Strategie voor rotatie met meerdere omgevingen Voor productiesystemen gebruikt u een gefaseerde aanpak: Week 1: Development Maak en implementeer een nieuwe sleutel naar de dev-omgeving Test grondig Week 2: Staging Implementeer de nieuwe sleutel naar staging Voer integratietests uit Houd issues in de gaten Week 3: Productie Implementeer de nieuwe sleutel naar productie tijdens een periode met weinig verkeer Houd het nauwlettend in de gaten Houd de oude sleutel 24-48 uur actief als fallback Week 4: Opruimen Controleer of de oude sleutel geen activiteit meer toont Verwijder de oude sleutel Werk documentatie bij Voorbeeld van automatisering Script om te helpen verifiëren dat sleutelrotatie is voltooid: #!/bin/bash # check-api-key.sh OLD_KEY="sk_live_OLD123..." NEW_KEY="sk_live_NEW789..." echo "Testing old key..." OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $OLD_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Testing new key..." NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \ -H "x-api-key: $NEW_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}') echo "Old key status: ${OLD_RESPONSE: -3}" echo "New key status: ${NEW_RESPONSE: -3}" if [ "${NEW_RESPONSE: -3}" == "200" ]; then echo "✅ New key is working!" else echo "❌ New key failed!" fi Best practices Roteer regelmatig: Elke 90 dagen voor productsleutels Documenteer rotaties: Houd bij wanneer sleutels zijn geroteerd en waarom Test voordat u verwijdert: Controleer altijd eerst of de nieuwe sleutel werkt voordat u de oude verwijdert Gebruik meerdere sleutels: Scheid sleutels per omgeving om rotatie eenvoudiger te maken Automatiseer waar mogelijk: Gebruik tools voor secretsbeheer die automatische rotatie ondersteunen Checklist na sleutelrotatie Bevestig deze punten na het roteren: ✅ Alle productie-instanties gebruiken de nieuwe sleutel ✅ Alle staging/dev-omgevingen zijn bijgewerkt (als u dezelfde sleutel gebruikt) ✅ Omgevingsvariabelen bijgewerkt ✅ CI/CD-secrets bijgewerkt ✅ Documentatie bijgewerkt ✅ Teamleden op de hoogte gebracht ✅ Oude sleutel verwijderd ✅ Rotatie vastgelegd voor auditdoeleinden

Question 9

Hoe beveilig ik mijn inloggegevens?

Accepted Answer

Je API-sleutels zijn de toegangspoort tot je Cathopic-account. Door ze goed te beveiligen, voorkom je onbevoegde toegang en bescherm je tegen factureringsfraude. De gouden regel: houd sleutels geheim Behandel je API-sleutels als wachtwoorden. Veelgemaakte fouten om te vermijden: Sleutels hardcoderen direct in broncode Sleutels vastleggen in Git of andere versiebeheersystemen Sleutels gebruiken in client-side JavaScript of mobiele apps Sleutels delen via e-mail, Slack of berichten-apps Sleutels opslaan op openbare locaties (openbare repositories, wiki’s, enz.) Gebruik omgevingsvariabelen Sla sleutels op in omgevingsvariabelen in plaats van in code: // .env-bestand (voeg toe aan .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Je code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; Zo scheid je gevoelige gegevens van je codebase en wordt het rouleren van sleutels eenvoudiger. Alleen server-side API-aanroepen moeten plaatsvinden vanuit je backendservers, niet vanuit browsers of mobiele apps. Als gebruikers toegang nodig hebben tot Cathopic-bronnen: Maak een backend-endpoint dat je API-sleutel gebruikt Je frontend roept jouw endpoint aan, niet direct Cathopic Je server valideert het gebruikersverzoek voordat hij Cathopic aanroept Beperk op IP (indien mogelijk) Sommige infrastructuren ondersteunen IP-whitelisting. Als je API-aanroepen afkomstig zijn van bekende IP’s: Configureer firewallregels om uitgaande toegang te beperken Gebruik dedicated serviceaccounts met minimale rechten Controleer toeganglogs op ongebruikelijke activiteit Als een sleutel is gecompromitteerd Als je vermoedt dat een sleutel is blootgesteld: Genereer onmiddellijk een nieuwe API-sleutel Werk je applicatie bij met de nieuwe sleutel Verwijder de gecompromitteerde sleutel Bekijk gebruikslogs op verdachte activiteit Contact support als je ongeautoriseerde kosten ziet Beheer je sleutels veilig op Instellingen → API.

Question 10

Veelvoorkomende authenticatiefouten

Accepted Answer

Als je problemen hebt met authenticeren met de Cathopic API, dan zijn dit de meest voorkomende fouten en hoe je ze oplost. 401 Unauthorized De meest voorkomende authenticatiefout: HTTP 401 Unauthorized { "message": "Unauthorized" } Veelvoorkomende oorzaken: Ontbrekend x-api-key header Ongeldige of verlopen API-sleutel Typfout in de API-sleutel Spaties vóór/na de sleutel Sleutel niet geladen vanuit omgevingsvariabele Hoe op te lossen: Controleer of de headernaam exact is x-api-key (kleine letters) Kopieer je API-sleutel opnieuw van Instellingen → API Controleer of omgevingsvariabelen zijn geladen: console.log(process.env.CATHOPIC_API_KEY) Trim spaties: apiKey.trim() Controleer of de sleutel actief is (niet verwijderd of gedeactiveerd) Verkeerde headernaam De API vereist x-api-key, niet andere veelgebruikte headernamen: // ❌ WRONG Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRECT x-api-key: sk_live_abc... Fout met onbevoegde token HTTP 401 Unauthorized { "error": "Unauthorized token" } Oorzaak: Je API-sleutel is gedeactiveerd of verwijderd. Hoe op te lossen: Controleer of de sleutel nog steeds actief is in Instellingen → API Activeer de sleutel opnieuw als deze gedeactiveerd was Genereer een nieuwe sleutel als de oude is verwijderd Omgevingsvariabele niet geladen Je code kan de API-sleutel niet vinden: // Geeft undefined terug const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined Hoe op te lossen: Node.js: // Zorg dat .env is geladen require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; if (!apiKey) { throw new Error('CATHOPIC_API_KEY not set'); } Python: import os from dotenv import load_dotenv load_dotenv() api_key = os.environ.get('CATHOPIC_API_KEY') if not api_key: raise ValueError('CATHOPIC_API_KEY not set') Fout door blootstelling aan de clientzijde Proberen om de API-sleutel te gebruiken in browser-JavaScript: // ❌ Dit zal mislukken (sleutels werken niet in browsers) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); Hoe op te lossen: Maak een endpoint aan de serverzijde die verzoeken doorstuurt (proxy) naar de Cathopic API. Zie "Hoe beveilig ik mijn inloggegevens?" voor voorbeelden. CORS-fouten Als je CORS-fouten ziet in de browserconsole: Toegang tot fetch is geblokkeerd door het CORS-beleid... Oorzaak: Je probeert de API rechtstreeks aan te roepen vanuit client-side JavaScript. Hoe op te lossen: De Cathopic API is alleen server-side. Je moet verzoeken via je eigen backend doorsturen (proxy). Authenticatie testen Snelle test om je setup te verifiëren: curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"test","page":1,"page_size":1}' # Zoek naar een HTTP 200-antwoord # Als 401, controleer de sleutel zorgvuldig Checklist voor debugging Als authenticatie nog steeds mislukt: ☐ De headernaam is x-api-key (hoofdlettergevoelig) ☐ De API-sleutel is de volledige sleutel (begint met sk_live_ of iets dergelijks) ☐ Geen Bearer-prefix of aanhalingstekens rond de sleutel ☐ Omgevingsvariabele is ingesteld en geladen ☐ Verzoek wordt verzonden vanuit server-side, niet vanuit browser ☐ Sleutel is actief in Instellingen → API ☐ Betaalmethode is toegevoegd en geldig Als de problemen blijven, neem contact op met developer support met: Het foutbericht Laatste 4 cijfers van je API-sleutel Programmeertaal en framework Voorbeeldcode (zonder je volledige sleutel bloot te geven)

Question 11

Beschikbare zoekparameters

Accepted Answer

De /resources endpoint accepteert verschillende parameters om je zoekresultaten te verfijnen. Basiszoekopdracht POST https://api.cathopic.com/resources { "query": "Sint Franciscus", "page": 1, "page_size": 20, "order": "popular" } Parameters query (string, optioneel) Je zoekterm. Laat leeg om alle resources op te halen. Voorbeelden: "Maagd Maria", "Eucharistie", "kruis" Ondersteunt fuzzy matching en tolerantie voor typefouten Zoekt in titels, beschrijvingen en tags page (integer, standaard: 1) Welke pagina met resultaten moet worden teruggegeven. Begint bij 1. page_size (integer, standaard: 20, max: 100) Aantal resultaten per pagina. Maximum is 100 om de prestaties te behouden. order (string, standaard: "popular") Zo sorteer je resultaten: popular - Eerst de meest gedownloade resources recent - Eerst de nieuwste uploads Structuur van de respons { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Titel van de resource", "description": "Beschrijving van de resource", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Praktische voorbeelden Haal de eerste 10 meest populaire resources op over gebed: { "query": "gebed", "page": 1, "page_size": 10, "order": "popular" } Haal recente uploads op, zonder specifieke zoekterm: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Blader door pagina 3 met afbeeldingen van heiligen: { "query": "heiligen", "page": 3, "page_size": 20, "order": "popular" } Voor de volledige API-referentie, ga naar api.cathopic.com/docs.

Question 12

Hoe kan ik afbeeldingen downloaden via de API?

Accepted Answer

Belangrijke verduidelijking: De API staat geen "downloaden" toe in de traditionele zin. In plaats daarvan biedt hij permanente URL's naar web-geoptimaliseerde content die je applicatie aan eindgebruikers aanbiedt. Dit wordt geregeld door onze API-licentieovereenkomst. Je downloadt GEEN bestanden De Cathopic API werkt fundamenteel anders dan traditionele downloads: Geen bestandsdownloads: Je ontvangt of bewaart nooit de daadwerkelijke afbeeldings-/videobestanden Toegang via URL: De API levert URL's die verwijzen naar content die door Cathopic wordt gehost Alleen web-geoptimaliseerd: Content wordt geleverd in een resolutie die geschikt is voor digitale weergave Geen originele bestanden: Originele bestanden met hoge resolutie zijn NOOIT via de API toegankelijk Altijd gehost: Content blijft op Cathopic-servers of op een geautoriseerde CDN Beschikbare resoluties De API biedt drie web-geoptimaliseerde formaten: Klein: Geschikt voor thumbnails en kleine inbeddingen (typisch ~400px breed) Middelgroot: Goed voor standaard webcontent (typisch ~800px breed) Groot: Beste kwaliteit voor webweergave (typisch ~1200px breed) Kritieke beperkingen: Originele bestanden met hoge resolutie worden NOOIT geleverd Resoluties zijn geoptimaliseerd voor schermweergave, niet voor print Bestandsgroottes zijn gecomprimeerd voor snelle weblevering Je kunt geen aangepaste resoluties of originele kwaliteit aanvragen Voor de volledige voorwaarden lees je de volledige API-licentieovereenkomst en bekijk je de technische documentatie op api.cathopic.com/docs. Afbeeldingen downloaden gebeurt in twee stappen: licenseren van de resource met /confirm, en vervolgens de geretourneerde URL's gebruiken. Stap 1: Licentieer de resource Roep /confirm aan om een resource te licenseren voor een specifieke eindgebruiker: POST https://api.cathopic.com/confirm x-api-key: YOUR_API_KEY { "media_id": 1234, "usage_type": "website", "client_identifier": "user_123" } Parameters: media_id - Het resource-ID uit je zoekresultaten usage_type - Ofwel "website" of "email" client_identifier - Unieke ID voor je eindgebruiker Stap 2: Gebruik de download-URL's Het antwoord bevat permanente URL's in meerdere formaten: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Belangrijk: Bewaar de URL's De URL's die worden teruggegeven zijn permanent—bewaar ze in je database: // Nadat je /confirm hebt aangeroepen const response = await api.confirm(mediaId, userId); // Bewaar in je database await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Haal de volgende keer uit de DB in plaats van opnieuw /confirm aan te roepen Kies het juiste formaat AVIF-formaat: Kleinere bestandsgroottes (betere prestaties) Betere compressie Aanbevolen voor moderne browsers Niet ondersteund in oudere browsers JPEG-formaat: Universele compatibiliteit Grotere bestandsgroottes Gebruik als fallback voor oudere browsers Kritieke herinnering ⚠️ Controleer altijd eerst je database voordat je /confirm aanroept. Door het meerdere keren aan te roepen voor dezelfde gebruiker en resource ontstaan er dubbele kosten. Volledige documentatie op api.cathopic.com/docs.

Question 13

Paginering en sortering beheren

Accepted Answer

De API geeft zoekresultaten in pagina’s terug. Zo navigeer je efficiënt door grote resultatenreeksen. Basis-paginering POST /resources { "query": "saints", "page": 1, "page_size": 20 } Antwoord: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 items ... ] } Het antwoord vertelt je dat er in totaal 1.523 resultaten zijn, en dat je pagina 1 bekijkt met 20 items. Het aantal pagina’s berekenen const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 pagina’s Volgende pagina laden // Eenvoudige volgende pagina currentPage++; // Of bouw een paginerings-UI for (let page = 1; page <= totalPages; page++) { // Maak een paginaknop } Paginaformaat optimaliseren Kies het paginaformaat op basis van je use case: Kleine pagina’s (10-20 items): Snellere initiële laadtijd Goed voor zoeken voor gebruikers Er zijn meer API-aanvragen nodig Grote pagina’s (50-100 items): Minder API-aanvragen Goed voor batchverwerking Langzamere individuele aanvragen Maximum is 100 items Sorteeropties Populair (standaard): { "order": "popular" } Geeft de meest gedownloade bronnen eerst terug. Het beste voor het tonen van hoogwaardige, bewezen content. Recent: { "order": "recent" } Geeft de nieuwste uploads eerst terug. Goed om nieuwe content te ontdekken. Voorbeeld van infinite scroll let currentPage = 1; const pageSize = 20; let isLoading = false; let hasMore = true; async function loadMore() { if (isLoading || !hasMore) return; isLoading = true; const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'prayer', page: currentPage, page_size: pageSize, order: 'popular' }) }); const data = await response.json(); // Voeg resultaten toe aan je UI appendResults(data.results); // Controleer of er nog meer pagina’s zijn const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Trigger bij scrollen window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Tips voor prestaties Cache resultaten lokaal om onnodige aanvragen te vermijden Gebruik passende paginaformaten voor je use case Implementeer laadstatussen voor een betere gebruikerservaring Overweeg virtualisatie voor erg grote lijsten Haal niet alle pagina’s tegelijk op - laad op aanvraag Voor meer details, zie de volledige documentatie op api.cathopic.com/docs.

Question 14

Hoe doorzoek je de catalogus en gebruik je Cathopic preview-URL’s

Accepted Answer

Gebruik GET /api/v2/catalog met catalog.read. Het gebruikt Cathopics bestaande fuzzy-zoeklaag die tolerant is voor typefouten en vult dezelfde canonieke mediaproductmodellen aan die ook door de website-grid worden gebruikt. Parameters q of query: tekst tot 250 tekens. type: foto, video, grafiek, artwork, ai, of alles. orientation: landscape, portrait, vierkant, of alles. sort: most_recent, popular, of popular_alltime. page, per_page tot 50, en locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENGebruik preview-URL’s ongewijzigd Elke resultaat bevat preview.url en preview.transformation_url_template. Ze komen uit dezelfde grid-presenter, CDN-host, opslagpad en watermerkregels die op cathopic.com worden gebruikt. Gebruik ze ongewijzigd zodat integraties de bestaande Cloudflare-cache-sleutels opnieuw kunnen gebruiken. Upload geen andere kopie of proxy het onnodig. Voeg geen cache-busting queryparameters toe. Vervang <OPTIONS> alleen door stabiele Cloudflare-afbeeldingsopties. Previews verbruiken nooit een download. already_licensed omvat individuele en gedeelde entitlements voor teams.

Question 15

Hoe licentie en bron veilig licenseren en downloaden

Accepted Answer

Het aanmaken van de licentie en het aanmaken van de oorspronkelijke URL zijn gescheiden, zodat herpogingen veilig zijn en verse URL’s nooit opnieuw kosten veroorzaken. 1. Maak de licentie aan POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Gebruik een unieke sleutel van 8 tot 160 afdrukbare ASCII-tekens voor de logische selectie-poging en behoud die bij het opnieuw proberen. Een nieuwe licentie geeft 201; een idempotente replay geeft 200 met hetzelfde licentienummer. Cathopic verifieert eerst de oorspronkelijke bron. In één transactie vergrendelt het de individuele- of teamabonnement, controleert het mediatoegang en bestaande gedeelde rechten, verbruikt het maximaal één download en registreert het het recht, de geschiedenis en de licentie. 2. Vraag de oorspronkelijke URL aan POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENDe URL verloopt na vijf minuten. Vraag een nieuwe URL aan voor een herdownload; maak geen nieuwe licentie. Cathopic leidt het opslagpad af en accepteert nooit een willekeurig pad. Belangrijke fouten subscription_required: geen actieve betaalde toegang. media_type_not_in_plan: type niet inbegrepen. download_balance_exhausted: er blijven geen downloads met beperkt plan over. file_unavailable: oorspronkelijke bron ontbreekt; geen kosten. idempotency_key_conflict: sleutel gebruikt voor een ander media-ID. Bewaar de X-Request-Id voor ondersteuning, maar log nooit tokens, geheimen of ondertekende URL’s. Bouw terug met jitter na een 429 of een tijdelijke 5xx-reactie.

Question 16

OAuth 2.0 quickstart voor Cathopic connected apps

Accepted Answer

Cathopic Connected Apps gebruiken OAuth 2.0 Authorization Code met verplichte PKCE S256. Dezelfde goedkeuring van de ontwikkelaar ontgrendelt ook de commerciële API van Cathopic, maar OAuth-verbindingen gebruiken gebruikers-tokens en het abonnement van de verbonden gebruiker in plaats van API-sleutels en facturering per gebruik van de API. 1. Verkrijg toegang en registreer de applicatie Dien het enkele verzoek om ontwikkelaarstoegang in via de contactformulier. Nadat Cathopic het account per e-mail heeft goedgekeurd, opent u Instellingen → Developer / API → OAuth-applicaties, maak de applicatie aan, registreer de exacte callbacks en vereiste scopes, en bewaar het eenmalige geheim ervan als het een vertrouwelijke applicatie is. 2. Ontdek de autorisatieserver GET https://cathopic.com/.well-known/oauth-authorization-server3. Redirect de gebruiker GET https://cathopic.com/oauth/authorize ?client_id=CLIENT_ID &redirect_uri=EXACT_CALLBACK &response_type=code &scope=account.read%20catalog.read%20entitlements.read%20licenses.create%20licenses.read &state=UNGUESSABLE_STATE &code_challenge=BASE64URL_SHA256_VERIFIER &code_challenge_method=S256 &ui_locales=enBouw één URL; de regeleinden maken het voorbeeld alleen leesbaar. Genereer voor elke poging nieuwe waarden met hoge entropie voor state en PKCE. ui_locales is optioneel en kan een ondersteunde taal opvragen zoals en of es. Als aanmelden vereist is, hervat Cathopic dezelfde autorisatieaanvraag en toont vervolgens het toestemmingsscherm. 4. Valideer de callback en wissel de code om Vergelijk de teruggestuurde state voordat u de code omwisselt. De redirect URI moet byte voor byte overeenkomen. POST https://cathopic.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=EXACT_CALLBACK&code=CODE&code_verifier=VERIFIERPublieke applicaties weglaten client_secret. Bewaar tokens en vertrouwelijke geheimen alleen op de server en versleutel ze tijdens opslag. Access tokens zijn 30 minuten geldig; refresh tokens zijn tot 30 dagen geldig en worden geroteerd wanneer ze worden gebruikt. Veelvoorkomende controles Een afgewezen callback verschilt meestal van de geregistreerde URI door scheme, host, poort, pad, hoofdlettergebruik of een afsluitende slash. invalid_request voor toestemming betekent dat PKCE S256, de challenge of state ontbreekt of ongeldig is. invalid_grant betekent doorgaans dat een code of een geroteerde refresh token opnieuw is gebruikt, of dat de callback of verifier is gewijzigd. Na een 401: vernieu w één keer; als vernieuwen mislukt, vraag de gebruiker dan om opnieuw te verbinden. Een 403 betekent dat de token niet over de vereiste scope beschikt. Zie het volledige OpenAPI-contract en de gedetailleerde handleiding voor de integratie van Connected Apps.

Question 17

Hoe verbind ik Cathopic met een andere applicatie?

Accepted Answer

Een goedgekeurd platform kan je de Cathopic-catalogus laten gebruiken zonder je wachtwoord te ontvangen. Het stuurt je browser naar een beveiligde pagina op cathopic.com, waar je inlogt en de exacte machtigingen bekijkt die worden gevraagd. Verbind je account Kies in de andere applicatie de Cathopic-connector en klik op Verbinden of Inloggen met Cathopic. Bevestig dat de browser zich op cathopic.combevindt. Log indien nodig in op Cathopic. Cathopic gaat terug naar dezelfde machtigingsaanvraag in plaats van je profiel te openen. Lees elke machtiging. Deze kunnen onder meer accountidentiteit, toegang tot de catalogus, het abonnementsaldo of de mogelijkheid om resources te licentiëren omvatten. Kies Toegang toestaan. Cathopic stuurt je alleen terug naar de exacte callback die voor die applicatie is geregistreerd. Taal en veiligheid van je account De applicatie kan een ondersteunde taal aanvragen voor de inlog- en machtigingsschermen. Cathopic houdt die taal aan gedurende de hele verbinding. De applicatie ontvangt kortlevende tokens, nooit je wachtwoord, en kan alleen de acties uitvoeren die op het machtigingsscherm staan vermeld. Als je het verzoek niet vertrouwt Kies Annuleren. Keur de verbinding niet goed als de applicatie je onbekend is, de machtigingen onnodig lijken, of als de browser niet het Cathopic-domein toont. Je kunt later de toegang intrekken via Instellingen → Developer / API → Verbonden apps.

Question 18

Gebruiken verbonden apps mijn downloads, en hoe verbreek ik de verbinding?

Accepted Answer

Het zoeken naar en het weergeven van watermerkvoorbeelden verbruikt nooit een download. Een download kan alleen worden verbruikt wanneer een verbonden toepassing Cathopic vraagt om een betaald resource te licentiëren. Wanneer één download wordt verbruikt De resource is betaald, het abonnement bevat het type ervan en noch jij, noch het abonnement van het huidige team heeft het eerder gelicentieerd. Het abonnement heeft een beperkt saldo. Abonnementen met onbeperkt gebruik registreren de licentie zonder een aantal te verlagen. Het originele bestand is beschikbaar. Cathopic verifieert dit voordat het saldo wordt aangepast. Wanneer er geen extra download wordt verbruikt De resource is gratis. Jij of een ander lid die dezelfde teamabonnement gebruikt, heeft het al eerder gelicentieerd. Je vraagt een nieuwe downloadlink aan voor een bestaande licentie. De toepassing probeert dezelfde aanvraag opnieuw met dezelfde idempotency key. Teamleden verbruiken het gedeelde saldo van de eigenaar van het team. Cathopic is altijd de bron van waarheid. Verbind een toepassing los Open Instellingen → Ontwikkelaar / API → Verbonden apps. Bekijk de toepassing en de machtigingen. Klik Verbreek de verbinding en bevestig. Alle actieve access- en refresh-tokens voor die toepassing worden onmiddellijk ingetrokken. Bestaande licenties en downloadgeschiedenis blijven behouden.

Question 19

Veelvoorkomende API-foutcodes

Accepted Answer

Het begrijpen van foutmeldingen helpt je om problemen snel op te lossen. Dit zijn de meest voorkomende fouten die je tegenkomt. 400 Bad Request { "error": "media_id is vereist" } Oorzaken: Ontbrekende vereiste parameter Ongeldig parameterformaat Ongeldige JSON Oplossing: Controleer of je request body overeenkomt met de API-specificatie op api.cathopic.com/docs. 401 Unauthorized { "message": "Niet geautoriseerd" } of { "error": "Onjuiste token" } Oorzaken: Ontbrekende of ongeldige API-sleutel Gedeactiveerde API-sleutel Verkeerde naam van de header Oplossing: Controleer of je x-api-key header correct is en de sleutel actief is in Instellingen → API. 404 Not Found { "error": "Geen bestand gevonden voor media_id 1234" } of { "error": "Media-item niet gevonden" } Oorzaken: De resource bestaat niet De resource is verwijderd Verkeerde media_id Oplossing: Controleer of de media_id bestaat door eerst te zoeken met /resources. 429 Too Many Requests { "error": "Limiet overschreden." } Oorzaken: Te veel verzoeken in korte tijd Snelheidslimiet overschreden Oplossing: Implementeer exponential backoff. Wacht en probeer opnieuw met oplopende vertragingen (1s, 2s, 4s, enz.). 500 Internal Server Error { "error": "Interne serverfout" } Oorzaken: Tijdelijk serverprobleem Onverwachte situatie Oplossing: Wacht even en probeer opnieuw. Als het blijft optreden, neem contact op met support. Voorbeeld van foutafhandeling async function searchWithErrorHandling(query) { try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query, page: 1, page_size: 20 }) }); if (!response.ok) { const error = await response.json(); switch (response.status) { case 400: console.error('Bad request:', error); break; case 401: console.error('Unauthorized. Check your API key.'); break; case 404: console.error('Resource not found:', error); break; case 429: console.error('Rate limited. Implementing backoff...'); await sleep(5000); return searchWithErrorHandling(query); // Retry case 500: console.error('Server error. Retrying in 10s...'); await sleep(10000); return searchWithErrorHandling(query); default: console.error('Unknown error:', error); } throw new Error(`API error: ${response.status}`); } return await response.json(); } catch (error) { console.error('Request failed:', error); throw error; } } Als de fouten aanhouden, controleer de volledige API-documentatie of neem contact op met support.

Question 20

Rate limit-fouten

Accepted Answer

Als je ziet 429 Too Many Requests, dan ben je de API te vaak aan het aanroepen. Zo kun je dit correct afhandelen. De fout HTTP 429 Too Many Requests { "error": "Limit exceed." } Waarom dit gebeurt Rate limits beschermen de API tegen overmatig gebruik: Te veel verzoeken in een korte tijd Aggressief pollen of scrapen Geen wachttijd tussen verzoeken Gelijktijdige verzoeken zonder throttling Strategie met exponentiële backoff De beste manier om rate limits af te handelen is exponentiële backoff: wacht langer na elke retry: async function fetchWithBackoff(url, options, maxRetries = 5) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); if (response.status === 429) { const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s console.log(`Rate limited. Waiting ${waitTime}ms before retry ${attempt + 1}/${maxRetries}`); await new Promise(resolve => setTimeout(resolve, waitTime)); continue; } if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { if (attempt === maxRetries - 1) throw error; } } throw new Error('Max retries exceeded'); } Rate limits voorkomen Voeg wachttijden toe tussen verzoeken: // Slecht: verzoeken in een snelle stroom for (const id of mediaIds) { await api.getResource(id); // Geen wachttijd } // Goed: throttled verzoeken for (const id of mediaIds) { await api.getResource(id); await sleep(500); // 500ms wachttijd } Bundel je bewerkingen: // Verwerk in batches van 10 met wachttijden const batchSize = 10; for (let i = 0; i < mediaIds.length; i += batchSize) { const batch = mediaIds.slice(i, i + batchSize); await Promise.all(batch.map(id => api.getResource(id))); if (i + batchSize < mediaIds.length) { await sleep(2000); // 2s tussen batches } } Cache de antwoorden: const cache = new Map(); async function getCachedResource(mediaId) { if (cache.has(mediaId)) { return cache.get(mediaId); } const data = await api.getResource(mediaId); cache.set(mediaId, data); return data; } Wat je NIET moet doen ❌ Meteen opnieuw proberen zonder wachttijd ❌ Parallelle verzoeken doen zonder limiet ❌ 429-fouten negeren ❌ Vaste korte wachttijden gebruiken (gebruik altijd exponentiële backoff) Als de problemen blijven Neem contact op met developer support als je legitiem hogere rate limits nodig hebt voor je use case. Geef details over: Je applicatie en use case Verwachte hoeveelheid verzoeken Huidige implementatie (met backoff)

Question 21

Time-out- en netwerkproblemen

Accepted Answer

Netwerkproblemen kunnen ervoor zorgen dat API-aanvragen mislukken. Zo ga je op een soepele manier om met time-outs en verbindingsproblemen. Passende time-outs instellen Stel altijd time-outs in om te voorkomen dat aanvragen blijven hangen: // JavaScript met fetch const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); // 30s try { const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'Jesus' }), signal: controller.signal }); clearTimeout(timeout); return await response.json(); } catch (error) { clearTimeout(timeout); if (error.name === 'AbortError') { console.error('Aanvraag time-out na 30s'); } else { console.error('Netwerkfout:', error); } throw error; } // Python met requests import requests from requests.exceptions import Timeout, RequestException try: response = requests.post( 'https://api.cathopic.com/resources', headers={'x-api-key': api_key}, json={'query': 'Jesus'}, timeout=30 # 30 seconden ) return response.json() except Timeout: print('Aanvraag time-out na 30s') raise except RequestException as e: print(f'Netwerkfout: {e}') raise Veelvoorkomende netwerkfouten Verbindings-time-out: Kan geen verbinding met de server tot stand brengen Meestal een probleem met het netwerk of de firewall Controleer je internetverbinding Controleer of de firewall HTTPS toestaat naar api.cathopic.com Leestime-out: Verbinding tot stand gebracht, maar geen respons De server kan traag zijn of overbelast Verhoog de time-out of probeer later opnieuw Fout bij DNS-resolutie: Kan api.cathopic.com niet omzetten Probleem met de DNS-server Probeer opnieuw of controleer de DNS-instellingen Opnieuw proberen met backoff async function fetchWithRetry(url, options, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { try { const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 30000); const response = await fetch(url, { ...options, signal: controller.signal }); clearTimeout(timeout); if (!response.ok) { throw new Error(`HTTP ${response.status}`); } return await response.json(); } catch (error) { const isLastAttempt = attempt === maxRetries - 1; if (isLastAttempt) { console.error(`Alle ${maxRetries} pogingen mislukt`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Poging ${attempt + 1} mislukt. Opnieuw proberen over ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Aanbevolen time-outwaarden Verbindings-time-out: 10 seconden Leestime-out: 30 seconden /resources zoeken: 30 seconden /confirm licensing: 30 seconden Netwerkproblemen debuggen Gebruik curl om de connectiviteit te testen: # Test basisconnectiviteit curl -v https://api.cathopic.com/resources # Test met time-out curl --max-time 30 -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Controleer op: ✓ DNS lost api.cathopic.com op ✓ SSL/TLS-verbinding slaagt ✓ HTTP-respons ontvangen ✓ Responstijd redelijk (<5s doorgaans) Als de problemen blijven, neem contact op met support met netwerkdiagnosegegevens.

Question 22

Foutopsporing van mislukte requests

Accepted Answer

Wanneer requests mislukken, helpt systematische foutopsporing om het probleem snel te identificeren. Schakel gedetailleerde logging in async function debugRequest(url, options) { console.log('=== API Request ==='); console.log('URL:', url); console.log('Method:', options.method); console.log('Headers:', { ...options.headers, 'x-api-key': options.headers['x-api-key']?.substring(0, 10) + '...' }); console.log('Body:', options.body); const startTime = Date.now(); try { const response = await fetch(url, options); const duration = Date.now() - startTime; console.log('=== API Response ==='); console.log('Status:', response.status, response.statusText); console.log('Duration:', duration + 'ms'); console.log('Headers:', Object.fromEntries(response.headers)); const data = await response.json(); console.log('Body:', data); return { response, data }; } catch (error) { console.error('=== Request Failed ==='); console.error('Error:', error.message); console.error('Duration:', Date.now() - startTime + 'ms'); throw error; } } Controleer dit eerst 1. De API-sleutel is correct: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. De headernaam is exact: // Must be lowercase 'x-api-key' headers: { 'x-api-key': apiKey, // ✓ Correct 'X-API-Key': apiKey, // ✗ Wrong 'api-key': apiKey, // ✗ Wrong } 3. JSON is geldig: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. De request bereikt de server: // Gebruik het tabblad Network in browser DevTools of curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Veelvoorkomende fouten Verkeerde Content-Type: // ✗ Wrong headers: { 'Content-Type': 'text/plain' } // ✓ Correct headers: { 'Content-Type': 'application/json' } Body niet omzetten naar string: // ✗ Wrong body: { query: 'test' } // ✓ Correct body: JSON.stringify({ query: 'test' }) GET gebruiken in plaats van POST: // ✗ All endpoints require POST method: 'GET' // ✓ Correct method: 'POST' Test met een minimale request Strip terug tot het absolute minimum om het probleem te isoleren: const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': 'YOUR_ACTUAL_KEY_HERE', 'Content-Type': 'application/json' }, body: '{}' // Empty object }); console.log(response.status); console.log(await response.json()); Als dit werkt, voeg dan geleidelijk parameters terug totdat het weer misgaat. Vergelijk met een werkend voorbeeld Test met curl om je implementatie te verifiëren: curl -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "Jesus", "page": 1, "page_size": 5}' Als curl werkt maar je code niet, vergelijk dan de exacte headers en body. Nog steeds vastgelopen? Contact developer support met: Volledige foutmelding Request-headers (verberg je volledige API-sleutel) Request body Response-status en body Programmeertaal en HTTP-bibliotheek Codefragment (zonder inloggegevens te onthullen)

Question 23

Hoe contact opnemen met developer support

Accepted Answer

Hulp nodig bij je API-integratie? Ons team voor developer support staat voor je klaar. Wanneer je contact opneemt met support Neem contact op als je problemen ondervindt met: Authenticatieproblemen ondanks het volgen van de handleidingen Onverwachte foutmeldingen Prestatieproblemen of trage reacties Vragen over facturering of gebruik Hogere rate limits nodig Uitleg over licentievoorwaarden Hulp bij specifieke integratiescenario’s Zo kun je contact met ons opnemen Supportpagina: Bezoek cathopic.com/support en vul het contactformulier in. E-mail (als opgegeven): Stuur de details rechtstreeks naar het e-mailadres voor developer support dat in je API-dashboard staat. Informatie om op te nemen Help ons je sneller te helpen door het volgende te verstrekken: 1. Een duidelijke beschrijving van het probleem Wat je probeert te doen Wat er gebeurt versus wat je verwacht Wanneer het probleem is begonnen 2. Technische details Programmeertaal en framework De HTTP-bibliotheek of SDK die je gebruikt De laatste 4 cijfers van je API-sleutel Foutmeldingen (volledige tekst) HTTP-statuscodes 3. Codevoorbeeld (geanonimiseerd) // Verwijder je volledige API-sleutel! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Alleen de laatste 4 cijfers 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Verzoek-/antwoorddetails Request headers Request body Response status Response body Tijdstip van het probleem Voordat je contact opneemt met support Probeer eerst het volgende om tijd te besparen: Bekijk de API-documentatie Lees de vragen in deze helpsectie Test met curl om het probleem te isoleren Controleer of je API-sleutel actief is in Instellingen → API Controleer of je betaalmethode geldig is Reactietijd We streven ernaar om binnen 24-48 uur op werkdagen te reageren op vragen aan developer support. Complexe problemen kunnen extra onderzoekstijd vereisen. Voor dringende problemen Als je een kritieke storing in productie ervaart: Markeer je supportverzoek als "Urgent" Geef je account-e-mailadres op voor prioriteitsidentificatie Voeg impactdetails toe (aantal getroffen gebruikers, impact op omzet, enz.) API-status Voordat je een storing meldt, controleer of er een bekend probleem is: Test basisconnectiviteit: curl https://api.cathopic.com/resources Bekijk onze statuspagina (indien beschikbaar) Zoek naar aankondigingen in je accountdashboard Aanvullende bronnen Volledige API-documentatie: api.cathopic.com/docs Accountdashboard: cathopic.com/settings/api Algemene support: cathopic.com/support Licentie-informatie: cathopic.com/legal/license We helpen je graag om je integratie succesvol te maken!

Ontwikkelaar / API

Beginnen

API-sleutels, facturering en beveiliging

Catalogus, zoeken en licenties

OAuth-toepassingen

Verbonden apps

Problemen oplossen