Skip to main content
Both AI endpoints are asynchronous. Requests return 202 Accepted immediately and dispatch a background job. A push notification or in-app notification is sent when the result is ready.

​
POST /api/v1/ai/generate

Generate a business profile using AI based on basic business details. Dispatches a GenerateBusinessProfile background job. Middleware: auth:sanctum, throttle:api
Authentication: Required

​
Budget enforcement

In addition to the route-level throttle, this endpoint enforces a token bucket rate limit: 5 requests per hour per user (key: ai-gen:{user_id}). When the budget is exhausted the endpoint returns 429 with a countdown until the next available slot. The user must also have an associated tenant_id. Requests without a tenant return 403.

​
Request body

​
business_name
string
required
Business name. Between 3 and 100 characters.
​
activity
string
required
Primary business activity or industry. Maximum 50 characters.
​
location
string
required
Geographic location of the business. Maximum 50 characters.
​
extra_details
string
Optional additional context for the AI. Maximum 200 characters.

​
Response 202 Accepted

​
status
string
processing
​
message
string
Confirmation message that the AI is working on the profile.
​
remaining_attempts
integer
Number of remaining AI generation attempts in the current hour.

​
Response 403 Forbidden

Returned when the authenticated user has no associated tenant.
​
message
string
No business associated.

​
Response 429 Too Many Requests

Returned when the per-user token bucket is exhausted.
​
message
string
Countdown message with minutes and seconds until the next slot.
curl -X POST https://yourdomain.com/api/v1/ai/generate \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "business_name": "Pupusas Don Carlos",
    "activity": "Restaurante",
    "location": "Tegucigalpa, Honduras",
    "extra_details": "Especialidad en comida típica hondureña"
  }'

​
Error responses

StatusCause
401Missing or invalid token
403User has no associated tenant
422Validation failure (missing required fields, length violations)
429Per-user AI budget exhausted

​
POST /api/v1/ai/optimize-profile

Queue an AI-powered optimization of an existing business profile. Accepts structured inputs including tone, target audience, and keywords. Dispatches a GenerateBusinessProfileJob. Middleware: auth:sanctum, throttle:api
Authentication: Required

​
Request body

​
business_name
string
required
Business name. Maximum 255 characters.
​
description
string
required
Current business description. Between 10 and 1000 characters.
​
target_audience
string
required
Description of the intended audience. Maximum 255 characters.
​
keywords
string[]
required
Array of keywords (maximum 10 keywords, each up to 50 characters).
​
tone
string
required
Writing tone for the optimized profile. One of: formal, casual, persuasive, witty, professional.

​
Response 202 Accepted

​
status
string
processing
​
message
string
Profile optimization has been queued.
curl -X POST https://yourdomain.com/api/v1/ai/optimize-profile \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "business_name": "Pupusas Don Carlos",
    "description": "Restaurante familiar en Tegucigalpa con 10 años de experiencia.",
    "target_audience": "Familias y jóvenes profesionales",
    "keywords": ["pupusas", "comida típica", "Honduras"],
    "tone": "casual"
  }'

​
Error responses

StatusCause
401Missing or invalid token
422Validation failure (tone not in allowed list, keywords > 10, description too short)

Build docs developers (and LLMs) love

Get started for freeTalk to us