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:

GET /channels?page=2&limit=2

Pagination Response

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

Filtering

Filtering has not been implemented yet.

Most list endpoints support filtering:

GET /posts?status=published&tag=api

Rate Limiting

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

Hilfe