API-DOCUMENTATIE

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Registreren (v2)
PURPOSE: Maak gratis een account aan en ontvang een inlogwachtwoord en een API-token. Geen authenticatie nodig.

--- 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: Het e-mailadres waarmee je je registreert. Een voor- of achternaam is niet nodig.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Moet waar zijn. Je gebruiker moet akkoord gaan met de Algemene voorwaarden en het privacybeleid.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Abonneer je op de nieuwsbrief. Standaard ingesteld op false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Taal van het account. Eén van: en, de, es. Standaard is en.

--- REQUEST EXAMPLES ---

Example 1: Meld je aan met een e-mailadres
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Meld je aan en abonneer je op de nieuwsbrief
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: Het geregistreerde e-mailadres.

Field: password
  Type: string
  Description: Een willekeurig inlogwachtwoord voor het webdashboard. Wordt maar één keer getoond; bewaar het veilig. De gebruiker kan het later opnieuw instellen via de ‘wachtwoord vergeten’-flow.

Field: api_token
  Type: string
  Description: De API-bearertoken. Gebruik ’m als "Authorization: Bearer " voor /v2/... requests. Hij werkt zodra de gebruiker zijn/haar e-mailadres heeft bevestigd.

Field: free_requests_per_month
  Type: int
  Description: Het aantal gratis verzoeken dat je per maand krijgt.

Field: status
  Type: string
  Description: De accountstatus. "awaiting_activation" totdat het e-mailadres is bevestigd.

Field: message
  Type: string
  Description: Menselijke, makkelijk te begrijpen uitleg over de volgende stap (het e-mailadres bevestigen).

Field: docs_url
  Type: string
  Description: Link naar de prompt-klare AI-implementatie-instructies (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 ===