ΤΕΚΜΗΡΙΩΣΗ API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Εγγραφή (v2)
PURPOSE: Δημιούργησε δωρεάν λογαριασμό και λάβε έναν κωδικό σύνδεσης και ένα API token. Δεν απαιτείται ταυτοποίηση.

--- 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: Η διεύθυνση email για την εγγραφή. Δεν απαιτείται όνομα ή επώνυμο.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Πρέπει να είναι ενεργό. Πρέπει να δώσεις τη συγκατάθεσή σου στους Όρους και Προϋποθέσεις και στην Πολιτική Απορρήτου.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Κάνε εγγραφή στο newsletter. Η προεπιλογή είναι false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Γλώσσα λογαριασμού. Μία από τις επιλογές en, de, es. Η προεπιλογή είναι en.

--- REQUEST EXAMPLES ---

Example 1: Κάνε εγγραφή με διεύθυνση email
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Κάνε εγγραφή και γράψου στο 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: Η καταχωρισμένη διεύθυνση email.

Field: password
  Type: string
  Description: Ένας τυχαίος κωδικός σύνδεσης για το web dashboard. Επιστρέφεται μόνο μία φορά· αποθήκευσέ τον με ασφάλεια. Ο χρήστης μπορεί να τον επαναφέρει αργότερα μέσω της διαδικασίας «Ξέχασα τον κωδικό».

Field: api_token
  Type: string
  Description: Το bearer token του API. Χρησιμοποίησέ το ως "Authorization: Bearer " για αιτήματα /v2/... . Αρχίζει να λειτουργεί μόλις ο χρήστης επιβεβαιώσει το email του.

Field: free_requests_per_month
  Type: int
  Description: Ο αριθμός των δωρεάν αιτημάτων που παρέχονται κάθε μήνα.

Field: status
  Type: string
  Description: Η κατάσταση του λογαριασμού. «awaiting_activation» μέχρι να επιβεβαιωθεί η διεύθυνση email.

Field: message
  Type: string
  Description: Οδηγίες σε απλή, κατανοητή γλώσσα για το επόμενο βήμα (επιβεβαίωση της διεύθυνσης email).

Field: docs_url
  Type: string
  Description: Σύνδεσμος προς τις οδηγίες υλοποίησης AI έτοιμες για prompt (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 ===