Referenční příručka API

CatCMS poskytuje komplexní REST API pro programovou správu obsahu, kolekcí, médií a autentizace. Je postaveno na Cloudflare Workers s tříúrovňovým systémem mezipaměti pro optimální výkon.[object Object]

Úvod[object Object]

Základní URL

https://your-domain.com/api

Pro lokální vývoj:

http://localhost:8787/api

Interaktivní dokumentace API

CatCMS obsahuje interaktivní průzkumník API poháněný Scalar UI. Přistupovat k němu můžete na adrese:

http://localhost:8787/docs

Specifikace OpenAPI

Získejte kompletní specifikaci OpenAPI 3.0:

curl -X GET "http://localhost:8787/api/"

Autentizace[object Object]

Většina API endpointů vyžaduje autentizaci. CatCMS používá JWT (JSON Web Tokens) s HTTP-only cookies pro webové klienty a Bearer tokeny pro API klienty.

Přihlášení

Získejte přístupový token ověřením pomocí svých přihlašovacích údajů.

curl -X POST "http://localhost:8787/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@catcms.app",
    "password": "admin123"
  }'

const response = await fetch('http://localhost:8787/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'admin@catcms.app',
    password: 'admin123',
  }),
})

const { user, token } = await response.json()

import requests

response = requests.post('http://localhost:8787/auth/login', json={
    'email': 'admin@catcms.app',
    'password': 'admin123'
})

data = response.json()
token = data['token']

Login Request

Login Response

{
  "user": {
    "id": "admin-user-id",
    "email": "admin@catcms.app",
    "username": "admin",
    "firstName": "Admin",
    "lastName": "User",
    "role": "admin"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "error": "Invalid email or password"
}

Použití tokenu

Zahrňte token do hlavičky Authorization u všech autentizovaných požadavků:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pro aplikace běžící v prohlížeči je token automaticky uložen jako HTTP-only cookie s názvem auth_token.

Registrace

Vytvořte nový uživatelský účet.

curl -X POST "http://localhost:8787/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "securepassword123",
    "username": "newuser",
    "firstName": "John",
    "lastName": "Doe"
  }'

const response = await fetch('http://localhost:8787/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'newuser@example.com',
    password: 'securepassword123',
    username: 'newuser',
    firstName: 'John',
    lastName: 'Doe',
  }),
})

const { user, token } = await response.json()

Register Request

Získat aktuálního uživatele

Získejte informace o aktuálně přihlášeném uživateli.

curl -X GET "http://localhost:8787/auth/me" \
  -H "Authorization: Bearer {token}"

const response = await fetch('http://localhost:8787/auth/me', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

const { user } = await response.json()

Get User Request

Obnovit token

Obnovte svůj přístupový token, než vyprší jeho platnost.

curl -X POST "http://localhost:8787/auth/refresh" \
  -H "Authorization: Bearer {token}"

Odhlášení

Ukončete svou relaci.

curl -X POST "http://localhost:8787/auth/logout"

Kolekce[object Object]

Vypsat všechny kolekce

Získejte všechny aktivní kolekce s jejich schématy.

Autentizace: Nevyžaduje se Mezipaměť: 5 minut

curl -X GET "http://localhost:8787/api/collections"

const response = await fetch('http://localhost:8787/api/collections')
const { data, meta } = await response.json()

import requests

response = requests.get('http://localhost:8787/api/collections')
data = response.json()

List Collections

Collections Response

{
  "data": [
    {
      "id": "blog-posts-collection-id",
      "name": "blog-posts",
      "display_name": "Blog Posts",
      "description": "Blog posts collection",
      "schema": {
        "name": "blog-posts",
        "displayName": "Blog Posts",
        "fields": [
          {
            "name": "title",
            "type": "text",
            "label": "Title",
            "required": true
          },
          {
            "name": "content",
            "type": "richtext",
            "label": "Content"
          },
          {
            "name": "featuredImage",
            "type": "media",
            "label": "Featured Image"
          }
        ]
      },
      "is_active": 1,
      "created_at": 1730000000,
      "updated_at": 1730000000
    }
  ],
  "meta": {
    "count": 1,
    "timestamp": "2025-10-06T12:34:56.789Z",
    "cache": {
      "hit": false,
      "source": "database"
    },
    "timing": {
      "total": 45,
      "execution": 12,
      "unit": "ms"
    }
  }
}

Správa obsahu[object Object]

Vypsat veškerý obsah

Získejte všechny položky obsahu se stránkováním a filtrováním.

Autentizace: Nevyžaduje se Mezipaměť: 5 minut

Parametry dotazu:

limit - Maximální počet položek k vrácení (výchozí: 50, max: 100)
offset - Počet položek k přeskočení pro stránkování
sort - Pole pro řazení (jako prefix použijte - pro sestupné řazení)
filter - Pokročilé filtrování (viz Filtrování a dotazování)

curl -X GET "http://localhost:8787/api/content?limit=10"

const response = await fetch('http://localhost:8787/api/content?limit=10')
const { data, meta } = await response.json()

import requests

response = requests.get('http://localhost:8787/api/content', params={
    'limit': 10
})
data = response.json()

List Content

Získat obsah podle kolekce

Získejte obsah pro konkrétní kolekci.

Autentizace: Nevyžaduje se Mezipaměť: 5 minut

curl -X GET "http://localhost:8787/api/collections/blog-posts/content?limit=25"

const response = await fetch('http://localhost:8787/api/collections/blog-posts/content?limit=25')
const { data, meta } = await response.json()

Get Collection Content

Získat jednu položku obsahu

Získejte konkrétní položku obsahu podle ID.

Autentizace: Nevyžaduje se Mezipaměť: 5 minut

curl -X GET "http://localhost:8787/api/content/{id}"

const response = await fetch(`http://localhost:8787/api/content/${id}`)
const { data } = await response.json()

Get Content

Vytvořit obsah

Vytvořte novou položku obsahu.

Autentizace: Vyžaduje se Oprávnění: Role Editor nebo Admin

curl -X POST "http://localhost:8787/api/content" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "collectionId": "blog-posts-collection-id",
    "title": "My New Blog Post",
    "slug": "my-new-blog-post",
    "status": "draft",
    "data": {
      "title": "My New Blog Post",
      "content": "<p>This is my blog post content...</p>",
      "excerpt": "A brief description"
    }
  }'

const response = await fetch('http://localhost:8787/api/content', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    collectionId: 'blog-posts-collection-id',
    title: 'My New Blog Post',
    slug: 'my-new-blog-post',
    status: 'draft',
    data: {
      title: 'My New Blog Post',
      content: '<p>This is my blog post content...</p>',
      excerpt: 'A brief description',
    },
  }),
})

const { data } = await response.json()

Create Content

Aktualizovat obsah

Aktualizujte existující položku obsahu.

Autentizace: Vyžaduje se Oprávnění: Vlastník obsahu, role Editor nebo Admin

curl -X PUT "http://localhost:8787/api/content/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Blog Post Title",
    "status": "published",
    "data": {
      "title": "Updated Blog Post Title",
      "content": "<p>Updated content...</p>"
    }
  }'

const response = await fetch(`http://localhost:8787/api/content/${id}`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Updated Blog Post Title',
    status: 'published',
    data: {
      title: 'Updated Blog Post Title',
      content: '<p>Updated content...</p>',
    },
  }),
})

const { data } = await response.json()

Update Content

Smazat obsah

Smažte položku obsahu.

Autentizace: Vyžaduje se Oprávnění: Vlastník obsahu, role Editor nebo Admin

curl -X DELETE "http://localhost:8787/api/content/{id}" \
  -H "Authorization: Bearer {token}"

const response = await fetch(`http://localhost:8787/api/content/${id}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

const { success } = await response.json()

Delete Content

Správa médií[object Object]

Všechny endpointy pro média vyžadují autentizaci.

Nahrát jeden soubor

Nahrát soubor do úložiště Cloudflare R2.

Autentizace: Vyžaduje se Content-Type: multipart/form-data Maximální velikost souboru: 50 MB

Podporované typy souborů:

Obrázky: JPEG, PNG, GIF, WebP, SVG
Dokumenty: PDF, TXT, DOC, DOCX
Videa: MP4, WebM, OGG, AVI, MOV
Audio: MP3, WAV, OGG, M4A

curl -X POST "http://localhost:8787/api/media/upload" \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/image.jpg" \
  -F "folder=blog-images"

const formData = new FormData()
formData.append('file', fileInput.files[0])
formData.append('folder', 'blog-images')

const response = await fetch('http://localhost:8787/api/media/upload', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
  body: formData,
})

const { success, file } = await response.json()

Upload File

Upload Response

{
  "success": true,
  "file": {
    "id": "V1StGXR8_Z5jdHi6B",
    "filename": "V1StGXR8_Z5jdHi6B.jpg",
    "originalName": "my-image.jpg",
    "mimeType": "image/jpeg",
    "size": 245678,
    "width": 1920,
    "height": 1080,
    "publicUrl": "https://pub-catcms-media-dev.r2.dev/blog-images/V1StGXR8_Z5jdHi6B.jpg",
    "thumbnailUrl": "https://imagedelivery.net/account-id/blog-images/V1StGXR8_Z5jdHi6B.jpg/thumbnail",
    "uploadedAt": "2025-10-06T12:34:56.789Z"
  }
}

{
  "error": "File validation failed",
  "details": [
    {
      "code": "too_big",
      "message": "File size exceeds 50MB limit",
      "path": ["size"]
    }
  ]
}

Nahrát více souborů

Nahrát více souborů v jednom požadavku.

Autentizace: Vyžaduje se

curl -X POST "http://localhost:8787/api/media/upload-multiple" \
  -H "Authorization: Bearer {token}" \
  -F "files=@/path/to/image1.jpg" \
  -F "files=@/path/to/image2.png" \
  -F "folder=gallery"

const formData = new FormData()
for (const file of fileInput.files) {
  formData.append('files', file)
}
formData.append('folder', 'gallery')

const response = await fetch('http://localhost:8787/api/media/upload-multiple', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
  body: formData,
})

const { success, uploaded, errors, summary } = await response.json()

Upload Multiple Files

Aktualizovat metadata souboru

Aktualizovat metadata souboru (alt text, popisek, štítky, složka).

Autentizace: Vyžaduje se Oprávnění: Role Uploader nebo Admin

curl -X PATCH "http://localhost:8787/api/media/{id}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "alt": "Beautiful sunset over the ocean",
    "caption": "Sunset at Malibu Beach",
    "tags": ["nature", "sunset", "ocean"],
    "folder": "featured-images"
  }'

const response = await fetch(`http://localhost:8787/api/media/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    alt: 'Beautiful sunset over the ocean',
    caption: 'Sunset at Malibu Beach',
    tags: ['nature', 'sunset', 'ocean'],
    folder: 'featured-images',
  }),
})

const { success } = await response.json()

Update File

Smazat soubor

Smazat jeden soubor.

Autentizace: Vyžaduje se Oprávnění: Role Uploader nebo Admin

curl -X DELETE "http://localhost:8787/api/media/{id}" \
  -H "Authorization: Bearer {token}"

const response = await fetch(`http://localhost:8787/api/media/${id}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${token}`,
  },
})

const { success } = await response.json()

Delete File

Hromadné mazání souborů

Smazat více souborů v jednom požadavku.

Autentizace: Vyžaduje se Max souborů: 50 na požadavek

curl -X POST "http://localhost:8787/api/media/bulk-delete" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileIds": ["file-id-1", "file-id-2", "file-id-3"]
  }'

const response = await fetch('http://localhost:8787/api/media/bulk-delete', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileIds: ['file-id-1', 'file-id-2', 'file-id-3'],
  }),
})

const { success, deleted, errors, summary } = await response.json()

Bulk Delete

Hromadný přesun souborů

Přesunout více souborů do jiné složky.

Autentizace: Vyžaduje se Max souborů: 50 na požadavek

curl -X POST "http://localhost:8787/api/media/bulk-move" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileIds": ["file-id-1", "file-id-2"],
    "targetFolder": "archived"
  }'

Bulk Move

Systémové endpointy[object Object]

Kontrola stavu

Zkontrolujte stav API a systému.

Autentizace: Nevyžaduje se

curl -X GET "http://localhost:8787/api/health"

const response = await fetch('http://localhost:8787/api/health')
const { status, schemas } = await response.json()

Health Check

Systémové informace

Získejte systémové informace a dostupné funkce.

Autentizace: Nevyžaduje se

curl -X GET "http://localhost:8787/api/system/info"

Systémové statistiky

Získejte statistiky databáze (počet obsahu, počet médií, počet uživatelů).

Autentizace: Vyžaduje se role Admin

curl -X GET "http://localhost:8787/api/system/stats" \
  -H "Authorization: Bearer {token}"

Ping databáze

Zkontrolujte připojení k databázi a latenci.

Autentizace: Nevyžaduje se

curl -X GET "http://localhost:8787/api/system/ping"

Filtrování a dotazování[object Object]

CatCMS poskytuje výkonné možnosti filtrování pro dotazy na obsah.

Filtrovací operátory

Operátor	Popis	Příklad
`equals`	Přesná shoda	`filter[status][equals]=published`
`not_equals`	Není rovno	`filter[status][not_equals]=draft`
`greater_than`	Větší než	`filter[price][greater_than]=100`
`less_than`	Menší než	`filter[price][less_than]=1000`
`like`	Vyhledávání bez ohledu na velikost písmen	`filter[title][like]=javascript`
`contains`	Řetězec obsahuje	`filter[tags][contains]=tutorial`
`in`	Hodnota v seznamu	`filter[category][in]=blog,news`
`not_in`	Hodnota není v seznamu	`filter[status][not_in]=draft,archived`
`exists`	Pole existuje	`filter[featuredImage][exists]=true`

Příklady filtrů

Jednoduchý filtr rovnosti:

curl "http://localhost:8787/api/content?filter[status][equals]=published"

Vícenásobné filtry (logika AND):

curl "http://localhost:8787/api/content?\
filter[status][equals]=published&\
filter[category][equals]=blog&\
filter[price][less_than]=100"

Vyhledávání pomocí LIKE:

curl "http://localhost:8787/api/content?filter[title][like]=getting started"

Filtr s operátorem IN:

curl "http://localhost:8787/api/content?filter[category][in]=blog,tutorial,guide"

Filtr rozmezí dat:

curl "http://localhost:8787/api/content?\
filter[created_at][greater_than]=2025-01-01&\
filter[created_at][less_than]=2025-12-31"

Řazení

Seřaďte výsledky podle libovolného pole. Jako prefix použijte - pro sestupné řazení.

# Sort by created_at descending
curl "http://localhost:8787/api/content?sort=-created_at"

# Sort by title ascending
curl "http://localhost:8787/api/content?sort=title"

Stránkování

Použijte limit a offset pro stránkování.

# Get first 10 items
curl "http://localhost:8787/api/content?limit=10&offset=0"

# Get next 10 items
curl "http://localhost:8787/api/content?limit=10&offset=10"

Ukládání do mezipaměti[object Object]

CatCMS implementuje tříúrovňový systém mezipaměti pro optimální výkon.

Úrovně mezipaměti

Paměťová mezipaměť - Mezipaměť v paměti (nejrychlejší, ~1-3 ms)
KV mezipaměť - Úložiště Cloudflare KV (rychlé, ~5-15 ms)
Databáze - Databáze D1 (pomalejší, ~20-50 ms)

Hlavičky mezipaměti

Každá odpověď API obsahuje informace o mezipaměti:

X-Cache-Status: HIT
X-Cache-Source: memory
X-Cache-TTL: 278
X-Response-Time: 3ms

Hlavičky:

X-Cache-Status - HIT nebo MISS
X-Cache-Source - memory, kv, nebo database
X-Cache-TTL - Zbývající TTL v sekundách (pouze pro zásahy do mezipaměti)
X-Response-Time - Celková doba odezvy

TTL mezipaměti

Zdroj	TTL	Paměť	KV
Odpovědi API	5 min	✓	✓
Kolekce	2 h	✓	✓
Obsah	1 h	✓	✓
Uživatelská data	15 min	✓	✓
Metadata médií	1 h	✓	✓

Zneplatnění mezipaměti

Mezipaměti jsou automaticky zneplatněny, když:

Je vytvořen, aktualizován nebo smazán obsah
Jsou upraveny kolekce
Jsou nahrány nebo smazány mediální soubory
Změní se uživatelská oprávnění

Zpracování chyb[object Object]

CatCMS používá standardní stavové kódy HTTP a vrací konzistentní chybové odpovědi.

Stavové kódy HTTP

Kód	Popis
200	Úspěch
201	Vytvořeno
400	Chybný požadavek
401	Neautorizováno
403	Zakázáno
404	Nenalezeno
500	Vnitřní chyba serveru

Formát chybové odpovědi

{
  "error": "Error message",
  "details": [
    {
      "code": "validation_error",
      "message": "Field is required",
      "path": ["fieldName"]
    }
  ]
}

Běžné chyby

401 Neautorizováno:

{
  "error": "Authentication required"
}

403 Zakázáno:

{
  "error": "Insufficient permissions"
}

404 Nenalezeno:

{
  "error": "Resource not found"
}

400 Chyba validace:

{
  "error": "Validation failed",
  "details": [
    {
      "code": "invalid_type",
      "message": "Expected string, received number",
      "path": ["title"]
    }
  ]
}

Omezení počtu požadavků

V současné době CatCMS nevynucuje omezení počtu požadavků. To se může v budoucích verzích změnit.

Pro produkční nasazení zvažte implementaci omezení počtu požadavků na úrovni Cloudflare Workers pomocí:

Cloudflare Rate Limiting
Vlastní middleware s využitím Cloudflare KV

Další kroky

Průvodce autentizací - Podrobný pohled na autentizaci a RBAC
Kolekce - Zjistěte více o schématech kolekcí a typech polí
Ukládání do mezipaměti - Porozumějte detailně systému mezipaměti
Testování - Napište testy pro své integrace API

Pro dotazy nebo podporu navštivte naši Komunita stránku.