API Documentation

API Key Header

x-api-key: your_api_key_here

Who should use the Basic API?

• Individual developers building personal projects or simple apps
• Small businesses who want direct API access without enterprise features
• Prototype builders testing hairstyle generation functionality
• Content creators generating hairstyles for social media or marketing

Retrieve a list of all available hairstyles and their details.

Response

{
  "data": [
    {
      "description": "Bob - disheveled",
      "sex": "feminine",
      "id": 817941,
      "tags": "disheveled, bob"
    }
    // ... more styles
  ],
  "message": "",
  "error": false
}

Retrieve a list of all available hair colors and their details.

Response

{
  "data": [
    {
      "id": "color_123",
      "name": "Brown",
      "description": "Natural brown hair color",
      "preview_images": {
        "thumbnail": "https://...",
        "full": "https://..."
      }
    }
    // ... more colors
  ],
  "message": "",
  "error": false
}

Generate a new hairstyle based on the provided image and parameters.

Headers

Content-Type: application/json
x-api-key: your_api_key_here

Request Body

{
  "mode": "live", // or "test"
  "gender": "person", // or "male", "female", "man", "woman"
  "styles": ["817941"], // Array of hairstyle ids
  "hair_colour": "brown",
  "image_name": "IMG-123123.jpg", // Must reference an image in your AIhairstyles account, or use image_url
  "image_url": "https://example.com/image.jpg", // Required if not using image_name
  "force_new_hairline": false, // Optional
  "callback_url": "https://your-domain.com/webhook" // Optional
}

Response

{
  "data": {
    "id": "job_123",
    "mode": "live",
    "image": {
      "name": "example.jpg",
      "url": "https://..."
    }
  },
  "message": "Job created successfully",
  "status": "success"
}

{
  "data": null,
  "message": "Error message explaining what went wrong",
  "status": "error"
}

Common Errors

• 400 Bad Request: Invalid request body format or validation errors in the parameters
• 401 Unauthorized: Missing or invalid API key
• 402 Payment Required: Insufficient credits for the operation
• 404 Not Found: Image not found or inaccessible

Retrieve the status and results of a specific generation job.

Headers

x-api-key: your_api_key_here

Parameters

• id: The ID of the generation job (received from the generation endpoint)

Response

{
  "data": {
    "images": [
      "https://ik.imagekit.io/...",
      // ... more image URLs
    ],
    "status": "completed"
  },
  "message": "Success",
  "status": "success"
}

{
  "data": null,
  "message": "Error message explaining what went wrong",
  "status": "error"
}

Common Errors

• 401 Unauthorized: No API key provided
• 403 Forbidden: Invalid API key
• 404 Not Found: Generation job not found
• 500 Server Error: Unexpected server error

Who should use the Enterprise API?

• Salon owners who want to integrate client data into their existing booking/management systems
• Barber shops looking to build custom client consultation workflows
• Hair clinics needing to manage patient consultations and treatment tracking
• Developers building custom applications for hair businesses

Retrieve a list of all clients associated with your enterprise, including their consultation history and generated images.

Headers

x-api-key: your_enterprise_api_key

Parameters

• enterprise_name: Your enterprise's URL slug (found in your dashboard URL)
• page (optional): Page number for pagination (default: 1)
• limit (optional): Number of clients to return (default: 10)
• search (optional): Search by email address

Response

{
  "clients": [
    {
      "id": "client_123",
      "email": "client@example.com",
      "name": "Jane Smith",
      "phone_number": "+1234567890",
      "user_id": "user_456",
      "metadata": {
        "source": "ai_studio",
        "created_by": "user_789"
      },
      "enterprise_clients_media": [
        {
          "id": "media_101",
          "file_url": "https://...",
          "file_name": "img-abc123",
          "created_at": "2024-01-20T14:15:00Z",
          "metadata": {
            "source": "upload"
          }
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15
  }
}

Add a new client to your enterprise. You must provide either an email address or phone number (or both) to create a client.

Headers

Content-Type: application/json
x-api-key: your_enterprise_api_key

Request Body

{
  "email": "client@example.com", // optional but either email or phone_number is required
  "name": "Jane Smith", // optional
  "phone_number": "+1234567890", // optional but either email or phone_number is required
  "source": "client_page" // optional, can be used to track where the client was added from
}

Response

{
  "success": true,
  "client": {
    "id": "client_123",
    "email": "client@example.com",
    "name": "Jane Smith",
    "phone_number": "+1234567890",
    "enterprise_id": "ent_456",
    "user_id": null,
    "metadata": {
      "source": "ai_studio",
      "created_by": "user_789"
    },
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Client created successfully"
}

Common Errors

• 400 Bad Request: Invalid email format, missing contact information (neither email nor phone provided), or other validation errors
• 401 Unauthorized: Invalid or missing API key
• 409 Conflict: Client with this email or phone number already exists for this enterprise

Get detailed information about a specific client, including their complete media history.

Headers

x-api-key: your_enterprise_api_key

Parameters

• enterprise_name: Your enterprise's URL slug
• client_id: The unique identifier of the client

Response

{
  "id": "client_123",
  "email": "client@example.com",
  "name": "Jane Smith",
  "phone_number": "+1234567890",
  "user_id": "user_456",
  "metadata": {
    "source": "ai_studio",
    "created_by": "user_789"
  },
  "enterprise_clients_media": [
    {
      "id": "media_101",
      "file_url": "https://...",
      "file_name": "img-abc123",
      "created_at": "2024-01-20T14:15:00Z",
      "metadata": {
        "source": "upload"
      }
    }
  ],
  "media_count": 25,
  "media_loaded": 5
}

Retrieve all hairstyle generations for a specific client, including images and metadata.

Headers

x-api-key: your_enterprise_api_key

Parameters

• enterprise_name: Your enterprise's URL slug
• client_id: The unique identifier of the client
• page (optional): Page number for pagination (default: 1)
• limit (optional): Number of generations to return (default: 10)

Response

{
  "generations": [
    {
      "id": "gen_456",
      "created_at": "2024-01-20T14:15:00Z",
      "status": "completed",
      "data": {
        "styles": ["Long Bob", "Pixie Cut"],
        "gender": "feminine",
        "hairColours": ["brown"],
        "options": {
          "force_new_hairline": false
        }
      },
      "images": [
        "https://ik.imagekit.io/aihairstyles/...",
        "https://ik.imagekit.io/aihairstyles/..."
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 8,
    "totalPages": 1
  }
}

Generate Login Link

Generate a secure login link for a staff member or client.

Headers

Content-Type: application/json
x-api-key: your_enterprise_api_key

Request Body

{
  "email": "staff@yourcompany.com", // Required: Email address of the staff member or client
  "next": "/dashboard/clients" // Optional: Where to redirect after login (relative path)
}

Parameters

• email (Required): Valid email address of the staff member or client who will receive the login link
• next (Optional): Relative path starting with "/" to redirect to after successful login

Response

{
    "login_url": "https://aihairstyles.com/login-link?token=bdaa3409550294c2f29b1ed1569d21ad32ab7bbd7050f080cf87e431&type=magiclink&next=%2Forg%2Ftest-salon%2Fai-studio",
    "message": "Login link generated successfully"
}
                    

Use Cases

• Providing quick access to staff members to secure areas of the platform

Common Errors

• 400 Bad Request: Invalid email format or relative path format for 'next' parameter
• 401 Unauthorized: Invalid or missing API key
• 500 Server Error: Failed to generate login link

View all API keys for your enterprise (values are masked for security).

Headers

x-api-key: your_enterprise_api_key

Response

{
  "data": [
    {
      "id": "key_789",
      "name": "Mobile App Integration",
      "created_at": "2024-01-15T10:30:00Z",
      "last_used": "2024-01-20T09:15:00Z",
      "status": "active",
      "api_key": "ak_**********************cdef"
    }
  ],
  "message": "API keys retrieved successfully"
}

Generate a new API key for your enterprise. Useful for creating separate keys for different applications or team members.

Headers

Content-Type: application/json
x-api-key: your_existing_api_key

Request Body

{
  "name": "Mobile App Integration",
  "expires_at": "2025-01-15T00:00:00Z" // optional
}

Response

{
  "success": true,
  "data": {
    "id": "key_789",
    "name": "Mobile App Integration", 
    "api_key": "ak_1234567890abcdef...",
    "created_at": "2024-01-15T10:30:00Z",
    "expires_at": "2025-01-15T00:00:00Z",
    "status": "active"
  },
  "message": "API key created successfully"
}

Permanently disable an API key. This action cannot be undone.

Headers

x-api-key: your_enterprise_api_key

Parameters

• enterprise_name: Your enterprise's URL slug
• key_id: The unique identifier of the API key to delete

Response

{
  "success": true,
  "message": "API key deleted successfully"
}

Common Errors

• 404 Not Found: API key not found or doesn't belong to this enterprise
• 400 Bad Request: Cannot delete the last remaining API key

Who should use the Partner API?

• SaaS providers offering salon management software with AI consultation features
• White-label solution providers building custom hairstyling applications for clients
• Franchise systems deploying consistent AI consultation tools across multiple locations
• E-commerce platforms integrating virtual try-on experiences for hair product retailers

Create a new enterprise account programmatically using an admin API key. This endpoint is designed for trusted partners who need to create businesses within the AIHairstyles ecosystem.

Headers

Content-Type: application/json
x-partner-api-key: your_partner_api_key_here

Request Body

{
  "businessName": "Hair Salon & Spa",
  "businessType": "salon",
  "ownerEmail": "owner@hairsalon.com"
}

Parameters

• businessName: Required The name of the business (minimum 4 characters)
• businessType: Required The type of business. Must be one of: "salon", "barber", "hair-clinic"
• ownerEmail: Required - Email address of the business owner who will have admin access to the enterprise

Response

{
  "data": {
    "enterprise_id": "550e8400-e29b-41d4-a716-446655440000",
    "enterprise_name": "hair-salon-spa-1234",
    "enterprise_brand_name": "Hair Salon & Spa",
    "widget_id": 12345,
    "api_key": "ak_abcdef123456789...",
    "owner_email": "owner@hairsalon.com",
    "links": {
      "enterprise_overview": "https://aihairstyles.com/org/hair-salon-spa-1234",
      "widget_management": "https://aihairstyles.com/org/hair-salon-spa-1234/widgets/12345",
      "widget_embed": "https://aihairstyles.com/studio-widget?widget_id=12345"
    }
  },
  "message": "Enterprise created successfully",
  "status": "success"
}

{
  "data": null,
  "message": "Error message explaining what went wrong",
  "status": "error"
}

Response Fields

• enterprise_id: Unique UUID for the created enterprise
• enterprise_name: URL-safe slug name for the enterprise (used in URLs)
• enterprise_brand_name: Original business name as provided in the request
• widget_id: ID of the default widget created for the enterprise
• api_key: Default API key for the enterprise (store securely)
• owner_email: Email address of the enterprise owner
• links.enterprise_overview: Direct URL to the enterprise dashboard
• links.widget_management: Direct URL to configure the widget settings
• links.widget_embed: Direct URL for embedding the AI consultation widget

What Gets Created

When you create an enterprise via this endpoint, the following items are automatically created in a single atomic transaction:

• Enterprise Account: A new business account with active subscription status
• Owner User Account: If the email doesn't exist, a new user account is created; otherwise, the existing user is assigned as owner
• User Permissions: The owner is granted full access with business_owner role and admin privileges
• Default Widget: An enabled widget for AI hair consultations
• Default API Key: A standard API key for the enterprise to use

Common Errors

• 400 Bad Request: Invalid request body, validation errors, or missing required fields like ownerEmail
• 401 Unauthorized: Missing or invalid admin API key
• 409 Conflict: Unable to generate unique enterprise name
• 500 Server Error: Unexpected server error during creation

Integration Notes

• Store the returned enterprise_id and api_key in your database
• The owner_email links to the user who will manage the enterprise
• The widget_id can be used to embed the AI consultation widget
• The enterprise_name is used for URL routing and API endpoints
• The owner can immediately log in and access their enterprise dashboard
• All created resources are immediately active and ready for use