{"openapi":"3.1.0","info":{"title":"Clawnify API","version":"1.0.0","description":"The Clawnify HTTP API lets you provision, update, and tear down user-facing apps programmatically from your own backend or automations. It powers the same flows used by the [Clawnify dashboard](https://clawnify.com) and the `clawnify` CLI.\n\n## Authentication\n\nAll `/v1/*` endpoints require a bearer token in the `Authorization` header:\n\n```bash\ncurl https://api.clawnify.com/v1/apps \\\n  -H \"Authorization: Bearer $CLAWNIFY_TOKEN\"\n```\n\nThe token can be either:\n\n- A **Supabase access token (JWT)** obtained via Google OAuth on clawnify.com (this is what the dashboard and CLI use).\n- A **Clawnify API key** scoped to an organization (issued from the dashboard Settings page).\n\nRequests without a valid token return `401 Unauthorized`. Requests from members of a different organization return `404 Not Found` (we never disclose existence across org boundaries).\n\n## Rate limits\n\nWrite endpoints are rate-limited per organization:\n\n| Endpoint | Limit |\n| --- | --- |\n| `POST /v1/apps/deploy` | 5 requests per 5 minutes |\n\nExceeding a limit returns `429 Too Many Requests` with a `Retry-After` header. Read endpoints are not rate-limited.\n\n## Versioning\n\nThe current stable version is `v1`. Breaking changes will ship under a new prefix (`v2`, ...) and `v1` will continue to work for a 12-month deprecation window. Non-breaking additions (new optional fields, new operations) will land under `v1` without a version bump.\n\n## Support\n\nSource of truth: [`github.com/clawnify/clawnify`](https://github.com/clawnify/clawnify). Open issues or reach out at [support@clawnify.com](mailto:support@clawnify.com)."},"servers":[{"url":"https://api.clawnify.com","description":"Production"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Supabase access token (JWT) or a Clawnify API key. Pass as `Authorization: Bearer <token>`."}},"schemas":{"DeployResponse":{"type":"object","properties":{"app_id":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"slug":{"type":"string","example":"example-todo"},"app_token":{"type":"string","description":"Bearer token for authenticated requests to the deployed app."},"url":{"type":"string","format":"uri","example":"https://example-todo.apps.clawnify.com"}},"required":["app_id","slug","app_token","url"]},"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"DeployRequest":{"type":"object","properties":{"repo":{"type":"string","pattern":"^[a-zA-Z0-9_.-]+\\/[a-zA-Z0-9_.-]+$","description":"GitHub repository in 'owner/name' format.","example":"clawnify/example-todo"},"branch":{"type":"string","description":"Branch to deploy. Defaults to 'main'.","example":"main"},"customization":{"type":"string","description":"Natural-language customization instructions passed to the app builder agent."}},"required":["repo"]},"AppSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","example":"ready"},"status_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"app_token":{"type":"string"}},"required":["id","name","slug","status","status_message","created_at","updated_at","app_token"]},"ListAppsResponse":{"type":"object","properties":{"apps":{"type":"array","items":{"$ref":"#/components/schemas/AppSummary"}}},"required":["apps"]},"AppDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"},"org_id":{"type":"string","format":"uuid"},"created_by":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"status_message":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"app_token":{"type":"string"},"manifest":{"type":"object","nullable":true,"properties":{"d1_database_id":{"type":"string"},"r2_bucket_name":{"type":"string"},"framework":{"type":"string"}}},"url":{"type":"string","format":"uri"}},"required":["id","name","slug","status","created_at","updated_at","app_token","url"]},"DeleteResponse":{"type":"object","properties":{"status":{"type":"string","enum":["deleted"]}},"required":["status"]},"LogsResponse":{"type":"object","properties":{"status":{"type":"string"},"status_message":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"logs":{"type":"string","nullable":true}},"required":["status","status_message","error","logs"]}},"parameters":{}},"paths":{"/v1/apps/deploy":{"post":{"tags":["Apps"],"summary":"Deploy an app from a GitHub repository","description":"Provisions a new Clawnify app by cloning the given GitHub repo and running the build pipeline. Returns the app ID, public URL, and a bearer token for authenticated requests to the deployed app.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployRequest"}}}},"responses":{"201":{"description":"App deployment initiated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeployResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apps":{"get":{"tags":["Apps"],"summary":"List deployed apps","description":"Returns every app belonging to the authenticated organization.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of apps","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAppsResponse"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apps/{id}":{"get":{"tags":["Apps"],"summary":"Get app details","description":"Fetches the full record for a single app, including its current build status and public URL.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"App details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppDetail"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Apps"],"summary":"Delete an app","description":"Tears down the Workers for Platforms script, D1 database, R2 source files, and KV auth entry, then removes the app record.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"App deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/apps/{id}/logs":{"get":{"tags":["Apps"],"summary":"Get build logs","description":"Returns the current build status and the raw build log (if one exists in R2).","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid","example":"3fa85f64-5717-4562-b3fc-2c963f66afa6"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Build logs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogsResponse"}}}},"404":{"description":"App not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}