API Documentation - My-Coach-Finder

Was ist eine API?

Eine API (Application Programming Interface) ist eine Schnittstelle, die es Ihnen ermöglicht, Ihre eigene Website, App oder Software mit My-Coach-Finder zu verbinden. So können Sie automatisch Daten austauschen und Funktionen integrieren.

Warum die API nutzen?

Automatische Synchronisation Ihrer Coach-Daten mit Ihrer eigenen Website
Integration von Coaching-Buchungen in Ihre bestehende Software
Entwicklung eigener mobiler Apps oder Tools
Automatisierung von Arbeitsabläufen und Prozessen

Für wen ist die API?

Die API ist primär für Entwickler und technische Teams gedacht. Als Coach ohne technische Kenntnisse können Sie die normale Plattform nutzen - alle Funktionen sind dort bereits integriert und einfach zu bedienen.

Brauchen Sie technische Unterstützung? Kontaktieren Sie uns für individuelle Integrationslösungen.

Erste Schritte

Die My-Coach-Finder API basiert auf REST. Unsere API hat vorhersagbare, ressourcenorientierte URLs, akzeptiert JSON-kodierte Request-Bodies, gibt JSON-kodierte Antworten zurück und verwendet standardisierte HTTP-Statuscodes.

Basis-URL

https://my-coach-finder.com

Interaktive Dokumentation

Testen Sie alle Endpunkte interaktiv mit Swagger UI oder durchsuchen Sie sie mit ReDoc:

Swagger UI ReDoc OpenAPI JSON

Authentication

The API uses JWT (JSON Web Tokens) for authentication. Include your access token in the Authorization header of each request.

Step 1: Register or Login

First, create an account or login to get your access token:

curl -X POST https://my-coach-finder.com/auth/register \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=your@email.com" \
  -d "password=YourSecurePassword123!" \
  -d "first_name=John" \
  -d "last_name=Doe"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 10080
}

Step 2: Use the Token

Include the token in the Authorization header for all protected endpoints:

curl https://my-coach-finder.com/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

API Token (Alternative)

For server-to-server integrations, generate a permanent API token from your settings page:

curl -X POST https://my-coach-finder.com/auth/generate-api-token \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Rate Limiting

Rate limits protect the API from abuse and ensure fair usage:

Registration

3 requests / hour

Login

5 requests / minute

2FA Verification

3 requests / minute

General API

100 requests / minute

API Endpoints

The API provides 141 endpoints across multiple resource categories:

Authentication Endpoints

POST /auth/register

Register a new user account. Automatically creates both coach and coachee profiles.

POST /auth/login

Authenticate with email and password. Returns JWT access token (7 days validity).

GET /auth/me

Get current authenticated user information.

POST /auth/change-password

Change user password (requires current password).

PUT /auth/update-profile

Update user profile (first name, last name).

Chat Endpoints

GET /chat/conversations

Get all conversations for the current user with unread counts.

GET /chat/conversations/{conversation_id}/messages

Get all messages in a conversation (automatically marks as read).

POST /chat/messages

Send a new message to a user. Creates conversation if it doesn't exist.

GET /chat/users/search?query={query}

Search users to start a new conversation.

Documents Endpoints

POST /documents/upload

Upload a document (PDF, images, etc.). Max 50MB. Supports multipart/form-data.

GET /documents/

Get all documents for the current user.

GET /documents/stats/summary

Get document statistics (total count, size, public documents).

DELETE /documents/{document_id}

Delete a document and its file from storage.

Blog Endpoints

POST /api/blog/

Create a new blog post (draft by default).

GET /api/blog/my-posts

Get all blog posts for the current user (including drafts).

GET /api/blog/public

Get all published blog posts (public, no authentication required).

POST /api/blog/{post_id}/publish

Publish a draft blog post (generates SEO-friendly slug).

POST /api/blog/ai/generate-content

Generate blog post content using AI based on topic and keywords.

AI Services Endpoints

POST /ai/summarize

Summarize long text using GPT-4o-mini.

POST /ai/improve-text

Improve text quality (grammar, clarity, professionalism).

POST /ai/suggest-goals

Get AI-suggested coaching goals based on context.

POST /presentation/scrape-website

AI-powered website scraping to extract coach bio, services, and testimonials.

Error Handling

The API uses standard HTTP response codes and returns JSON error objects:

HTTP Status Codes

200 OK - Request succeeded

201 Created - Resource created successfully

400 Bad Request - Invalid parameters

401 Unauthorized - Invalid or missing token

403 Forbidden - No permission

404 Not Found - Resource doesn't exist

429 Too Many Requests - Rate limit exceeded

500 Internal Server Error - Server error

Error Response Format

{
  "detail": "Incorrect email or password"
}

Code Examples

Complete examples showing how to authenticate and use the API in different programming languages.

Python Example (with requests)

import requests

# Register a new user
response = requests.post(
    'https://my-coach-finder.com/auth/register',
    data={
        'email': 'coach@example.com',
        'password': 'SecurePass123!',
        'first_name': 'John',
        'last_name': 'Doe'
    }
)

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

# Get user info
user = requests.get(
    'https://my-coach-finder.com/auth/me',
    headers={'Authorization': f'Bearer {token}'}
).json()

print(f"Logged in as: {user['first_name']} {user['last_name']}")

# Send a chat message
message = requests.post(
    'https://my-coach-finder.com/chat/messages',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'recipient_id': 123,
        'content': 'Hello, I would like to book a session'
    }
).json()

print(f"Message sent: {message['id']}")

PHP Example (with cURL)

<?php

// Register a new user
$ch = curl_init('https://my-coach-finder.com/auth/register');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query([
    'email' => 'coach@example.com',
    'password' => 'SecurePass123!',
    'first_name' => 'John',
    'last_name' => 'Doe'
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
$token = $data['access_token'];

// Get user info
$ch = curl_init('https://my-coach-finder.com/auth/me');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$userResponse = curl_exec($ch);
curl_close($ch);

$user = json_decode($userResponse, true);
echo "Logged in as: {$user['first_name']} {$user['last_name']}\n";

// Get blog posts
$ch = curl_init('https://my-coach-finder.com/api/blog/public');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$postsResponse = curl_exec($ch);
curl_close($ch);

$posts = json_decode($postsResponse, true);
echo "Total blog posts: " . count($posts) . "\n";

?>

PHP Example (with Guzzle)

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://my-coach-finder.com']);

// Register a new user
$response = $client->post('/auth/register', [
    'form_params' => [
        'email' => 'coach@example.com',
        'password' => 'SecurePass123!',
        'first_name' => 'John',
        'last_name' => 'Doe'
    ]
]);

$data = json_decode($response->getBody(), true);
$token = $data['access_token'];

// Get user conversations
$response = $client->get('/chat/conversations', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ]
]);

$conversations = json_decode($response->getBody(), true);
echo "You have " . count($conversations) . " conversations\n";

// Upload a document
$response = $client->post('/documents/upload', [
    'headers' => [
        'Authorization' => 'Bearer ' . $token
    ],
    'multipart' => [
        [
            'name' => 'file',
            'contents' => fopen('/path/to/document.pdf', 'r'),
            'filename' => 'document.pdf'
        ],
        [
            'name' => 'is_public',
            'contents' => 'false'
        ]
    ]
]);

$document = json_decode($response->getBody(), true);
echo "Document uploaded: {$document['id']}\n";

?>

JavaScript Example (Fetch API)

// Login
const loginResponse = await fetch('https://my-coach-finder.com/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    email: 'coach@example.com',
    password: 'SecurePass123!'
  })
});

const { access_token } = await loginResponse.json();

// Get conversations
const conversations = await fetch('https://my-coach-finder.com/chat/conversations', {
  headers: { 'Authorization': `Bearer ${access_token}` }
}).then(res => res.json());

console.log(`You have ${conversations.length} conversations`);

// Create a blog post
const blogPost = await fetch('https://my-coach-finder.com/api/blog/', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${access_token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'My First Blog Post',
    content: 'This is the content of my blog post',
    excerpt: 'A short preview',
    category: 'Life Coaching'
  })
}).then(res => res.json());

console.log(`Blog post created with ID: ${blogPost.id}`);

cURL Examples

# Upload a document
curl -X POST https://my-coach-finder.com/documents/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf" \
  -F "is_public=false"

# Get AI-generated blog content
curl -X POST https://my-coach-finder.com/api/blog/ai/generate-content \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Life Coaching Tips",
    "keywords": ["motivation", "goals", "success"],
    "tone": "professional"
  }'

# Search for coaches
curl "https://my-coach-finder.com/api/coaches/search?query=life+coach&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get chat messages
curl https://my-coach-finder.com/chat/conversations/42/messages \
  -H "Authorization: Bearer YOUR_TOKEN"

SDKs & Tools

OpenAPI / Swagger

Download our OpenAPI specification to generate client SDKs in any language:

Download OpenAPI JSON

Postman Collection

Import our OpenAPI spec into Postman for easy API testing and exploration.

Support

Need help with the API? Contact us at api@my-coach-finder.com

API Dokumentation