API Endpoints

This page provides a comprehensive overview of all available Wortfreunde API endpoints.

Base URL

All API requests should be made to:

https://api.wortfreunde.ch/v1

Authentication

All endpoints require authentication via API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Available Endpoints

Channels

Method	Endpoint	Description
GET	/channels	List all channels
GET	/channels/{id}	Get a specific channel

Posts

Method	Endpoint	Scope	Description
GET	/channels/:channel_id/posts	read:posts	List all posts by channel
GET	/channels/:channel_id/posts/:id	read:posts	Get a specific post with all details
PATCH	/channels/:channel_id/posts/:id/publish	write:posts	Confirm publication of a pending post
PATCH	/channels/:channel_id/posts/:id/unpublish	write:posts	Revert a published post to draft

SSO

Method	Endpoint	Scope	Description
POST	/sso_tokens	write:sso	Create a one-time SSO login token

Request Format

Headers

All requests should include these headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body

POST and PUT requests should send JSON data:

{
  "title": "Article Title",
  "content": "Article content...",
  "status": "draft"
}

Response Format

Success Response

{
  "data": {
    "id": "123",
    "title": "Article Title",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required",
    "details": {
      "field": "title",
      "rule": "required"
    }
  }
}

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max: 100)

Example: http GET /channels?page=2&limit=2

Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pages": 1,
    "count": 5,
    "per_page": 20
  }
}

Filtering

⚠️ Warnung

Filtering has not been implemented yet.

Most list endpoints support filtering:

GET /posts?status=published&tag=api

Rate Limiting

⚠️ Warnung

Rate limiting has not been implemented yet.

API requests are rate-limited based on your plan:

Plan	Requests/Hour
Free	1,000
Starter	10,000
Professional	50,000
Enterprise	Unlimited

Rate limit headers are included in all responses:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9995
X-RateLimit-Reset: 1640995200

Status Codes

Code	Description
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Too Many Requests
500	Internal Server Error