{ "openapi": "3.1.0", "info": { "title": "Prevu API", "version": "0.1.0", "description": "REST API for Prevu, the staging and review layer for coding agents. Use it to create persistent VM-backed environments, retrieve SSH commands, expose ports, manage services, and pause or resume workspaces. Rate limits are documented at https://prevu.cloud/rate-limits.md; clients should honor 429 and Retry-After." }, "servers": [ { "url": "https://app.prevu.cloud/api/v1", "description": "Production API" }, { "url": "https://prevu.cloud/api/v1", "description": "Discovery and structured JSON error probe endpoint" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Prevu personal access token" } }, "schemas": { "Environment": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "creating", "ready", "paused", "error", "destroying" ] }, "sshCommand": { "type": "string" }, "urls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "EnvironmentCreateRequest": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "project": { "type": "string" }, "cpu": { "type": "integer", "minimum": 1 }, "memoryGi": { "type": "integer", "minimum": 1 }, "diskGi": { "type": "integer", "minimum": 1 } } }, "PortExposeRequest": { "type": "object", "required": [ "port" ], "properties": { "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "mode": { "type": "string", "enum": [ "https", "tcp" ], "default": "https" } } }, "ServiceStartRequest": { "type": "object", "required": [ "name", "command" ], "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "cwd": { "type": "string", "default": "/workspace" }, "port": { "type": "integer" } } }, "Error": { "type": "object", "properties": { "error": { "type": "string" } } }, "ApiError": { "type": "object", "required": [ "code", "message", "hint", "status" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code, for example unauthorized, not_found, validation_error, rate_limited." }, "message": { "type": "string", "description": "Human-readable summary." }, "hint": { "type": "string", "description": "Actionable recovery instruction for agents." }, "status": { "type": "integer", "description": "HTTP status code." }, "field": { "type": "string", "description": "Affected request field when available." }, "retryAfter": { "type": "integer", "description": "Seconds to wait before retrying when rate limited." }, "docs": { "type": "string", "format": "uri" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ApiError" } } }, "Pagination": { "type": "object", "properties": { "nextCursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" } } }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": [ "string", "null" ] } } }, "Quota": { "type": "object", "properties": { "retainedEnvironments": { "type": "integer" }, "runningEnvironments": { "type": "integer" }, "diskGi": { "type": "integer" } } }, "EnvironmentList": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "SshCommand": { "type": "object", "properties": { "sshCommand": { "type": "string" } } }, "PublicPort": { "type": "object", "properties": { "port": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "mode": { "type": "string", "enum": [ "https", "tcp" ] } } }, "Service": { "type": "object", "properties": { "name": { "type": "string" }, "command": { "type": "string" }, "status": { "type": "string" }, "port": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ], "format": "uri" } } }, "ServiceList": { "type": "object", "properties": { "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "Logs": { "type": "object", "properties": { "logs": { "type": "string" }, "tail": { "type": "integer" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid bearer token.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "unauthorized", "message": "Authentication is required.", "hint": "Create a token at https://app.prevu.cloud/keys and send Authorization: Bearer .", "status": 401, "docs": "https://prevu.cloud/openapi.json" } } } } }, "NotFound": { "description": "Resource or route not found.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Invalid request body or parameters.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Rate limit exceeded. Back off and honor Retry-After.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests.", "hint": "Wait the number of seconds in Retry-After, then retry with exponential backoff.", "status": 429, "retryAfter": 60 } } } } } } }, "paths": { "/me": { "get": { "summary": "Get current user", "operationId": "getMe", "responses": { "200": { "description": "Authenticated user", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Get current user", "tags": [ "me" ] } }, "/quota": { "get": { "summary": "Get quota status", "operationId": "getQuota", "responses": { "200": { "description": "Quota and usage", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quota" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Get quota status", "tags": [ "quota" ] } }, "/environments": { "get": { "summary": "List environments", "operationId": "listEnvironments", "responses": { "200": { "description": "Environment list", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentList" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "List environments", "tags": [ "environments" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum rows to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous response." } ] }, "post": { "summary": "Create environment", "operationId": "createEnvironment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentCreateRequest" } } } }, "responses": { "201": { "description": "Created environment", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Create environment", "tags": [ "environments" ] } }, "/environments/refresh": { "post": { "summary": "Refresh all environment statuses", "operationId": "refreshEnvironments", "responses": { "200": { "description": "Refresh result", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Refresh all environment statuses", "tags": [ "environments" ] } }, "/environments/{slug}": { "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "summary": "Get environment", "operationId": "getEnvironment", "responses": { "200": { "description": "Environment detail", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } } }, "404": { "description": "Not found", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Get environment", "tags": [ "environments" ] }, "delete": { "summary": "Destroy environment permanently", "operationId": "destroyEnvironment", "description": "Permanently deletes the VM and workspace. Agents should call only after explicit user confirmation.", "responses": { "200": { "description": "Destroyed", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "tags": [ "environments" ] } }, "/environments/{slug}/pause": { "post": { "summary": "Pause environment compute", "operationId": "pauseEnvironment", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paused", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Pause environment compute", "tags": [ "environments" ] } }, "/environments/{slug}/resume": { "post": { "summary": "Resume environment compute", "operationId": "resumeEnvironment", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Resumed", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Resume environment compute", "tags": [ "environments" ] } }, "/environments/{slug}/refresh": { "post": { "summary": "Refresh one environment", "operationId": "refreshEnvironment", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refresh result", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Refresh one environment", "tags": [ "environments" ] } }, "/environments/{slug}/ssh": { "get": { "summary": "Get SSH command", "operationId": "getEnvironmentSsh", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "SSH command", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Get SSH command", "tags": [ "environments" ] } }, "/environments/{slug}/terminal": { "post": { "summary": "Create browser terminal session", "operationId": "createTerminalSession", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Terminal session token", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Create browser terminal session", "tags": [ "environments" ] } }, "/environments/{slug}/ports": { "post": { "summary": "Expose a port", "operationId": "exposePort", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortExposeRequest" } } } }, "responses": { "200": { "description": "Public URL", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "port": { "$ref": "#/components/schemas/PublicPort" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Expose a port", "tags": [ "environments" ] } }, "/environments/{slug}/ports/{port}": { "delete": { "summary": "Unexpose a port", "operationId": "unexposePort", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "port", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Removed", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "port": { "$ref": "#/components/schemas/PublicPort" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Unexpose a port", "tags": [ "environments" ] } }, "/environments/{slug}/services": { "get": { "summary": "List managed services", "operationId": "listServices", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum rows to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous response." } ], "responses": { "200": { "description": "Services", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "List managed services", "tags": [ "environments" ] }, "post": { "summary": "Start managed service", "operationId": "startService", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceStartRequest" } } } }, "responses": { "200": { "description": "Started", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Start managed service", "tags": [ "environments" ] } }, "/environments/{slug}/services/{name}": { "delete": { "summary": "Stop managed service", "operationId": "stopService", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stopped", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Stop managed service", "tags": [ "environments" ] } }, "/environments/{slug}/services/{name}/restart": { "post": { "summary": "Restart managed service", "operationId": "restartService", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Restarted", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "$ref": "#/components/schemas/Service" } } } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Restart managed service", "tags": [ "environments" ] } }, "/environments/{slug}/services/{name}/logs": { "get": { "summary": "Get service logs", "operationId": "getServiceLogs", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "tail", "in": "query", "schema": { "type": "integer", "default": 200 } } ], "responses": { "200": { "description": "Logs", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Logs" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Get service logs", "tags": [ "environments" ] } }, "/keys": { "get": { "summary": "List API keys", "operationId": "listKeys", "responses": { "200": { "description": "Keys", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "List API keys", "tags": [ "keys" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum rows to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous response." } ] }, "post": { "summary": "Create API key", "operationId": "createKey", "responses": { "201": { "description": "Created key", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Create API key", "tags": [ "keys" ] } }, "/tokens": { "get": { "summary": "List personal access tokens", "operationId": "listTokens", "responses": { "200": { "description": "Tokens", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "List personal access tokens", "tags": [ "tokens" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum rows to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque pagination cursor from the previous response." } ] }, "post": { "summary": "Create personal access token", "operationId": "createToken", "responses": { "201": { "description": "Created token", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Create personal access token", "tags": [ "tokens" ] } }, "/tokens/{id}": { "delete": { "summary": "Revoke personal access token", "operationId": "revokeToken", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Maximum requests in the active window" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Remaining requests in the active window" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Seconds until the active window resets" }, "RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Standard rate limit maximum" }, "RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Standard remaining request count" }, "RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Standard reset delay in seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "400": { "$ref": "#/components/responses/ValidationError" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "404": { "$ref": "#/components/responses/NotFound" } }, "description": "Revoke personal access token", "tags": [ "tokens" ] } } }, "x-rateLimit": { "authenticatedPerTokenPerMinute": 120, "mutationPerTokenPerMinute": 30, "retryHeader": "Retry-After", "documentation": "https://prevu.cloud/rate-limits.md" }, "x-cli": { "package": "@prevu/cli", "registry": "npm", "install": "npm install -g @prevu/cli", "url": "https://www.npmjs.com/package/@prevu/cli", "jsonOutput": "--format json" }, "x-sdks": { "catalog": "https://prevu.cloud/.well-known/sdk-catalog.json", "openapiGeneratorCompatible": true }, "x-mcp": { "discovery": "https://prevu.cloud/.well-known/mcp", "serverCard": "https://prevu.cloud/.well-known/mcp/server-card.json", "streamableHttp": "https://app.prevu.cloud/api/mcp" } }