{"openapi":"3.1.0","info":{"title":"SiteSpark API","version":"1.0.0","description":"Build, read, update, and publish real SiteSpark sites — the same AI site-building pipeline SiteSpark's own app uses, reachable from your own app. Every call is billed against the real credit balance of whichever SiteSpark account issued the API key. Real API keys are created in SiteSpark under Settings > Developers. An MCP server exposing the same operations to AI agents is also available — see Settings > Developers for connection details.","contact":{"name":"SiteSpark support","email":"support@buildsitespark.com","url":"https://buildsitespark.com/contact"}},"servers":[{"url":"https://buildsitespark.com"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"sisp_live_...","description":"A real SiteSpark API key, created under Settings > Developers, sent as \"Authorization: Bearer sisp_live_...\". Each key carries its own real permission scopes (sites:read, sites:write) and can be revoked independently at any time."}},"schemas":{"Site":{"type":"object","description":"A complete SiteSpark site: its name, theme, and every page's sections (hero, products, gallery, etc.) as real structured content. Best obtained from a real GET /sites/{id} response and edited in place, rather than hand-built from scratch.","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"logoText":{"type":"string"},"pages":{"type":"array","items":{"type":"object","additionalProperties":true}},"theme":{"type":"object","additionalProperties":true}},"required":["id","name","pages"]},"SiteSummary":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"published":{"type":"boolean"},"freeStoreUrl":{"type":"string","nullable":true},"liveUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","published"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}},"responses":{"Unauthorized":{"description":"Missing or invalid API key, or the key lacks the scope this operation requires.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"NotFound":{"description":"No site with this id exists, or it isn't owned by this key's account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"paths":{"/api/v1/sites":{"post":{"operationId":"buildSite","summary":"Build a new site with AI","description":"Generates a brand-new, real website from a one-line business description — real AI-written copy, a real per-business color theme and hero image — exactly like SiteSpark's own in-app AI Generate. Creates a real Site owned by this key's account and charges its real credits. Requires the sites:write scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prompt":{"type":"string","description":"A one-line business description.","example":"A minimalist streetwear store called Northline"}},"required":["prompt"]}}}},"responses":{"201":{"description":"The real site that was built.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"usedAI":{"type":"boolean"},"pages":{"type":"array","items":{"type":"object","additionalProperties":true}},"published":{"type":"boolean"},"freeStoreUrl":{"type":"string"},"creditsRemaining":{"type":"number"},"costCharged":{"type":"number"}}}}}},"400":{"description":"Missing prompt.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Not enough credits for a full site generation.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Real abuse-prevention build rate limit hit — retry after the given delay.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"get":{"operationId":"listSites","summary":"List this account's sites","description":"Lists every real site this API key's account owns. Requires the sites:read scope.","responses":{"200":{"description":"The real list of sites.","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"published":{"type":"boolean"},"freeStoreUrl":{"type":"string","nullable":true},"liveUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","published"]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/sites/{id}":{"get":{"operationId":"getSite","summary":"Read a site's real content","description":"Returns a site's complete real content as JSON. Requires the sites:read scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The real site.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"site":{"type":"object","description":"A complete SiteSpark site: its name, theme, and every page's sections (hero, products, gallery, etc.) as real structured content. Best obtained from a real GET /sites/{id} response and edited in place, rather than hand-built from scratch.","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"logoText":{"type":"string"},"pages":{"type":"array","items":{"type":"object","additionalProperties":true}},"theme":{"type":"object","additionalProperties":true}},"required":["id","name","pages"]},"published":{"type":"boolean"},"freeStoreUrl":{"type":"string","nullable":true},"liveUrl":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"operationId":"updateSite","summary":"Replace a site's real content","description":"Replaces a site's entire content with the given JSON — real, direct code work. Shape it like a real getSite response's `site` field: fetch it, edit it, send the whole thing back. Requires the sites:write scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","description":"A complete SiteSpark site: its name, theme, and every page's sections (hero, products, gallery, etc.) as real structured content. Best obtained from a real GET /sites/{id} response and edited in place, rather than hand-built from scratch.","additionalProperties":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"logoText":{"type":"string"},"pages":{"type":"array","items":{"type":"object","additionalProperties":true}},"theme":{"type":"object","additionalProperties":true}},"required":["id","name","pages"]}},"required":["site"]}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"savedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Malformed site payload.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/sites/import":{"post":{"operationId":"importSite","summary":"Import a built site from a connected app","description":"Hands SiteSpark a whole real site as raw files (e.g. exported from a connector like NexaAi) and publishes it at a real, live URL. Keyed on externalRef: re-importing the same externalRef updates that same Site rather than creating a duplicate. Requires the sites:write scope. index.html is required; file paths may not contain path traversal (\"..\").","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalRef":{"type":"string","description":"The connected app's own stable id for this project.","example":"nexaai-project-123"},"name":{"type":"string","example":"My Store"},"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string","example":"index.html"},"content":{"type":"string"}},"required":["path","content"]}}},"required":["externalRef","files"]}}}},"responses":{"200":{"description":"The real, live site.","content":{"application/json":{"schema":{"type":"object","properties":{"siteId":{"type":"string"},"url":{"type":"string"}}}}}},"400":{"description":"Missing externalRef, missing files, or an invalid file (bad path, missing index.html).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"description":"The import payload is too large.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/v1/sites/{id}/publish":{"post":{"operationId":"publishSite","summary":"Publish a site","description":"Makes a site's real, free store URL (and any connected custom domain) go live for real visitors. Requires the sites:write scope.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published.","content":{"application/json":{"schema":{"type":"object","properties":{"published":{"type":"boolean"},"slug":{"type":"string"},"freeStoreUrl":{"type":"string"},"liveUrl":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}