fined| Set to"true"to force filtering for published articles only | |slug| DELETE |string` | required | Unique identifier of the article to delete |

Request Body (POST)

The POST method accepts a JSON payload containing an articles array. Each object supports the following fields:

Field	Type	Required	Description
slug	string	✅	Unique URL-friendly identifier. Used for upsert logic
titleEn	string	✅	English title of the article
contentEn	string	✅	Markdown-formatted article body
excerptEn	string	❌	Short summary for listings
descriptionEn	string	❌	Full description for SEO/social sharing
seoTitle	string	❌	Custom SEO title. Falls back to titleEn
seoDescription	string	❌	Custom SEO description. Falls back to descriptionEn
isPremium	boolean	❌	Marks article as premium content. Defaults to true
isPublished	boolean	❌	Controls visibility. Defaults to true
categorySlug	string	❌	Slug of an existing category to link the article to

Response Format

Success Responses

POST (Bulk Create/Update)

{
  "success": true,
  "processed": 2,
  "results": [
    {
      "slug": "react-hooks-guide",
      "status": "created",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "categoryLinked": "frontend"
    },
    {
      "slug": "nextjs-auth",
      "status": "updated",
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012"
    }
  ]
}

GET (Paginated Listing)

{
  "articles": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "slug": "react-hooks-guide",
      "titleEn": "Mastering React Hooks",
      "excerptEn": "A practical guide to useState and useEffect...",
      "descriptionEn": "Deep dive into React's component lifecycle...",
      "isPremium": true,
      "isPublished": true,
      "publishedAt": "2024-05-10T14:30:00Z",
      "viewCount": 1240,
      "categories": [
        { "slug": "frontend", "name": "Frontend Development" }
      ]
    }
  ],
  "total": 2840,
  "limit": 20,
  "offset": 0
}

DELETE

{
  "success": true,
  "deleted": "react-hooks-guide"
}

Error Responses

All error responses return a JSON object with an error string and the corresponding HTTP status code:

Status	Condition	Example Payload
400	Missing required fields or invalid slug parameter	{"error": "articles array is required"}
401	Missing or invalid authentication token	{"error": "Authentication required"}
403	Non-admin user attempting DELETE	{"error": "Admin permissions required to delete articles"}
429	Rate limit exceeded	{"error": "Rate limit exceeded. Try again later."}
500	Database or validation failure	{"error": "Internal server error"}

Usage Example

Below is a curl command demonstrating a bulk article creation/update request:

curl -X POST https://codcompass.com/api/articles \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "articles": [
      {
        "slug": "typescript-generics",
        "titleEn": "Understanding TypeScript Generics",
        "contentEn": "# Generics in TypeScript\\n\\nGenerics allow you to create reusable components...",
        "excerptEn": "Learn how to write flexible, type-safe functions.",
        "isPremium": false,
        "isPublished": true,
        "categorySlug": "typescript"
      }
    ]
  }'

Common Pitfalls

1. Implicit Upsert Behavior via Slug
   The POST endpoint does not require an id field. Instead, it queries the database by slug. If a matching slug exists, the article is updated; otherwise, it is created. Ensure your slugs are stable and unique across your content pipeline to avoid unintended overwrites.

2. Category Linking Requires Pre-existing Slugs
   The categorySlug field only creates a relationship if the category already exists in the database. If you pass a slug that doesn't match a record in the Category table, the link is silently skipped. Always verify category slugs via /api/categories before publishing articles that depend on them.

3. Strict Content Validation & Auto-Cleaning
   Every contentEn payload passes through a strict markdown validator. Malformed syntax, missing source attribution, or unsafe HTML triggers a rejected status in the response. The validator also applies auto-cleaning, which may strip certain markdown artifacts. Always inspect the results[].status field and monitor server logs for [Articles API] Warnings to catch silent transformations.

Related Endpoints

• /api/categories — Create, update, and list category slugs required for article linking.
• /api/auth — Generate API keys, rotate secrets, and manage user session tokens for authenticated requests.
• /api/search — Perform full-text search across published articles using indexed content and metadata.