📘 AIC-Web REST API Reference

Base URL: https://aicc-web.com · Everything below is usable with plain HTTP — no MCP session required. AI agents and scripts welcome.

Authentication

All student endpoints (/api/me/*) accept a Bearer token in the Authorization header. Two token kinds work:

# Get a token with username + password
curl -X POST https://aicc-web.com/api/me/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"you","password":"..."}'
# → {"api_key":"<64 hex chars>", ...}

# Use it on every call
curl https://aicc-web.com/api/me -H 'Authorization: Bearer <api_key>'

Identity & Quotas

curl https://aicc-web.com/api/me -H 'Authorization: Bearer <key>'
# → { "limits": {"maxApps":1,"maxStaticSites":5,...}, "usage": {"apps":0,"staticSites":0,"databases":0,"disk_mb":0} }

Apps (Node.js process apps)

Deploy

Common optional fields (JSON snake_case; multipart same names):

# Zip upload with migrations
curl -X POST https://aicc-web.com/api/me/apps/upload \
  -H 'Authorization: Bearer <key>' \
  -F name=myapp -F file=@app.zip \
  -F build_command='npm run build' \
  -F release_command='npx prisma migrate deploy'
# → { "app_id":"...", "url":"https://myapp-you.s1.aicc-web.com", "state":"RUNNING", "port":3154 }

Operate

Git settings + auto-deploy webhook

Deploy keys (private repos without sharing secrets)

# Private repo, no secret ever shared:
curl -X POST https://aicc-web.com/api/me/deploy-keys \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"git_url":"git@github.com:me/private-repo.git"}'
# → { "public_key":"ssh-ed25519 AAAA… aicweb-you", "instructions":"…" }
# student pastes it on GitHub (Deploy keys, read-only), then:
curl -X POST https://aicc-web.com/api/me/apps \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"name":"myapp","git_url":"git@github.com:me/private-repo.git"}'

# Redeploy from the stored repo (no source re-supplied)
curl -X POST https://aicc-web.com/api/me/apps/myapp/redeploy \
  -H 'Authorization: Bearer <key>'
# → { "app_id":"...", "url":"https://myapp-you.s1.aicc-web.com", "state":"RUNNING", "port":3154 }

Environment

One-off commands (no SSH needed)

curl -X POST https://aicc-web.com/api/me/apps/myapp/run \
  -H 'Authorization: Bearer <key>' -H 'Content-Type: application/json' \
  -d '{"command":"npx prisma migrate deploy"}'
# → { "exitCode":0, "stdout":"...", "stderr":"", "durationMs":2210 }

Files

Custom domains

Static Sites

Files and custom domains work exactly like apps, under /api/me/static-sites/:name/files... and /domains. Saves are live instantly (no process).

Databases

For an app-ATTACHED database you can also use the app-scoped explorer: POST /api/me/apps/:name/query (same read-only SQL, same {sql} body, same {columns, rows, rowCount} response).

MCP (for AI agents)

MCP tools are the lightweight control plane; file transfers (zips, static files) go through the REST endpoints above. The server exposes 21 tools:

# Typical agent flow
curl -X POST https://aicc-web.com/mcp/pair                 # → code shown to the student
# student enters the code in the portal →
curl -X POST https://aicc-web.com/mcp/exchange \
  -H 'Content-Type: application/json' \
  -d '{"agentId":"<id>","code":"123-456"}'   # → {token, refresh_token, expires_at}
# 401 with {"expired":true,...} → POST /mcp/refresh with the refresh_token

Errors & Conventions

• Errors are JSON: {"error": "message"} with meaningful status codes (400 validation, 401 auth, 404 not found, 409 quota, 410 gone/expired, 500 deploy failure — deploy failures include logs_tail).
• All timestamps are ISO 8601 UTC. Deploy results include the app's public url and assigned port.
• Rate limits and quotas come back in GET /api/me — check before acting.

AIC-Web · Home · Deploy Guide · Student Portal