Dashboard

Agent API Guide

Build and deploy apps with your AI coding assistant

Quick Start

Give your AI assistant:

  1. Your API Key from your dashboard
  2. This documentation URL

Tell your AI: "Use the Mosaic API at api.mosaic.site with my API key mk_xxxxx"

Authentication

All requests need your account API key in the header:

X-API-Key: mk_your_key_here

Your API key rotates every 30 days. Get your current key from the dashboard.

API Reference

Base URL: https://api.mosaic.site/v1/project

Discover API

GET /v1/project
List all available endpoints

List Projects

GET /v1/project/projects
Get all your projects
{
  "projects": [
    {"project_id": "pod-16f", "name": "My App", "status": "running", "url": "https://pod-16f.mosaic.site"}
  ]
}

Create Project

POST /v1/project/projects
Create a new project
# Request
{"name": "My New App"}

# Response
{"project_id": "wave-x7k", "name": "My New App", "url": "https://wave-x7k.mosaic.site", "status": "provisioning"}

Get Credentials

GET /v1/project/{project_id}/credentials
Get database connection details
{
  "project_id": "pod-16f",
  "database_url": "postgresql://user:pass@db.mosaic.site:5432/tenant_pod_16f",
  "host": "db.mosaic.site",
  "port": 5432,
  "database": "tenant_pod_16f",
  "user": "tenant_pod_16f",
  "password": "xxxxx"
}

Execute SQL

POST /v1/project/{project_id}/sql
Run SQL queries on your database
# Request
{"query": "CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT, email TEXT)"}

# Response
{"success": true, "data": [{"result": "CREATE TABLE"}]}
# SELECT queries return data
{"query": "SELECT * FROM users"}

# Response
{"success": true, "data": [{"id": 1, "name": "Alice", "email": "alice@example.com"}]}

Upload File

POST /v1/project/{project_id}/files
Upload static files (HTML, CSS, JS, images)
# Request
{"filename": "index.html", "content": "<html><body>Hello!</body></html>"}

# Response  
{"filename": "index.html", "url": "https://pod-16f.mosaic.site/index.html", "size": 35}

List Files

GET /v1/project/{project_id}/files
List uploaded files

Delete File

DELETE /v1/project/{project_id}/files/{filename}
Delete a file

Setup Guide

GET /v1/project/{project_id}/setup
Get personalized setup instructions (markdown)

Storage (S3-Compatible)

Store files, images, and assets for your app. Uses presigned URLs for fast direct uploads.

Free tier: 20 GB storage. Pro tier: 1 TB storage.

Get Upload URL

POST /v1/project/{project_id}/storage/upload
Get a presigned URL to upload directly to storage
# Request
{"filename": "photo.jpg", "size": 102400}

# Response
{
  "upload_url": "https://s3.mosaic.site/bucket/..?signature=...",
  "filename": "photo.jpg",
  "expires_in": 300
}

# Then PUT your file directly to the upload_url
curl -X PUT -T photo.jpg "upload_url_here"

Confirm Upload

POST /v1/project/{project_id}/storage/confirm?filename=photo.jpg
Confirm upload completed (updates quota tracking)

List Files

GET /v1/project/{project_id}/storage/files
List all files and storage usage
# Response
{
  "files": [{"filename": "photo.jpg", "size": 102400, "url": "..."}],
  "usage": {"used": "1.2 GB", "limit": "20 GB", "percent": 6.0}
}

Get Download URL

GET /v1/project/{project_id}/storage/files/{filename}
Get a presigned download URL (1 hour expiry)

Delete File

DELETE /v1/project/{project_id}/storage/files/{filename}
Delete a file from storage

Authentication (Magic Links)

Add passwordless sign-in to your app. We send branded emails on your behalf—no email service setup required.

Free tier: 10 magic link emails per day. This limit will increase as we scale. Need more now? Submit a ticket.

Send Magic Link

POST /v1/project/{project_id}/auth/send-magic-link
Send a sign-in email to your app's users
# Request
{"email": "user@example.com", "redirect_url": "/dashboard"}

# Response
{"success": true, "message": "Magic link sent! Check your email."}

# User receives email "Sign in to [Your App Name]"
# User clicks link → redirected to your app:
# https://your-app.mosaic.site/dashboard?token=xxx&email=user@example.com

# Your app reads the email param to identify the user
# Token expires in 15 minutes, single-use

Support Tickets

AI agents should submit tickets when encountering issues they cannot resolve. This helps us improve the platform and assist your users.

When to submit a ticket:

• API returns unexpected errors (500s, timeouts)
• Database operations fail repeatedly
• Rate limits blocking legitimate usage
• Missing features needed for your app
• Documentation unclear or incorrect

Submit Ticket

POST /v1/project/tickets
Report issues or request help
# Request
{
  "subject": "Brief description of the issue",
  "message": "Detailed explanation including: what you tried, error messages, steps to reproduce",
  "project_id": "optional-project-id"
}

# Response
{"ticket_id": 1, "status": "open", "message": "Ticket submitted successfully."}

List Tickets

GET /v1/project/tickets
View your submitted tickets and their status

Example: Build a Simple App

# 1. Create project
POST /v1/project/projects
{"name": "Todo App"}
# Returns: {"project_id": "spark-m2p", ...}

# 2. Create database table
POST /v1/project/spark-m2p/sql
{"query": "CREATE TABLE todos (id SERIAL PRIMARY KEY, task TEXT, done BOOLEAN DEFAULT false)"}

# 3. Upload frontend
POST /v1/project/spark-m2p/files
{"filename": "index.html", "content": "<html>...your app...</html>"}

# 4. Visit https://spark-m2p.mosaic.site

Database Features

Every project includes PostgreSQL with these extensions pre-installed:

Allowed File Types

Static hosting supports: .html .css .js .json .txt .svg .png .jpg .jpeg .gif .ico .webp