ΤΕΚΜΗΡΙΩΣΗ API

=== AI IMPLEMENTATION INSTRUCTIONS ===

ENDPOINT: Sign Up (v2)
PURPOSE: Create a free account and receive a login password and an API token. No authentication required.

--- 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: The email address to register. No first or last name is required.

Parameter: accept_terms
  Type: bool
  Required: REQUIRED
  Description: Must be true. The user must consent to the Terms and Conditions and Privacy Policy.

Parameter: newsletter
  Type: bool
  Required: OPTIONAL
  Description: Subscribe to the newsletter. Defaults to false.

Parameter: locale
  Type: string
  Required: OPTIONAL
  Description: Account language. One of en, de, es. Defaults to en.

--- REQUEST EXAMPLES ---

Example 1: Sign up with an email address
Request Body (JSON):
{
    "email": "user@example.com",
    "accept_terms": true
}

Example 2: Sign up and subscribe to the 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: The registered email address.

Field: password
  Type: string
  Description: A random login password for the web dashboard. Returned only once; store it securely. The user can reset it later via the forgot-password flow.

Field: api_token
  Type: string
  Description: The API bearer token. Use it as "Authorization: Bearer " for /v2/... requests. It starts working once the user confirms their email.

Field: free_requests_per_month
  Type: int
  Description: The number of free requests granted per month.

Field: status
  Type: string
  Description: The account status. "awaiting_activation" until the email address is confirmed.

Field: message
  Type: string
  Description: Human-readable guidance on the next step (confirming the email address).

Field: docs_url
  Type: string
  Description: Link to the prompt-ready AI implementation instructions (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 ===