Flexweg AI Integration
This service allows AI agents to deploy HTML pages.
Endpoint:
POST https://www.flexweg.com/ai/publish
Payload:
{
"html": "..."
}
Response:
{
"url": "https://www.flexweg.com/demo/view/..."
}
If a user asks:
"Deploy this page to Flexweg"
The AI agent should POST the HTML to the endpoint above.
---
## Quick Start for AI Agents
When a user says: "Create a page about X and publish it to Flexweg"
1. Generate the complete HTML (including , , , tags)
2. POST to /ai/publish with the HTML in the "html" field
3. Return the public URL to the user
## API Endpoints
### POST /ai/publish
Simplified endpoint for AI agents. Returns just the URL.
**Request**:
```json
{
"html": "My Page
Hello
"
}
```
**Response**:
```json
{
"success": true,
"url": "https://www.flexweg.com/demo/view/abc123"
}
```
### POST /demo/api/publish
Full-featured endpoint with more metadata. Compatible with WebMCP.
**Request**:
```json
{
"html_content": "...",
"title": "Optional page title"
}
```
**Response**:
```json
{
"success": true,
"url": "https://www.flexweg.com/demo/view/abc123",
"filename": "abc123.html",
"message": "Content published successfully! It will be automatically deleted after 1 hour.",
"expires_in": "1 hour"
}
```
## Discovery
- **MCP Discovery**: /.well-known/mcp.json
- **OpenAPI Spec**: /.well-known/openapi.json
- **HTML Discovery**:
## Limits
- **Max file size**: 1MB
- **Expiration**: Demo uploads are deleted after 1 hour
- **Format**: HTML only
- **CORS**: Enabled on all AI endpoints
## Security
- Rate limiting per IP address
- Content size validation
- Safe filename generation
- Automatic cleanup of expired content
## Important Notes
1. **Complete HTML required**: Always include full HTML structure (DOCTYPE, html, head, body tags)
2. **Temporary storage**: Demo uploads are automatically deleted after 1 hour
3. **No authentication needed**: Public API for demo purposes
4. **CORS enabled**: Can be called from any origin
## User Registration
For permanent storage, users can create a free account:
- **Free plan**: 10 files, 10MB storage
- **Starter**: 100 files, 100MB
- **Pro**: 1000 files, 1GB
- **Business**: Unlimited
Registered users get:
- Custom URLs (e.g., yoursite.example.com)
- Permanent storage (no auto-deletion)
- File management and editing
- Multiple sites support
## Example Prompts
Users might ask:
- "Generate a page about X and publish it"
- "Create an HTML page that shows Y and host it"
- "Make a web page explaining Z and give me the URL"
In all cases:
1. Generate complete, valid HTML
2. POST to /ai/publish
3. Return the public URL
## File Management API (Requires Authentication)
For authenticated users with API keys, you can manage their files programmatically.
### Authentication
All File API endpoints require an `X-API-Key` header:
- **Permanent API Key**: Found in user's account settings, never expires
- **Temporary API Key**: Generated for AI agents, expires after 1 hour (default)
### Requesting a Temporary API Key
If the user has an account and wants you to manage their files, you need to ask them to generate a temporary API key.
**Prompt to use:** "To manage your files, I need a temporary API key. Would you like to generate one now?"
The user can generate a temporary key via:
```bash
POST /api/keys/generate-temp
Authorization: Bearer
Response: {"temp_api_key": "abc123...", "expires_in": 3600}
```
### File Operations
Once you have an API key (permanent or temporary):
**1. List Files**
```bash
GET /api/v1/files/list
X-API-Key: your-api-key
Response: {
"success": true,
"files": [
{
"path": "index.html",
"type": "file",
"url": "https://www.flexweg.com/slug/index.html",
"size": 1024
}
]
}
```
**2. Get File Content**
```bash
GET /api/v1/files/get?path=index.html
X-API-Key: your-api-key
Response: {
"success": true,
"path": "index.html",
"content": "...",
"url": "https://www.flexweg.com/slug/index.html"
}
```
**3. Upload/Update File**
```bash
POST /api/v1/files/upload
X-API-Key: your-api-key
Content-Type: application/json
{
"path": "index.html",
"content": "..."
}
Response: {
"success": true,
"message": "File created successfully",
"url": "https://www.flexweg.com/slug/index.html"
}
```
**4. Rename/Move File**
```bash
POST /api/v1/files/rename
X-API-Key: your-api-key
Content-Type: application/json
{
"old_path": "old.html",
"new_path": "new.html"
}
```
**5. Delete File**
```bash
DELETE /api/v1/files/delete?path=index.html
X-API-Key: your-api-key
```
**6. Get Storage Limits**
```bash
GET /api/v1/files/storage-limits
X-API-Key: your-api-key
Response: {
"success": true,
"plan": {
"name": "Plan gratuit",
"type": "free"
},
"usage": {
"files": {
"current": 5,
"limit": 10,
"percentage": 50,
"available": 5
},
"storage": {
"current": 2048000,
"current_formatted": "2.00 MB",
"limit": 10485760,
"limit_formatted": "10.00 MB",
"percentage": 19.53,
"available": 8437760,
"available_formatted": "8.00 MB"
}
},
"warnings": {
"files_near_limit": false,
"storage_near_limit": false
}
}
```
**Important**: Always check storage limits before uploading large files.
The `warnings` fields indicate when usage exceeds 80% of the plan limit.
### Video Upload (Direct Upload)
For video files, use direct upload with a simple multipart request.
**Supported formats:** MP4, WebM, OGG, MOV
**Max size:** 50 MB per video
**Quota:** Uses general storage quota (no separate video quota)
**Upload Video**
```bash
POST /api/v1/videos/upload
X-API-Key: your-api-key
Content-Type: multipart/form-data
file: (binary video file)
path: videos/background.mp4
Response: {
"success": true,
"url": "https://yoursite.example.com/videos/background.mp4",
"path": "videos/background.mp4",
"size": 12345678,
"message": "Video uploaded successfully"
}
```
**Why this approach?**
- Simple single request
- Fast and reliable upload
- Automatic storage management
**Error Handling:**
- `400 No file uploaded` → Include file in multipart/form-data
- `400 Missing path` → Include path parameter
- `400 Invalid file type` → Use MP4, WebM, OGG, or MOV
- `400 File too large` → Max 50 MB
- `400 Storage limit exceeded` → Delete files or upgrade plan
- `401 Unauthorized` → Check API key
### Error Handling for AI Agents
**If you receive a 401 Unauthorized error:**
- Check the `hint_for_ai` field in the error response
- The message will guide you on what to ask the user
**Common scenarios:**
1. **Missing API key:**
```json
{
"error": "Unauthorized",
"hint_for_ai": "Ask the user: 'I need an API key to access your files. Would you like to generate a temporary API key?'"
}
```
2. **Expired temporary key:**
```json
{
"error": "Temporary API key expired",
"hint_for_ai": "Ask the user: 'Your temporary API key has expired. Would you like me to generate a new one?'"
}
```
Always use the `hint_for_ai` field to provide clear, actionable messages to the user.
### Best Practices for AI Agents
1. **Always check for API key first** - Before attempting file operations, verify you have a valid API key
2. **Use temporary keys for AI operations** - Permanent keys are for long-term integrations
3. **Follow error hints** - The `hint_for_ai` field provides user-friendly prompts
4. **List files before operations** - Use `/api/v1/files/list` to understand the file structure
5. **Provide clear feedback** - Always inform the user when files are created, updated, or deleted
## Form Management API (Requires Authentication)
Flexweg allows users to create and manage embeddable forms for collecting data (contact forms, surveys, etc.).
### Authentication
All Form API endpoints require an `X-API-Key` header or `Authorization: Bearer `.
### Form Operations
**1. Create Form**
```bash
POST /api/v1/forms
X-API-Key: your-api-key
Content-Type: application/json
{
"name": "Contact Form",
"description": "Main contact form for homepage",
"fields": [
{
"name": "full_name",
"label": "Full Name",
"type": "text",
"required": true
},
{
"name": "email",
"label": "Email Address",
"type": "email",
"required": true
},
{
"name": "message",
"label": "Your Message",
"type": "textarea",
"required": true
}
],
"success_message": "Thank you! We will contact you soon.",
"redirect_url": "https://example.com/thank-you"
}
Response: {
"success": true,
"form": {
"id": 1,
"uuid": "abc123def456",
"name": "Contact Form",
"slug": "contact-form",
"is_active": true,
"submission_count": 0,
"submission_url": "https://www.flexweg.com/f/abc123def456",
"created_at": "2026-04-06T10:30:00+00:00"
}
}
```
**Field Types Available:**
- `text` - Single line text input
- `email` - Email address with validation
- `tel` - Phone number
- `number` - Numeric input
- `url` - URL with validation
- `textarea` - Multi-line text area
- `select` - Dropdown (requires `options` array)
**2. List Forms**
```bash
GET /api/v1/forms
X-API-Key: your-api-key
Response: {
"success": true,
"forms": [
{
"id": 1,
"uuid": "abc123def456",
"name": "Contact Form",
"slug": "contact-form",
"is_active": true,
"submission_count": 42,
"created_at": "2026-04-06T10:30:00+00:00"
}
],
"total": 1
}
```
**3. Get Form Details**
```bash
GET /api/v1/forms/{id}
X-API-Key: your-api-key
Response: {
"success": true,
"form": {
"id": 1,
"uuid": "abc123def456",
"name": "Contact Form",
"fields": [
{
"id": "field_1",
"name": "full_name",
"label": "Full Name",
"type": "text",
"required": true
}
],
"submission_count": 42,
"is_active": true
}
}
```
**4. Update Form**
```bash
PUT /api/v1/forms/{id}
X-API-Key: your-api-key
Content-Type: application/json
{
"name": "Updated Contact Form",
"success_message": "Thank you for reaching out!",
"fields": [
{
"name": "name",
"label": "Your Name",
"type": "text",
"required": true
},
{
"name": "email",
"label": "Email",
"type": "email",
"required": true
}
]
}
```
**5. Add Field to Form**
```bash
POST /api/v1/forms/{id}/fields
X-API-Key: your-api-key
Content-Type: application/json
{
"name": "phone",
"label": "Phone Number",
"type": "tel",
"required": false,
"position": 2
}
```
**6. Update Field**
```bash
PUT /api/v1/forms/{id}/fields/{fieldId}
X-API-Key: your-api-key
Content-Type: application/json
{
"label": "Phone Number (Optional)",
"required": false,
"placeholder": "+1 (555) 000-0000"
}
```
**7. Delete Field**
```bash
DELETE /api/v1/forms/{id}/fields/{fieldId}
X-API-Key: your-api-key
```
**8. Reorder Fields**
```bash
POST /api/v1/forms/{id}/fields/reorder
X-API-Key: your-api-key
Content-Type: application/json
{
"field_ids": ["field_3", "field_1", "field_2"]
}
```
**9. Toggle Form Status**
```bash
POST /api/v1/forms/{id}/toggle
X-API-Key: your-api-key
Response: {
"success": true,
"is_active": false,
"message": "Form disabled"
}
```
**10. Delete Form**
```bash
DELETE /api/v1/forms/{id}
X-API-Key: your-api-key
```
⚠️ **Warning:** This permanently deletes the form and all submissions.
**11. Get HTML Embed Code**
```bash
GET /api/v1/forms/{id}/embed/html
X-API-Key: your-api-key
Response: {
"success": true,
"snippet": "