Integration Guide

Authentication

All API requests to the upload endpoint require authentication via a Bearer token. Generate an API Key within your Ceyon Dashboard and include it in your HTTP headers:

Authorization: Bearer cyn_YOUR_API_KEY

Supported File Types

Ceyon securely handles web-compatible imagery, plain text, documents, code files, and media (video/audio).

When sending programmatic payloads, compile your assets as Base64 data URLs. Ceyon automatically extracts and saves the correct extension based on your originalName attribute.

Method 1: Displaying & Serving Assets

Ceyon serves different asset categories based on their target usability. The URL matches the clean ID structure generated upon upload:

• Images: Served inline directly with standard caching, optimal for embedding in your code (e.g. <img src="...">).
• PDFs: Served inline directly so browsers render them instantly inside interactive preview tabs.
• Code & Text files: Files like .html, .js, .css, or .json are served cleanly as text/plain by default. This enables direct raw source code views in the browser instead of executing them!

<!-- Use the returned CDN URL directly in your HTML frontend -->
<img src="https://ceyon.netlify.app/asset/CEYONmoac22recwqm7kyvcgszuo" alt="Ceyon Edge Asset" />

Method 2: Client-Side Upload (Browser)

Use client-side scripts to upload files on the fly. Pass the Base64 representation along with the file's metadata directly to the upload endpoint:

// 1. Grab file from input element
const file = document.getElementById('fileInput').files[0];
const reader = new FileReader();

reader.onload = async () => {
  // 2. Upload Base64 representation directly to the API
  const response = await fetch("https://ceyon.netlify.app/api/upload", {
    method: "POST",
    headers: {
      "Authorization": "Bearer cyn_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ 
      base64: reader.result, 
      visibility: "public",
      originalName: file.name
    })
  });

  const data = await response.json();
  console.log("Success! CDN URL:", data.url);
};

reader.readAsDataURL(file);

Integrate your server or build scripts to programmatically push assets during CI/CD. Ceyon parses any of the standard metadata keys (originalName, name, or fileName).

Method 4: Downloading Assets with Branded Names

Append the query parameter ?download=1 (or ?dl=1) to force an instantaneous download instead of an inline preview. Downloaded assets automatically receive custom Ceyon copyright branding while cleanly maintaining their original file extensions.

<!-- Direct branded attachment download -->
<a href="https://ceyon.netlify.app/asset/CEYONabc123?download=1">
  Download File
</a>

<!-- Saved locally as: "© Ceyon | CDN - CEYONabc123.png" -->

Method 5: Overwriting & Replacing Assets

Update or patch file contents globally on the CDN without breaking your live links. Send a PUT request specifying the existing target id. This preserves view logs and date metadata.

const response = await fetch("https://ceyon.netlify.app/api/upload", {
  method: "PUT", // <-- Put ensures we edit the existing record
  headers: {
    "Authorization": "Bearer cyn_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ 
    id: "CEYONmoac22recwqm7kyvcgszuo", // Overwrites this asset ID
    base64: "data:text/css;base64,...",
    originalName: "styles.css"
  })
});

const data = await response.json();
console.log("Successfully overwritten!", data);

CORS & Domain Restrictions

For security, you can restrict where your assets can be viewed or fetched. Domain restrictions can be applied at the **Project level** or the individual **API Key level**:

• Allowed Domains: You can define a comma-separated list of domains (e.g. example.com, myapp.com). You can also append a wildcard to explicitly allow everything under it (e.g. example.com/*).
• Subdomains: Specifying example.com automatically whitelists all nested subdomains (e.g. api.example.com, dashboard.example.com).
• Global Access: Use * to permit unrestricted asset delivery across all origins on the web.

AI Crawler & Scraper Compatibility

Ceyon is designed to be fully compatible with AI models and search engine scrapers. When crawlers like ChatGPT (GPTBot), Anthropic (ClaudeBot), Google, or social embeds access your public assets, Ceyon automatically detects them and bypasses standard CORS and domain restrictions.