Question 1

What is the Cathopic API?

Accepted Answer

Our API is a RESTful service that lets you integrate Cathopic's Catholic media library directly into your applications. Access thousands of images, videos, and graphics programmatically. What you can do Search and browse through our complete catalog License resources for your end-users automatically Download in multiple formats optimized for different use cases Access rich metadata including tags, descriptions, and liturgical information REST architecture Built on standard REST principles: Base URL: https://api.cathopic.com Data format: JSON requests and responses Authentication: API key via x-api-key header HTTP method: POST for all endpoints Four core endpoints POST /resources - Search the catalog POST /resource - Get details about a specific item POST /confirm - License a resource and get download URLs POST /remove - Stop licensing when no longer needed (website only) Complete documentation Everything you need is available online: Interactive API reference: api.cathopic.com/docs Code examples in multiple languages Detailed parameter specifications Getting started Contact our team to request API access Generate your API key in Settings → API Add a payment method for usage billing Start building Check out the other questions in this section for details on authentication, billing, and best practices. API License Agreement All API usage is subject to our API License Agreement. Key points to understand: Digital use only: Content can only be displayed in web and email environments No file downloads: End users cannot download or export original files Prohibited uses: AI/ML training, print materials, and offline use are strictly forbidden Usage-based billing: Pay only for actual content usage by your end users By using the API, you accept all terms in the license agreement Before integrating the API: Review the complete API License Agreement Understand the restrictions and obligations Ensure your use case complies with digital-only requirements Plan your integration to track usage accurately for billing For more details, see: What can I build with the API? (includes detailed restrictions) How do licenses work via API? (complete licensing details) How is API usage billed? (billing model explanation)

Question 2

What can I build with the API?

Accepted Answer

The Cathopic API allows you to integrate Catholic visual content directly into your application, website, or platform. However, API usage is strictly governed by our API License Agreement, which limits use to specific digital environments. What you can build Church and parish management systems Allow parishes to add Catholic imagery to their bulletins and newsletters Enable event promotion with relevant visual content Provide liturgical images that match the church calendar Create digital displays for parish announcements Catholic content platforms Build blogging platforms for Catholic writers with integrated imagery Create Catholic news websites with relevant visuals Develop devotional apps with daily images and prayers Design catechetical platforms with visual teaching aids Email marketing tools Allow ministries to create newsletters with Catholic imagery Enable religious organizations to design email campaigns Provide templates with integrated Cathopic content Support fundraising campaigns with appropriate visuals Website builders and CMS Integrate Catholic imagery into website building platforms Provide content modules for Catholic organizations Enable drag-and-drop image selection from Cathopic Create templates specifically for Catholic ministries Event and social media management Help ministries create social media graphics (without downloading files) Design event invitation systems with Catholic imagery Build content calendars with liturgical season visuals Enable organizations to schedule posts with appropriate images Critical restrictions you must follow The API License strictly prohibits certain uses. Violating these restrictions may result in immediate termination: ❌ AI/ML training (PERMANENTLY PROHIBITED) Cannot be used to train, fine-tune, or feed any AI/ML models Cannot create embeddings, datasets, or derivative extracts for AI This restriction survives indefinitely, even after agreement termination Applies to all forms of machine learning and artificial intelligence ❌ File downloads and exports End users cannot download or save content as files Cannot provide "download" or "export" functionality Content must remain hosted by Cathopic or in authorized cache Only web-optimized URLs can be used, not original files ❌ Print and offline use Cannot be used in print materials, brochures, or posters No offline advertising or physical products Strictly limited to digital web and email environments Cannot be incorporated into PDFs meant for printing ❌ Resale and redistribution Cannot create products that resell or redistribute Cathopic content Cannot build stock photo marketplaces using our API Cannot offer content as a standalone product Must be integrated as part of a larger service ❌ Modification and derivatives Cannot alter, transform, or create derivative works Cannot apply filters or significant modifications Must display content as provided by the API Basic cropping and resizing are permitted for layout purposes Only web and email environments Content accessed through the API can only be used in: Websites: Public or private web pages Web applications: Browser-based tools and platforms Email: Newsletters, campaigns, and transactional emails Blogs: Online content management systems Web embeds: Controlled iframe or API-served content Important: Content must be displayed at web-optimized resolution only. Original high-resolution files are never accessible through the API. Technical requirements Your application must: Use HTTPS: All API calls and content delivery must be secure Implement watermark handling: Start with watermarked content, request unwatermarked only when needed Track usage accurately: Log all content usage for billing purposes Call /confirm endpoint: When end user commits to using content Call /remove endpoint: When content is no longer in use (stops billing) Prevent unauthorized access: Protect your API credentials Respect rate limits: Follow the limits set for your account Your legal obligations When you integrate the API, you must: Update your Terms of Use to inform end users: Content cannot be downloaded or used outside your application Content cannot be used for AI/ML purposes Content is owned by Cathopic and its creators Usage is tracked for billing and compliance Implement technical controls to prevent: Right-click downloads (where feasible) Direct URL access to original files Browser extensions that enable downloads Maintain usage logs for: Billing verification Compliance audits Dispute resolution Examples of compliant integrations ✅ Parish bulletin builder Parishes create digital bulletins with Catholic images Content displays on website and in email newsletters No download functionality provided Billing tracks usage per parish and per image ✅ Ministry email platform Religious organizations design email campaigns Images served directly in emails via API URLs Billed per email sent with content No file storage on end user devices ✅ Catholic CMS platform Website builder with integrated Cathopic library Users browse and select images for their pages Content embeds via API-served URLs Billed per day of use per user Examples of prohibited integrations ❌ AI-powered image generator Using Cathopic content to train AI models Creating datasets for machine learning Generating similar images based on our content ❌ Print design tool Allowing users to create printable posters Providing download for high-res printing Creating PDFs with Cathopic content for print ❌ Stock photo marketplace Reselling Cathopic content as standalone products Creating derivative stock photo collections Redistributing content to multiple clients Before you start building Essential reading: Review the complete API License Agreement Study the technical documentation at api.cathopic.com/docs Understand the billing model in detail (see How is API usage billed?) Plan your integration to comply with all restrictions Contact us via support if you have questions Remember: By accessing or using the API, you accept all terms in the API License Agreement. Non-compliance may result in immediate termination and legal consequences.

Question 3

What are the rate limits?

Accepted Answer

Currently, we don't enforce strict request-per-second limits. However, fair usage is expected to maintain service quality for everyone. Current approach Instead of hard limits, we encourage responsible use: Space out your requests reasonably Implement exponential backoff when errors occur Cache responses to avoid redundant calls Contact us if you anticipate high traffic volumes Best practices Cache aggressively: Store search results for common queries Keep media metadata locally after retrieval Don't call /confirm multiple times for the same user/resource Batch your operations: Group related requests together Add small delays between batches Limit concurrent connections (10-20 is reasonable) Handle errors gracefully: Implement retry logic with exponential backoff Don't retry immediately on failure Log errors for monitoring Expected response times /resources search: 200-500ms typically /resource details: Under 100ms /confirm licensing: 300-800ms Set your client timeout to at least 30 seconds to handle occasional slower responses. If you hit limits You'll receive a 429 Too Many Requests error. When this happens: // 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 your usage Track API activity in Settings → API: View total requests made Check active licenses Review usage trends Monitor for unusual patterns Need higher limits? If your legitimate use case requires high request volumes (>1M requests/month), contact our team to discuss: Your application and traffic patterns Expected request volume Guaranteed rate limits if needed

Question 4

How is API usage billed?

Accepted Answer

The Cathopic API uses a pay-as-you-go billing model based on actual content usage by your end users. All billing terms are governed by our API License Agreement. Two billing models Billing depends on how your end users consume the content: 1. Website usage (Days of Use model) Applies when content is displayed on websites, blogs, or web applications Calculated per calendar day that an end user accesses specific content Formula: Total Days of Use × (Negotiated monthly rate ÷ 30) Prorated daily billing ensures you only pay for actual usage Tracked separately per end user and per content item 2. Email usage (Per Email model) Applies when content is incorporated into email messages Charged per email message sent (not per recipient) One-time billing per email that includes the content Rate negotiated during API access setup How billing starts and stops Watermarked content is free Content initially appears with a watermark Watermarked preview does not generate charges Ideal for letting end users browse before committing Can be used for testing and trial purposes Billing starts when watermark is removed End user decides to use content without watermark Your application calls POST /confirm with: media_id: The content identifier usage_type: Either "website" or "email" client_identifier: Your end user's unique ID API returns permanent URLs for watermark-free content Billing begins immediately from this moment You must store these URLs and usage data for billing tracking Billing stops when content is removed End user removes or stops using the content Your application calls POST /remove with: media_id: The content identifier client_identifier: The end user's ID Billing for that specific usage stops You must delete the watermark-free URLs from your database Website billing example Let's say you negotiated a monthly rate of for unlimited content usage: Scenario: Parish A displays Image #12345 on their homepage Day 1: You call /confirm → Billing starts Days 1-15: Image remains on homepage (15 days of use) Day 16: Parish removes image, you call /remove → Billing stops Calculation: 15 days × ( ÷ 30 days) = Charged: for this specific usage If Parish B also uses the same image for 10 days, that's tracked separately and adds more. Email billing example Let's say you negotiated a rate of --.05 per email: Scenario: Ministry sends a newsletter with Image #67890 Action: You call /confirm with usage_type: "email" Result: One-time charge of --.05 for that email Recipients: Doesn't matter if sent to 100 or 10,000 people Charged: --.05 total (not per recipient) Monthly billing caps Your agreement may include monthly billing caps: Protects you from unexpectedly high bills Once cap is reached, additional usage may be free or at reduced rate Specific cap amount is negotiated during API access setup Applies to total monthly charges across all end users Invoicing and payment Invoice schedule Invoices issued monthly within the first 10 days of each month Covers all usage from the previous month Detailed breakdown of usage by end user and content item Sent to the email address associated with your API account Payment processing Payments processed exclusively through Stripe Automatic charge to your registered payment method Must maintain valid payment information at all times Receipts provided automatically after successful payment Payment failures If payment fails, system makes 4 retry attempts You receive email notifications about payment issues If all retries fail, API access is suspended Access restored immediately upon successful payment Unpaid invoices may accrue interest charges Your tracking responsibilities You must maintain accurate records of: Usage logs: When content was confirmed and removed End user IDs: Which users accessed which content Content IDs: Which media items were used Usage types: Website vs email for each usage Dates: Start and end dates for website usage URLs: Stored watermark-free URLs for active usage These logs are essential for: Verifying monthly invoices Resolving billing disputes Compliance audits by Cathopic Your own internal reporting Accessing usage reports You can track your API usage in real-time: Go to Settings → API View the "On-demand usage" section See current billing period statistics: Total cost accumulated so far Website uses count Email uses count Click "View detailed report" for breakdown by: End user (client identifier) Content item Usage type Date range Individual costs Export reports as CSV for your records Negotiating rates API pricing is customized for each client: Rates are negotiated during the API access request process Based on your expected usage volume Based on your specific use case and integration type May include volume discounts for high-usage applications Billing caps can be negotiated to provide predictable costs To discuss pricing: Visit our support page Select "API access request" Describe your integration and expected usage Our team will provide a customized quote Understanding the full license Billing is just one aspect of the API agreement. Review the complete terms: Read the full API License Agreement Understand usage restrictions (digital only, no AI/ML, no downloads) Know your obligations for tracking and reporting Review intellectual property and termination clauses For technical details on implementation: See the /confirm and /remove endpoints at api.cathopic.com/docs Understand how to calculate usage for your specific integration Review best practices for accurate billing tracking Remember: Accurate usage tracking is your responsibility. Maintain detailed logs to ensure correct billing and compliance with the license agreement.

Question 5

How to request developer access for the API and OAuth

Accepted Answer

Cathopic reviews a developer account once. That single approval unlocks both the commercial API and OAuth application management; you do not submit separate requests. After approval, you create and manage your API keys and OAuth credentials from Cathopic Settings. Developers never need a Cathopic server command or infrastructure access. 1. Prepare your Cathopic account Create a Cathopic account, verify its email address, and make sure the username and email in the request match that account exactly. 2. Send the developer request Open the Cathopic contact form. Choose Request developer access. Confirm the Cathopic username and describe the product, organization, and intended catalog use. Send the form. The request appears in Cathopic's internal review dashboard. 3. Receive the decision Cathopic reviews the account and use case. When approved, the developer receives an email with the next steps and a link to Settings → Developer / API → OAuth applications. If more information is needed, Cathopic contacts the email from the request. 4. Create the application Choose a confidential web application when the product has a secure backend, or a public PKCE application for browser-only, mobile, or desktop clients. Enter its public name, description, website, privacy policy, security contact, exact callback URLs, and only the scopes it needs. 5. Store the credentials The client ID identifies the integration and is shared by all of that product's users. User authorization and tokens remain separate for each Cathopic account. A confidential client secret is shown only once and must be encrypted on the application's server. Never include it in browser code, generated websites, logs, support messages, or a public repository. The same page lets the approved developer edit callbacks and scopes, rotate a confidential secret, or revoke the application.

Question 6

How do API keys work?

Accepted Answer

API keys are your authentication credentials for accessing the Cathopic API. Understanding how they work is essential for secure and effective API integration. What is an API key? An API key is a unique secret token that identifies your application and authorizes it to access the Cathopic API: A long alphanumeric string (e.g., sk_live_abc123xyz789...) Acts as both authentication and authorization Tied to your Cathopic account and billing Can be active or inactive Key lifecycle Creation: Generate keys in Settings → API Give each key a descriptive name ("Production Website", "Staging", "Mobile App") Copy the full key immediately - it's shown only once Store securely (environment variables, secrets manager, password manager) Usage: Include in the x-api-key HTTP header with every request Keys are validated server-side on each request All API usage is tracked and billed to your account Deactivation: Keys can be temporarily disabled without deletion Useful for troubleshooting or pausing a specific integration Can be reactivated anytime Deletion: Permanently removes the key Cannot be undone or recovered All requests with that key will fail immediately Key management guidelines Security: Never commit keys to version control: Use .env files and add them to .gitignore Never expose in client-side code: API keys should only be used server-side Use environment variables: Store keys in process.env.CATHOPIC_API_KEY or equivalent Rotate regularly: Change keys periodically (quarterly or after team member changes) Use separate keys per environment: Different keys for dev, staging, and production Organization: Descriptive names: Name keys by purpose: "Production Website", "iOS App", "Email System" Document ownership: Track which team member created each key Regular audits: Review active keys monthly and remove unused ones Multiple API keys You can create multiple API keys for different purposes: Per environment: Separate keys for development, staging, production Per application: Different keys for website, mobile app, internal tools Per team member: Individual keys for developers (easier to track and revoke) All keys under your account share the same billing. Usage from all keys is combined in your monthly invoice. Monitoring key usage Track activity for each key: Go to Settings → API View list of all keys with last used dates Click on a key to see detailed usage statistics Monitor for unexpected activity What to do if a key is compromised If you believe an API key has been exposed: Immediately delete or deactivate the key in Settings → API Generate a new replacement key Update your application with the new key Review usage logs for any suspicious activity Contact support if you see unauthorized usage Example: Storing keys securely Node.js with environment variables: // .env file (add to .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Your 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 with environment variables: 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

How do I authenticate requests?

Accepted Answer

All requests to the Cathopic API must be authenticated using your API key. Here's how to properly authenticate your API calls. Authentication method The Cathopic API uses API key authentication via HTTP headers: Header name: x-api-key Header value: Your full API key Required for: All API endpoints Case sensitive: Header names and values must match exactly Basic authentication example 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

How do I rotate an API key?

Accepted Answer

Rotating API keys regularly is an important security practice. Here's how to safely rotate your keys without disrupting your service. Why rotate API keys? Security best practice: Limits exposure if a key is ever compromised Team member changes: When developers leave or change roles Suspected compromise: If you believe a key may have been exposed Compliance: Some security policies require periodic key rotation Environment changes: When migrating infrastructure or refactoring Standard rotation process (zero downtime) Step 1: Create a new key Log in to Settings → API Click "Create new API key" Name it descriptively (e.g., "Production Web v2") Copy the new key immediately - it's shown only once Store it securely Step 2: Update your application Deploy the new key to your application (environment variables, secrets manager, etc.) Restart your application to load the new key Verify the new key is working correctly Monitor for any errors Step 3: Monitor the transition Keep both keys active temporarily Check Settings → API to see "Last used" dates Wait until old key shows no recent activity Ensure all instances/services have switched to the new key Step 4: Delete the old key Once confirmed the old key is no longer in use Delete or deactivate the old key in Settings → API Document the rotation for your records Quick rotation process (if compromised) If a key is definitely compromised and you need to act immediately: Delete the compromised key first in Settings → API Create a new replacement key Quickly deploy the new key to all applications Accept brief downtime to prevent unauthorized access Monitor usage logs for any suspicious activity Contact support if needed Multi-environment rotation strategy For production systems, use a phased approach: Week 1: Development Create and deploy new key to dev environment Test thoroughly Week 2: Staging Deploy new key to staging Run integration tests Monitor for issues Week 3: Production Deploy new key to production during low-traffic period Monitor closely Keep old key active for 24-48 hours as fallback Week 4: Cleanup Verify old key shows no activity Delete old key Update documentation Automation example Script to help verify key rotation is complete: #!/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 Rotate regularly: Every 90 days for production keys Document rotations: Keep a log of when keys were rotated and why Test before deleting: Always verify the new key works before removing the old one Use multiple keys: Separate keys per environment make rotation easier Automate where possible: Use secrets management tools that support automatic rotation After rotation checklist Confirm these items after rotating: ✅ All production instances using new key ✅ All staging/dev environments updated (if using same key) ✅ Environment variables updated ✅ CI/CD secrets updated ✅ Documentation updated ✅ Team members notified ✅ Old key deleted ✅ Rotation logged for audit purposes

Question 9

How do I secure my credentials?

Accepted Answer

Your API keys are the gateway to your Cathopic account. Keeping them secure prevents unauthorized access and protects against billing fraud. The golden rule: Keep keys secret Treat your API keys like passwords. Common mistakes to avoid: Hardcoding keys directly in source code Committing keys to Git or other version control Using keys in client-side JavaScript or mobile apps Sharing keys via email, Slack, or messaging apps Storing keys in public locations (public repos, wikis, etc.) Use environment variables Store keys in environment variables instead of code: // .env file (add to .gitignore!) CATHOPIC_API_KEY=sk_live_abc123xyz789... // Your code require('dotenv').config(); const apiKey = process.env.CATHOPIC_API_KEY; This separates sensitive data from your codebase and makes key rotation easier. Server-side only API calls must happen from your backend servers, not browsers or mobile apps. If users need access to Cathopic resources: Create a backend endpoint that uses your API key Your frontend calls YOUR endpoint, not Cathopic directly Your server validates the user request before calling Cathopic Restrict by IP (if possible) Some infrastructure allows IP whitelisting. If your API calls come from known IPs: Configure firewall rules to limit outbound access Use dedicated service accounts with minimal permissions Monitor access logs for unusual activity If a key is compromised If you suspect a key has been exposed: Generate a new API key immediately Update your application with the new key Delete the compromised key Review usage logs for suspicious activity Contact support if you see unauthorized charges Manage your keys securely at Settings → API.

Question 10

Common authentication errors

Accepted Answer

If you're having trouble authenticating with the Cathopic API, these are the most common errors and how to fix them. 401 Unauthorized The most common authentication error: HTTP 401 Unauthorized { "message": "Unauthorized" } Common causes: Missing x-api-key header Invalid or expired API key Typo in the API key Whitespace before/after the key Key not loaded from environment variable How to fix: Verify the header name is exactly x-api-key (lowercase) Copy your API key again from Settings → API Check environment variables are loaded: console.log(process.env.CATHOPIC_API_KEY) Trim whitespace: apiKey.trim() Verify the key is active (not deleted or deactivated) Wrong header name The API requires x-api-key, not other common header names: // ❌ WRONG Authorization: Bearer sk_live_abc... API-Key: sk_live_abc... apikey: sk_live_abc... // ✅ CORRECT x-api-key: sk_live_abc... Unauthorized token error HTTP 401 Unauthorized { "error": "Unauthorized token" } Cause: Your API key has been deactivated or deleted. How to fix: Check if the key is still active in Settings → API Reactivate the key if it was deactivated Generate a new key if the old one was deleted Environment variable not loaded Your code can't find the API key: // Returns undefined const apiKey = process.env.CATHOPIC_API_KEY; console.log(apiKey); // undefined How to fix: Node.js: // Make sure .env is loaded 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') Client-side exposure error Trying to use API key in browser JavaScript: // ❌ This will fail (keys don't work in browsers) fetch('https://api.cathopic.com/resources', { headers: { 'x-api-key': 'sk_live_abc...' } }); How to fix: Create a server-side endpoint that proxies requests to the Cathopic API. See "How do I secure my credentials?" for examples. CORS errors If you see CORS errors in the browser console: Access to fetch has been blocked by CORS policy... Cause: You're trying to call the API directly from client-side JavaScript. How to fix: The Cathopic API is server-side only. You must proxy requests through your own backend. Testing authentication Quick test to verify your setup: 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}' # Look for HTTP 200 response # If 401, check the key carefully Debugging checklist If authentication still fails: ☐ Header name is x-api-key (case sensitive) ☐ API key is the full key (starts with sk_live_ or similar) ☐ No Bearer prefix or quotes around the key ☐ Environment variable is set and loaded ☐ Request is sent from server-side, not browser ☐ Key is active in Settings → API ☐ Payment method is added and valid If problems persist, contact developer support with: The error message Last 4 digits of your API key Programming language and framework Sample code (without exposing your full key)

Question 11

Available search parameters

Accepted Answer

The /resources endpoint accepts several parameters to refine your search results. Basic search POST https://api.cathopic.com/resources { "query": "Saint Francis", "page": 1, "page_size": 20, "order": "popular" } Parameters query (string, optional) Your search term. Leave empty to get all resources. Examples: "Virgin Mary", "Eucharist", "cross" Supports fuzzy matching and typo tolerance Searches across titles, descriptions, and tags page (integer, default: 1) Which page of results to return. Starts at 1. page_size (integer, default: 20, max: 100) Number of results per page. Maximum is 100 to maintain performance. order (string, default: "popular") How to sort results: popular - Most downloaded resources first recent - Newest uploads first Response structure { "total": 1523, "page": 1, "page_size": 20, "results": [ { "id": 1234, "name": "Resource title", "description": "Resource description", "type": "photo", "orientation": "portrait", "thumbnail_url": "https://...", "author": { ... }, "tags": ["tag1", "tag2"] } ] } Practical examples Get the first 10 most popular resources about prayer: { "query": "prayer", "page": 1, "page_size": 10, "order": "popular" } Get recent uploads, no specific search term: { "query": "", "page": 1, "page_size": 50, "order": "recent" } Browse page 3 of saint images: { "query": "saints", "page": 3, "page_size": 20, "order": "popular" } For full API reference, visit api.cathopic.com/docs.

Question 12

How do I download images via API?

Accepted Answer

Important clarification: The API does not allow "downloading" in the traditional sense. Instead, it provides permanent URLs to web-optimized content that your application serves to end users. This is governed by our API License Agreement. You do NOT download files The Cathopic API works fundamentally different from traditional downloads: No file transfers: You never receive or store the actual image/video files URL-based access: The API provides URLs that point to content hosted by Cathopic Web-optimized only: Content is served in resolution suitable for digital display No original files: High-resolution originals are never accessible via API Always hosted: Content remains on Cathopic servers or authorized CDN Available resolutions The API provides three web-optimized sizes: Small: Suitable for thumbnails and small embeds (typically ~400px wide) Medium: Good for standard web content (typically ~800px wide) Large: Best quality for web display (typically ~1200px wide) Critical restrictions: Original high-resolution files are NEVER provided Resolutions are optimized for screen display, not print File sizes are compressed for fast web delivery You cannot request custom resolutions or original quality For complete terms, read the full API License Agreement and review technical documentation at api.cathopic.com/docs. Downloading images involves two steps: licensing the resource with /confirm, then using the returned URLs. Step 1: License the resource Call /confirm to license a resource for a specific end-user: 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 - The resource ID from your search results usage_type - Either "website" or "email" client_identifier - Unique ID for your end-user Step 2: Use the download URLs The response contains permanent URLs in multiple formats: { "download_url": { "avif": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." }, "jpeg": { "320": "https://...", "640": "https://...", "1280": "https://...", "1920": "https://...", "2560": "https://..." } } } Important: Store the URLs The URLs returned are permanent - store them in your database: // After calling /confirm const response = await api.confirm(mediaId, userId); // Store in your database await db.save({ userId: userId, mediaId: mediaId, avifUrls: response.download_url.avif, jpegUrls: response.download_url.jpeg, licensedAt: new Date() }); // Next time, retrieve from DB instead of calling /confirm again Choosing the right format AVIF format: Smaller file sizes (better performance) Better compression Recommended for modern browsers Not supported in older browsers JPEG format: Universal compatibility Larger file sizes Use as fallback for older browsers Critical reminder ⚠️ Always check your database before calling /confirm. Calling it multiple times for the same user and resource will create duplicate charges. Full documentation at api.cathopic.com/docs.

Question 13

Handling pagination and sorting

Accepted Answer

The API returns search results in pages. Here's how to efficiently navigate through large result sets. Basic pagination POST /resources { "query": "saints", "page": 1, "page_size": 20 } Response: { "total": 1523, "page": 1, "page_size": 20, "results": [ ... 20 items ... ] } The response tells you there are 1,523 total results, and you're viewing page 1 with 20 items. Calculating total pages const totalPages = Math.ceil(response.total / response.page_size); // 1523 / 20 = 76.15 → 77 pages Loading next page // Simple next page currentPage++; // Or build pagination UI for (let page = 1; page <= totalPages; page++) { // Create page button } Optimizing page size Choose page size based on your use case: Small pages (10-20 items): Faster initial load Good for user-facing search More API requests needed Large pages (50-100 items): Fewer API requests Good for batch processing Slower individual requests Maximum is 100 items Sorting options Popular (default): { "order": "popular" } Returns most downloaded resources first. Best for showing high-quality, proven content. Recent: { "order": "recent" } Returns newest uploads first. Good for discovering fresh content. Infinite scroll example 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(); // Add results to your UI appendResults(data.results); // Check if there are more pages const totalPages = Math.ceil(data.total / pageSize); hasMore = currentPage < totalPages; currentPage++; isLoading = false; } // Trigger on scroll window.addEventListener('scroll', () => { if (window.innerHeight + window.scrollY >= document.body.offsetHeight - 500) { loadMore(); } }); Performance tips Cache results locally to avoid redundant requests Use appropriate page sizes for your use case Implement loading states for better UX Consider virtualization for very large lists Don't fetch all pages at once - load on demand For more details, see the full documentation at api.cathopic.com/docs.

Question 14

How to search the catalog and use Cathopic preview URLs

Accepted Answer

Use GET /api/v2/catalog with catalog.read. It uses Cathopic's existing typo-tolerant fuzzy search layer and hydrates the same canonical media models used by the website grid. Parameters q or query: text up to 250 characters. type: photo, video, graphic, artwork, ai, or all. orientation: landscape, portrait, square, or all. sort: most_recent, popular, or popular_alltime. page, per_page up to 50, and locale. GET /api/v2/catalog?q=adoration&type=photo&orientation=landscape&per_page=30 Authorization: Bearer ACCESS_TOKENUse preview URLs unchanged Each result includes preview.url and preview.transformation_url_template. They come from the exact same grid presenter, CDN host, storage path, and watermark rules used on cathopic.com. Use them unchanged so integrations reuse the existing Cloudflare cache keys. Do not upload another copy or proxy it unnecessarily. Do not add cache-busting query parameters. Replace <OPTIONS> only with stable Cloudflare image options. Previews never consume a download. already_licensed includes individual and shared-team entitlements.

Question 15

How to license and download a resource safely

Accepted Answer

License creation and original URL creation are separate so retries are safe and fresh URLs never charge again. 1. Create the license POST /api/v2/licenses Authorization: Bearer ACCESS_TOKEN Content-Type: application/json Idempotency-Key: 2bd25ec7-12da-45fc-9daa-67593b510932 {"media_id":123}Use a unique key of 8 to 160 printable ASCII characters for the logical selection attempt and keep it when retrying. A new license returns 201; an idempotent replay returns 200 with the same license ID. Cathopic first verifies the original. In one transaction it locks the individual or team subscription, checks media access and existing shared entitlements, consumes at most one download, and records the entitlement, history, and license. 2. Request the original URL POST /api/v2/licenses/LICENSE_UUID/download-url Authorization: Bearer ACCESS_TOKENThe URL expires after five minutes. Request a new URL for a re-download; do not create another license. Cathopic derives the storage path and never accepts an arbitrary path. Important errors subscription_required: no active paid access. media_type_not_in_plan: type not included. download_balance_exhausted: no limited-plan downloads remain. file_unavailable: original missing; no charge. idempotency_key_conflict: key used for another media ID. Keep the X-Request-Id for support, but never log tokens, secrets, or signed URLs. Back off with jitter after 429 or transient 5xx responses.

Question 16

OAuth 2.0 quickstart for Cathopic connected apps

Accepted Answer

Cathopic Connected Apps use OAuth 2.0 Authorization Code with mandatory PKCE S256. The same developer approval also unlocks Cathopic's commercial API, but OAuth connections use user tokens and the connected user's plan instead of API keys and metered API billing. 1. Get access and register the application Submit the single developer access request through the contact form. After Cathopic approves the account by email, open Settings → Developer / API → OAuth applications, create the application, register its exact callbacks and required scopes, and store its one-time secret if it is confidential. 2. Discover the authorization server GET https://cathopic.com/.well-known/oauth-authorization-server3. Redirect the user 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=enBuild one URL; the line breaks only make the example readable. Generate new high-entropy state and PKCE values for every attempt. ui_locales is optional and can request a supported language such as en or es. If sign-in is required, Cathopic resumes the same authorization request and then shows the permission screen. 4. Validate the callback and exchange the code Compare the returned state before exchanging the code. The redirect URI must match byte for byte. 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=VERIFIERPublic applications omit client_secret. Store tokens and confidential secrets only on the server and encrypt them at rest. Access tokens last 30 minutes; refresh tokens last up to 30 days and rotate when used. Common checks A rejected callback usually differs from the registered URI by scheme, host, port, path, casing, or trailing slash. invalid_request before consent means that PKCE S256, the challenge, or state is missing or invalid. invalid_grant commonly means a code or rotated refresh token was reused, or the callback or verifier changed. After a 401, refresh once; if refresh fails, ask the user to reconnect. A 403 means the token lacks the required scope. See the complete OpenAPI contract and the detailed Connected Apps integration guide.

Question 17

How do I connect Cathopic to another application?

Accepted Answer

An approved platform can let you use the Cathopic catalog without receiving your password. It sends your browser to a secure page on cathopic.com, where you sign in and review the exact permissions requested. Connect your account In the other application, choose its Cathopic connector and click Connect or Sign in with Cathopic. Confirm that the browser is on cathopic.com. Sign in to Cathopic if necessary. Cathopic returns to the same permission request instead of opening your profile. Read every permission. These can include account identity, catalog access, subscription balance, or the ability to license resources. Choose Allow access. Cathopic sends you back only to the exact callback registered for that application. Language and account safety The application can request a supported language for the sign-in and permission screens. Cathopic keeps that language throughout the connection. The application receives short-lived tokens, never your password, and can perform only the actions listed on the permission screen. If you do not trust the request Choose Cancel. Do not approve the connection if the application is unfamiliar, the permissions seem unnecessary, or the browser is not showing the Cathopic domain. You can later revoke access from Settings → Developer / API → Connected apps.

Question 18

Do connected apps use my downloads, and how do I disconnect them?

Accepted Answer

Searching and displaying watermarked previews never consumes a download. A download may be consumed only when a connected application asks Cathopic to license a paid resource. When one download is consumed The resource is paid, the plan includes its type, and neither you nor the current team subscription has licensed it before. The plan has a limited balance. Unlimited plans record the license without reducing a number. The original file is available. Cathopic verifies this before changing the balance. When no additional download is consumed The resource is free. You or another member using the same team subscription already licensed it. You request a new download link for an existing license. The application retries the same request with the same idempotency key. Team members consume the team owner's shared balance. Cathopic is always the source of truth. Disconnect an application Open Settings → Developer / API → Connected apps. Review the application and its permissions. Click Disconnect and confirm. Every active access and refresh token for that application is revoked immediately. Existing licenses and download history remain.

Question 19

Common API error codes

Accepted Answer

Understanding error responses helps you debug issues quickly. Here are the most common errors you'll encounter. 400 Bad Request { "error": "media_id is required" } Causes: Missing required parameter Invalid parameter format Malformed JSON Fix: Check your request body matches the API specification at api.cathopic.com/docs. 401 Unauthorized { "message": "Unauthorized" } or { "error": "Unauthorized token" } Causes: Missing or invalid API key Deactivated API key Wrong header name Fix: Verify your x-api-key header is correct and the key is active in Settings → API. 404 Not Found { "error": "No file found for media_id 1234" } or { "error": "Media item not found" } Causes: Resource doesn't exist Resource has been deleted Wrong media_id Fix: Verify the media_id exists by searching first with /resources. 429 Too Many Requests { "error": "Limit exceed." } Causes: Too many requests in short time Rate limit exceeded Fix: Implement exponential backoff. Wait and retry with increasing delays (1s, 2s, 4s, etc.). 500 Internal Server Error { "error": "Internal server error" } Causes: Temporary server issue Unexpected condition Fix: Wait a moment and retry. If it persists, contact support. Error handling example 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; } } For persistent errors, check the full API documentation or contact support.

Question 20

Rate limit errors

Accepted Answer

If you see 429 Too Many Requests, you're hitting the API too frequently. Here's how to handle it properly. The error HTTP 429 Too Many Requests { "error": "Limit exceed." } Why this happens Rate limits protect the API from excessive use: Too many requests in a short time Aggressive polling or scraping No delay between requests Concurrent requests without throttling Exponential backoff strategy The best way to handle rate limits is exponential backoff - wait longer after each 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'); } Preventing rate limits Add delays between requests: // Bad: Rapid-fire requests for (const id of mediaIds) { await api.getResource(id); // No delay } // Good: Throttled requests for (const id of mediaIds) { await api.getResource(id); await sleep(500); // 500ms delay } Batch your operations: // Process in batches of 10 with delays 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 between batches } } Cache responses: 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; } What NOT to do ❌ Retry immediately without delay ❌ Make parallel requests without limit ❌ Ignore 429 errors ❌ Use fixed short delays (always use exponential backoff) If problems persist Contact developer support if you legitimately need higher rate limits for your use case. Provide details about: Your application and use case Expected request volume Current implementation (with backoff)

Question 21

Timeout and network issues

Accepted Answer

Network problems can cause API requests to fail. Here's how to handle timeouts and connection issues gracefully. Setting appropriate timeouts Always set timeouts to avoid hanging requests: // JavaScript with 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('Request timed out after 30s'); } else { console.error('Network error:', error); } throw error; } // Python with 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 seconds ) return response.json() except Timeout: print('Request timed out after 30s') raise except RequestException as e: print(f'Network error: {e}') raise Common network errors Connection timeout: Can't establish connection to the server Usually network or firewall issue Check internet connection Verify firewall allows HTTPS to api.cathopic.com Read timeout: Connection established but no response Server may be slow or overloaded Increase timeout or retry later DNS resolution failure: Can't resolve api.cathopic.com DNS server issue Try again or check DNS settings Retry with 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(`All ${maxRetries} attempts failed`); throw error; } const waitTime = Math.pow(2, attempt) * 1000; console.log(`Attempt ${attempt + 1} failed. Retrying in ${waitTime}ms...`); await new Promise(resolve => setTimeout(resolve, waitTime)); } } } Recommended timeout values Connection timeout: 10 seconds Read timeout: 30 seconds /resources search: 30 seconds /confirm licensing: 30 seconds Debugging network issues Use curl to test connectivity: # Test basic connectivity curl -v https://api.cathopic.com/resources # Test with timeout 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"}' Check for: ✓ DNS resolves api.cathopic.com ✓ SSL/TLS connection succeeds ✓ HTTP response received ✓ Response time reasonable (<5s typically) If issues persist, contact support with network diagnostic details.

Question 22

Debugging failed requests

Accepted Answer

When requests fail, systematic debugging helps identify the issue quickly. Enable detailed logging 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; } } Check these first 1. API key is correct: console.log('API key starts with:', apiKey.substring(0, 10)); console.log('API key length:', apiKey.length); 2. Header name 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 valid: try { const body = JSON.stringify({ query: 'test' }); console.log('Valid JSON:', body); } catch (e) { console.error('Invalid JSON:', e); } 4. Request reaches the server: // Use browser DevTools Network tab or curl -v -X POST https://api.cathopic.com/resources \ -H "x-api-key: YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"query": "test"}' Common mistakes Wrong Content-Type: // ✗ Wrong headers: { 'Content-Type': 'text/plain' } // ✓ Correct headers: { 'Content-Type': 'application/json' } Not stringifying body: // ✗ Wrong body: { query: 'test' } // ✓ Correct body: JSON.stringify({ query: 'test' }) Using GET instead of POST: // ✗ All endpoints require POST method: 'GET' // ✓ Correct method: 'POST' Test with minimal request Strip down to bare minimum to isolate the problem: 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()); If this works, gradually add back parameters until it fails. Compare with working example Test with curl to verify your implementation: 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}' If curl works but your code doesn't, compare the exact headers and body. Still stuck? Contact developer support with: Full error message Request headers (hide your full API key) Request body Response status and body Programming language and HTTP library Code snippet (without exposing credentials)

Question 23

How to contact developer support

Accepted Answer

Need help with your API integration? Our developer support team is here to assist you. When to contact support Reach out if you're experiencing: Authentication issues despite following guides Unexpected error responses Performance problems or slow responses Questions about billing or usage Need higher rate limits Clarification on licensing terms Help with specific integration scenarios How to contact us Support page: Visit cathopic.com/support and fill out the contact form. Email (if provided): Send details directly to the developer support email listed in your API dashboard. Information to include Help us help you faster by providing: 1. Clear description of the problem What you're trying to do What's happening vs. what you expect When the issue started 2. Technical details Programming language and framework HTTP library or SDK you're using Last 4 digits of your API key Error messages (full text) HTTP status codes 3. Code example (sanitized) // Remove your full API key! const response = await fetch('https://api.cathopic.com/resources', { method: 'POST', headers: { 'x-api-key': '••••1234', // Last 4 digits only 'Content-Type': 'application/json' }, body: JSON.stringify({ query: 'test' }) }); console.log(response.status); // 401 console.log(await response.json()); // {"error": "Unauthorized"} 4. Request/response details Request headers Request body Response status Response body Timestamp of the issue Before contacting support Try these first to save time: Check the API documentation Review questions in this help section Test with curl to isolate the issue Verify your API key is active in Settings → API Check your payment method is valid Response time We aim to respond to developer support inquiries within 24-48 hours on business days. Complex issues may require additional investigation time. For urgent issues If you're experiencing a critical production outage: Mark your support request as "Urgent" Provide your account email for priority identification Include impact details (number of users affected, revenue impact, etc.) API status Before reporting an outage, check if there's a known issue: Test basic connectivity: curl https://api.cathopic.com/resources Check our status page (if available) Look for announcements in your account dashboard Additional resources Full API documentation: api.cathopic.com/docs Account dashboard: cathopic.com/settings/api General support: cathopic.com/support License information: cathopic.com/legal/license We're here to help make your integration successful!

Developer / API

Getting started

API keys, billing & security

Catalog, search & licensing

OAuth applications

Connected apps

Troubleshooting