API Documentation
Create sites programmatically — for automation, agencies, and client workflows — with a long-lived API token and a single REST endpoint.
Programmatic site creation
One endpoint, JSON in and out, designed for approved customers
Simple REST
Plain HTTPS requests with JSON bodies. Nothing else to install.
Token auth
Long-lived mcapi_ tokens you create and revoke in Settings.
Manual billing
Skips Stripe checkout — deployments are invoiced at the end of the period.
Getting API access
The deploy endpoint is restricted to approved customers
- 1Email support@maldonadocloud.com to request API access for your account.
- 2Once approved, open Settings → API and accept the API Service Agreement.
- 3Create an API token on the same page. The full token is shown only once — copy it somewhere safe. Tokens are long-lived, expire after a configurable period (30 days by default), and can be revoked at any time.
Authentication
Send your API token as a Bearer token in the Authorization header:
Authentication header
Authorization: Bearer mcapi_your_token_hereKeep tokens secret. Never commit them to version control, embed them in client-side code, or share them publicly. If a token leaks, revoke it in Settings and create a new one.
POST/api/sites/deploy
Create a new site without going through Stripe checkout
Example request
curl -X POST 'https://portal.mcwebsites.app/api/sites/deploy' \
-H 'Authorization: Bearer mcapi_your_token_here' \
-H 'Content-Type: application/json' \
-d '{
"siteName": "my-first-site",
"planId": "professional",
"skipPayment": true
}'Request body
siteNameUnique site identifier: 3–30 characters, lowercase letters, numbers, and hyphens; must start and end with a letter or number.
planIdBillable plan for the site: starter, professional, or enterprise. See the plan reference.
cloudProviderOptional. Only onprem is supported, and it is the default — you can omit this field entirely.
skipPaymentMust be true. This endpoint skips Stripe checkout; API deployments are invoiced manually instead.
Success response (201 Created)
{
"success": true,
"message": "Site deployment initiated successfully",
"site": {
"siteId": "cust-1234-my-first-site",
"siteName": "my-first-site",
"customerId": "cust-1234",
"domain": "my-first-site.mcwebsites.app",
"plan": "professional",
"cloudProvider": "onprem",
"status": "provisioning"
},
"builderUrl": "https://...",
"billing": {
"status": "pending",
"message": "This deployment will be billed manually. You will receive an invoice at the end of the billing period.",
"plan": "Professional",
"monthlyPrice": 49
},
"note": "Site is being provisioned. This may take 2-5 minutes. Use GET /api/sites/{siteId} to check status."
}Provisioning takes about 2–5 minutes. Poll the site through the dashboard or the browser-session endpoint GET /api/sites/{siteId} until its status becomes active. The builderUrl opens the AI builder for the new site.
Error responses
Bad Request
Invalid parameters: unknown planId, skipPayment missing or not true, or siteName failing validation.
{ "error": "This endpoint requires skipPayment=true. For normal site creation with payment, use /api/create-checkout-session" }Unauthorized
Missing Authorization header, token not in mcapi_... format, or an invalid/expired token.
{ "error": "Invalid token format. API tokens must start with \"mcapi_\"" }Forbidden
API access has not been granted, or the API Service Agreement has not been accepted. The response includes a contact or help_url field.
{ "error": "API access not enabled. Please contact support to request API access.", "contact": "support@maldonadocloud.com" }Conflict
A site with that name already exists.
{ "error": "Site name already exists. Please choose a different name." }Internal Server Error
Something went wrong while provisioning. Retry, then contact support if it persists.
{ "error": "Internal server error", "details": "..." }Billing note: every API deployment is recorded and billed manually — you'll receive an invoice at the end of the billing period for sites created this way. For self-serve subscriptions with automatic card billing, create sites from the dashboard instead.
More examples
Python
import requests
response = requests.post(
'https://portal.mcwebsites.app/api/sites/deploy',
headers={
'Authorization': 'Bearer mcapi_your_token_here',
'Content-Type': 'application/json',
},
json={
'siteName': 'my-first-site',
'planId': 'professional',
'skipPayment': True,
},
)
data = response.json()
if response.status_code == 201:
print('Site ID:', data['site']['siteId'])
print('Domain:', data['site']['domain'])
print('Builder:', data['builderUrl'])
else:
print('Error:', data.get('error'))Node.js / TypeScript
const response = await fetch('https://portal.mcwebsites.app/api/sites/deploy', {
method: 'POST',
headers: {
'Authorization': 'Bearer mcapi_your_token_here',
'Content-Type': 'application/json',
},
body: JSON.stringify({
siteName: 'my-first-site',
planId: 'professional',
skipPayment: true,
}),
});
const data = await response.json();
if (response.status === 201) {
console.log('Site ID:', data.site.siteId);
console.log('Domain:', data.site.domain);
console.log('Builder:', data.builderUrl);
} else {
console.error('Error:', data.error);
}