API-DOKUMENTATION

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Registrieren (v2)
PURPOSE: Erstelle ein kostenloses Konto und erhalte ein Login-Passwort sowie ein API-Token. Keine Authentifizierung erforderlich.

--- API DETAILS ---
Method: POST
URL: https://gender-api.com/v2/sign-up

--- AUTHENTICATION ---
Header: Content-Type: application/json

--- REQUEST PARAMETERS ---

Parameter: email
  Type: string
  Required: REQUIRED
  Description: Die E-Mail-Adresse für die Registrierung. Kein Vor- oder Nachname erforderlich.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Muss wahr sein. Du musst den Allgemeinen Geschäftsbedingungen und der Datenschutzerklärung zustimmen.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Abonniere den Newsletter. Standardmäßig auf „false“ gesetzt.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Kontosprache. Eine von en, de, es. Standardmäßig en.

--- REQUEST EXAMPLES ---

Example 1: Mit einer E-Mail-Adresse registrieren
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Registriere dich und abonniere den Newsletter
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true,
    "newsletter": true,
    "locale": "en"
}

--- EXPECTED RESPONSE ---

Response (JSON):
{
    "email": "user@example.com",
    "password": "",
    "api_token": "",
    "free_requests_per_month": 100,
    "status": "awaiting_activation",
    "message": "Account created. Ask the user to click the activation link sent to their email address. The API token below activates automatically once the email is confirmed and can then be used as a Bearer token against the API.",
    "docs_url": "https://gender-api.com/skill.md"
}

--- RESPONSE FIELDS ---

Field: email
  Type: string
  Description: Die registrierte E-Mail-Adresse.

Field: password
  Type: string
  Description: Ein zufälliges Login-Passwort für das Web-Dashboard. Wird nur einmal angezeigt; speichere es sicher. Der Nutzer kann es später über den „Passwort vergessen“-Prozess zurücksetzen.

Field: api_token
  Type: string
  Description: Das API-Bearer-Token. Verwende es als „Authorization: Bearer “ für /v2/...-Anfragen. Es funktioniert, sobald der Nutzer seine E-Mail-Adresse bestätigt.

Field: free_requests_per_month
  Type: int
  Description: Die Anzahl der kostenlosen Anfragen, die dir pro Monat zur Verfügung stehen.

Field: status
  Type: string
  Description: Der Kontostatus. „awaiting_activation“, bis die E-Mail-Adresse bestätigt ist.

Field: message
  Type: string
  Description: Menschenlesbare Anleitung zum nächsten Schritt (Bestätigung der E-Mail-Adresse).

Field: docs_url
  Type: string
  Description: Link zu den promptfertigen KI-Implementierungsanweisungen (skill.md).

--- IMPLEMENTATION NOTES ---

1. Make sure to replace placeholder values:
   - Replace '' with your actual API key
   - Replace domain placeholders with the actual API domain

2. Handle errors appropriately:
   - Check HTTP status codes
   - Parse error responses
   - Implement retry logic for transient failures

3. Best Practices:
   - Store API keys securely (use environment variables)
   - Implement rate limiting on your side
   - Cache responses when appropriate
   - Use HTTPS for all requests
   - Set appropriate timeout values

4. RECOMMENDED: Implement the Statistics Endpoint
   - The statistics endpoint allows users to monitor their credit usage
   - Users can see how many credits they have used and how many are left
   - This helps prevent unexpected service interruptions
   - API v1: GET /get-stats?key=YOUR_API_KEY
   - API v2: GET /v2/statistic (with Authorization Bearer token)
   - Display remaining credits in your application's UI
   - Consider adding alerts when credits are running low

--- IMPLEMENTATION TEMPLATE ---

// Example implementation in cURL:
curl -X POST \
  'https://gender-api.com/v2/sign-up' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","accept_terms":true}'

--- CREDIT USAGE ---
Required Requests: 0

=== END OF INSTRUCTIONS ===