Blog API - Concordia

Overview

The Blog API provides comprehensive content management endpoints for articles, authors, categories, comments, and media. All Blog API endpoints require admin authentication.

Articles

List Articles

curl "https://your-domain.com/api/admin/blog/articles?page=1&perPage=20&status=published" \
  -H "Authorization: Bearer <token>"

{
  "articles": [
    {
      "id": "art_123",
      "slug": "welcome-to-concordia",
      "status": "published",
      "publishedAt": "2024-03-01T10:00:00Z",
      "isFeatured": true,
      "displayInHome": true,
      "displayInBlog": true,
      "translations": [
        {
          "inLanguage": "fr",
          "headline": "Bienvenue à Concordia"
        }
      ],
      "authors": ["John Doe"],
      "categoryIds": ["cat_001"]
    }
  ],
  "total": 150,
  "page": 1,
  "perPage": 20,
  "totalPages": 8
}

Query Parameters

integer

default:"1"

Page number (1-indexed)

integer

default:"20"

Items per page (max: 100)

string

Search by slug

string

Filter by status: draft, published, scheduled, archived

boolean

Filter featured articles (true or false)

boolean

Filter articles displayed on homepage

boolean

Filter articles displayed in blog listing

string

Filter by category ID

string

Filter by organization ID

string

Fetch single article by ID (returns full details with translations, authors, categories, media)

Create Article

From /src/pages/api/admin/blog/articles.ts:197-297:

curl -X POST "https://your-domain.com/api/admin/blog/articles" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d @article.json

{
  "action": "create",
  "slug": "welcome-post",
  "status": "draft",
  "inLanguage": "fr",
  "organizationId": "org_123",
  "displayInHome": true,
  "displayInBlog": true,
  "isFeatured": false,
  "allowComments": true,
  "readingTime": "5 min",
  "translations": [
    {
      "inLanguage": "fr",
      "headline": "Article de bienvenue",
      "articleBody": "Contenu de l'article...",
      "excerpt": "Courte description",
      "seoTitle": "Article SEO Title",
      "seoDescription": "Article SEO description"
    }
  ],
  "authorIds": ["author_001"],
  "categoryIds": ["cat_001", "cat_002"],
  "media": [
    {
      "mediaId": "media_123",
      "type": "cover",
      "position": "hero"
    }
  ]
}

{
  "ok": true,
  "id": "art_456",
  "slug": "welcome-post"
}

Request Body

string

required

Must be "create"

string

required

URL-friendly slug (auto-generated if not provided)

string

default:"draft"

Article status: draft, published, scheduled, archived

string

default:"fr"

Primary language code (ISO 639-1)

string

Organization ID (nullable)

boolean

default:"false"

Show on homepage

boolean

default:"true"

Show in blog listing

boolean

default:"false"

Mark as featured

boolean

default:"true"

Enable comments

string

Estimated reading time (e.g., “5 min”)

string

Article word count

array

Array of translation objects (see structure above)

string[]

Array of author IDs

string[]

Array of category IDs

array

Array of media objects with mediaId, type, position

Update Article

From /src/pages/api/admin/blog/articles.ts:299-409:

{
  "action": "update",
  "id": "art_456",
  "slug": "updated-slug",
  "status": "published",
  "isFeatured": true,
  "translations": [...],
  "authorIds": [...],
  "categoryIds": [...]
}

Updating an article replaces translations, authors, categories, and media (full replacement strategy).

Authors

List Authors

From /src/pages/api/admin/blog/authors.ts:19-98:

GET /api/admin/blog/authors?page=1&perPage=20

Query Parameters

string

Fetch single author by ID (includes article count)

boolean

Return all authors (for selectors) with minimal fields

string

Search by slug

boolean

Filter featured authors

boolean

Filter authors displayed on homepage

boolean

Filter authors displayed in blog

Create Author

From /src/pages/api/admin/blog/authors.ts:122-166:

{
  "action": "create",
  "slug": "john-doe",
  "displayName": { "fr": "John Doe", "en": "John Doe" },
  "givenName": { "fr": "John" },
  "familyName": { "fr": "Doe" },
  "bio": { "fr": "Auteur passionné" },
  "jobTitle": { "fr": "Journaliste" },
  "email": "john@example.com",
  "avatarUrl": "https://example.com/avatar.jpg",
  "website": "https://johndoe.com",
  "displayInHome": false,
  "displayInBlog": true,
  "isFeatured": false
}

Response

{
  "ok": true,
  "id": "author_789",
  "slug": "john-doe"
}

Update/Delete Author

From /src/pages/api/admin/blog/authors.ts:168-238:

// Update
{ "action": "update", "id": "author_789", "displayName": {...} }

// Delete
{ "action": "delete", "id": "author_789" }

Comments

List Comments

From /src/pages/api/admin/blog/comments.ts:13-66:

GET /api/admin/blog/comments?status=pending&page=1

Query Parameters

string

Filter by status: pending, approved, rejected

string

Filter by post type

string

Search by author name or email

Response

{
  "comments": [...],
  "total": 42,
  "page": 1,
  "perPage": 25,
  "totalPages": 2,
  "stats": {
    "pending": 12,
    "approved": 28,
    "rejected": 2
  }
}

Moderate Comments

From /src/pages/api/admin/blog/comments.ts:72-162:

{
  "action": "approve",
  "id": "comment_123"
}

{
  "action": "reject",
  "id": "comment_123"
}

{
  "action": "delete",
  "id": "comment_123"
}

Media

List Media

From /src/pages/api/admin/blog/media.ts:20-51:

GET /api/admin/blog/media?type=image&page=1&perPage=30

Query Parameters

string

Filter by media type: image, video, audio

string

Search by URL

Upload Media

From /src/pages/api/admin/blog/media.ts:57-210:

curl -X POST "https://your-domain.com/api/admin/blog/media" \
  -H "Authorization: Bearer <token>" \
  -F "file=@image.jpg" \
  -F "alt=Image description" \
  -F "caption=Photo caption" \
  -F "customName=my-image"

{
  "ok": true,
  "id": "media_999",
  "url": "/uploads/blog/my-image.jpg"
}

Configuration

Upload directory: public/uploads/blog
Max file size: 10 MB
Allowed types: JPEG, PNG, WebP, AVIF, GIF, SVG

Form Fields

File

required

Image file to upload

string

Custom filename (auto-sanitized)

string

Alt text for accessibility

string

Image caption

string

Detailed description

Update/Delete Media

From /src/pages/api/admin/blog/media.ts:66-115:

{
  "action": "update",
  "id": "media_999",
  "caption": { "fr": "Nouvelle légende" },
  "alt": { "fr": "Nouveau texte alternatif" }
}

{
  "action": "delete",
  "id": "media_999"
}

Deleting media also removes the file from disk.

Common Response Codes

Code	Description
200	Success
201	Created
400	Invalid request (missing fields, invalid action)
403	Not admin (forbidden)
404	Resource not found
500	Server error

Audit Logging

All Blog API actions are logged to audit_log table:

blog.article.create
blog.article.update
blog.article.delete
blog.article.publish
blog.article.unpublish
blog.article.duplicate
blog.author.create
blog.author.update
blog.author.delete
blog.category.create
blog.category.update
blog.category.delete
blog.comment.approve
blog.comment.reject
blog.comment.delete
blog.media.upload
blog.media.delete

API Overview

Authentication and rate limiting

Services API

Manage service listings

​Overview

​Articles

​List Articles

​Query Parameters

​Create Article

​Request Body

​Update Article

​Other Article Actions

​Publish Article

​Unpublish Article

​Delete Article

​Duplicate Article

​Authors

​List Authors

​Query Parameters

​Create Author

​Response

​Update/Delete Author

​Categories

​List Categories

​Query Parameters

​Create Category

​Comments

​List Comments

​Query Parameters

​Response

​Moderate Comments

​Media

​List Media

​Query Parameters

​Upload Media

​Configuration

​Form Fields

​Update/Delete Media

​Common Response Codes

​Audit Logging

​Related Resources

API Overview

Services API

Overview

Articles

List Articles

Query Parameters

Create Article

Request Body

Update Article

Other Article Actions

Publish Article

Unpublish Article

Delete Article

Duplicate Article

Authors

List Authors

Query Parameters

Create Author

Response

Update/Delete Author

Categories

List Categories

Query Parameters

Create Category

Comments

List Comments

Query Parameters

Response

Moderate Comments

Media

List Media

Query Parameters

Upload Media

Configuration

Form Fields

Update/Delete Media

Common Response Codes

Audit Logging

Related Resources