{ "openapi": "3.1.0", "info": { "title": "VibeInfra Public API & SRE Flight Simulator Engine", "version": "1.0.0", "summary": "Course catalog, live platform capacity, disposable sandbox orchestration, automated evaluation, and Agentic Commerce Protocol (ACP).", "description": "VibeInfra is a learn-by-doing infrastructure engineering platform. Engineers troubleshoot realistic production incidents (Linux kernel, Docker, Kubernetes, Nginx, PostgreSQL, Kafka, AWS) inside live disposable multi-container sandboxes with automated grading across the 7-step incident lifecycle.", "contact": { "name": "VibeInfra Developer Relations", "url": "https://vibeinfra.id/developers/", "email": "hello@vibeinfra.id" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "x-category": "Infrastructure & DevOps", "x-categories": [ "Infrastructure & DevOps", "Developer Tools" ], "x-deprecation-policy": "https://vibeinfra.id/docs/deprecation.md", "x-sunset-policy": "Minimum 12-month notice signaled via standard HTTP Sunset and Deprecation headers", "x-versioning": "Path-based versioning (/api/v1/) and header-based versioning (API-Version: YYYY-MM-DD)" }, "servers": [ { "url": "https://vibeinfra.id/api/v1", "description": "Production API (Primary)" }, { "url": "https://api.vibeinfra.id/api/v1", "description": "Production API (Direct Host)" }, { "url": "https://vibeinfra.id", "description": "Root Host (ACP & Agent Protocols)" } ], "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "Platform" ], "summary": "Liveness probe", "description": "Returns healthy operational status and engine version.", "responses": { "200": { "description": "API is operational.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/courses": { "get": { "operationId": "listCourses", "tags": [ "Catalog" ], "summary": "List courses and incidents with cursor-based pagination", "description": "Returns available SRE flight simulator courses, foundational labs, and incident scenarios.", "parameters": [ { "name": "cursor", "in": "query", "description": "Pagination cursor for next page of items", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results per page (default 20, max 100)", "schema": { "type": "integer", "default": 20, "maximum": 100 } }, { "name": "tier", "in": "query", "description": "Filter by difficulty tier", "schema": { "type": "string", "enum": [ "beginner", "intermediate", "advanced", "expert" ] } }, { "name": "domain", "in": "query", "description": "Filter by engineering domain", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated course list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCoursesResponse" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/courses/{courseId}": { "get": { "operationId": "getCourseDetails", "tags": [ "Catalog" ], "summary": "Get incident course details", "description": "Retrieves comprehensive scenario topology, learning objectives, and fault description for a specific course.", "parameters": [ { "name": "courseId", "in": "path", "required": true, "description": "Course identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Course details object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseDetails" } } } }, "404": { "$ref": "#/components/responses/404NotFound" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/sandbox/start": { "post": { "operationId": "startSandbox", "tags": [ "Labs" ], "summary": "Start disposable incident sandbox", "description": "Provisions isolated multi-container sandbox session. Supports synchronous start or 202 Accepted asynchronous start pattern for large clusters.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSandboxRequest" } } } }, "responses": { "200": { "description": "Sandbox initialized and ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSession" } } } }, "202": { "description": "Async sandbox provisioning started. Poll status at status_url.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AsyncJobResponse" } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "400": { "$ref": "#/components/responses/400BadRequest" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/sandbox/eval": { "post": { "operationId": "evaluateSandbox", "tags": [ "Labs" ], "summary": "Evaluate running sandbox incident recovery", "description": "Runs automated 7-step verification checks against live container states.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateSandboxRequest" } } } }, "responses": { "200": { "description": "Evaluation checkpoint results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResult" } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "404": { "$ref": "#/components/responses/404NotFound" }, "400": { "$ref": "#/components/responses/400BadRequest" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/batch": { "post": { "operationId": "executeBatchOperations", "tags": [ "Platform" ], "summary": "Bulk / Batch operations", "description": "Execute multiple read/write operations in a single atomic or sequential batch request.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchRequest" } } } }, "responses": { "200": { "description": "Batch operation responses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/checkout_sessions": { "post": { "operationId": "createCheckoutSession", "tags": [ "Commerce (ACP)" ], "summary": "Create Agentic Commerce Protocol checkout session", "description": "Initializes an ACP-compliant checkout session for Pro subscriptions or Founding Engineer passes.", "parameters": [ { "$ref": "#/components/parameters/APIVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" } } } }, "responses": { "201": { "description": "Checkout session created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/checkout_sessions/{sessionId}": { "get": { "operationId": "getCheckoutSession", "tags": [ "Commerce (ACP)" ], "summary": "Retrieve checkout session status", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/APIVersion" } ], "responses": { "200": { "description": "Current checkout session state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "404": { "$ref": "#/components/responses/404NotFound" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/checkout_sessions/{sessionId}/complete": { "post": { "operationId": "completeCheckoutSession", "tags": [ "Commerce (ACP)" ], "summary": "Complete checkout session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/APIVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Session completed and entitlement activated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "404": { "$ref": "#/components/responses/404NotFound" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } }, "/checkout_sessions/{sessionId}/cancel": { "post": { "operationId": "cancelCheckoutSession", "tags": [ "Commerce (ACP)" ], "summary": "Cancel checkout session", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/APIVersion" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Session cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/400BadRequest" }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "404": { "$ref": "#/components/responses/404NotFound" }, "429": { "$ref": "#/components/responses/429RateLimited" }, "500": { "$ref": "#/components/responses/500InternalServerError" } } } } }, "components": { "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique UUID to safely retry write operations without duplicating state or charges.", "schema": { "type": "string", "format": "uuid" } }, "APIVersion": { "name": "API-Version", "in": "header", "required": false, "description": "Requested API version date (e.g. 2026-09-04).", "schema": { "type": "string", "example": "2026-09-04" } } }, "responses": { "400BadRequest": { "description": "Bad Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401Unauthorized": { "description": "Authentication required. Check WWW-Authenticate header for resource metadata.", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer resource_metadata=\"https://vibeinfra.id/.well-known/oauth-protected-resource\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429RateLimited": { "description": "Rate limit exceeded.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500InternalServerError": { "description": "Internal Server Error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Authentication required." }, "resolution_hint": { "type": "string", "example": "Fetch https://vibeinfra.id/.well-known/oauth-protected-resource." } } } } }, "HealthResponse": { "type": "object", "required": [ "status", "version" ], "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "1.0.0" } } }, "PaginatedCoursesResponse": { "type": "object", "required": [ "items", "has_more" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CourseDetails" } }, "next_cursor": { "type": "string", "nullable": true }, "has_more": { "type": "boolean" }, "total_count": { "type": "integer" } } }, "CourseDetails": { "type": "object", "required": [ "id", "title", "tier", "domain", "description" ], "properties": { "id": { "type": "string", "example": "incident-21-flight-simulator" }, "title": { "type": "string", "example": "Checkout API Latency Regression" }, "tier": { "type": "string", "enum": [ "beginner", "intermediate", "advanced", "expert" ] }, "domain": { "type": "string", "example": "database" }, "description": { "type": "string" }, "duration_minutes": { "type": "integer", "example": 45 }, "stack": { "type": "array", "items": { "type": "string" } } } }, "StartSandboxRequest": { "type": "object", "required": [ "course_id" ], "properties": { "course_id": { "type": "string", "example": "incident-21-flight-simulator" }, "async": { "type": "boolean", "default": false } } }, "SandboxSession": { "type": "object", "required": [ "session_id", "status" ], "properties": { "session_id": { "type": "string", "example": "sess_9918237" }, "status": { "type": "string", "enum": [ "starting", "running", "completed", "terminated" ] }, "terminal_url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "AsyncJobResponse": { "type": "object", "required": [ "job_id", "status_url", "status" ], "properties": { "job_id": { "type": "string", "example": "job_sandbox_prov_123" }, "status_url": { "type": "string", "example": "/api/v1/jobs/job_sandbox_prov_123" }, "status": { "type": "string", "example": "in_progress" }, "poll_after_seconds": { "type": "integer", "example": 3 } } }, "EvaluateSandboxRequest": { "type": "object", "required": [ "session_id" ], "properties": { "session_id": { "type": "string" } } }, "EvaluationResult": { "type": "object", "required": [ "passed", "score", "checkpoints" ], "properties": { "passed": { "type": "boolean" }, "score": { "type": "integer" }, "checkpoints": { "type": "array", "items": { "type": "object", "required": [ "name", "passed" ], "properties": { "name": { "type": "string" }, "passed": { "type": "boolean" }, "output": { "type": "string" } } } } } }, "BatchRequest": { "type": "object", "required": [ "requests" ], "properties": { "requests": { "type": "array", "items": { "type": "object", "required": [ "method", "path" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE" ] }, "path": { "type": "string" }, "body": { "type": "object" } } } } } }, "BatchResponse": { "type": "object", "required": [ "responses" ], "properties": { "responses": { "type": "array", "items": { "type": "object", "required": [ "status", "body" ], "properties": { "status": { "type": "integer" }, "body": { "type": "object" } } } } } }, "CreateCheckoutSessionRequest": { "type": "object", "required": [ "plan_id" ], "properties": { "plan_id": { "type": "string", "enum": [ "pro_monthly", "founding_pass" ] }, "success_url": { "type": "string" }, "cancel_url": { "type": "string" } } }, "CheckoutSession": { "type": "object", "required": [ "id", "status", "payment_url" ], "properties": { "id": { "type": "string", "example": "cs_acp_991823719" }, "status": { "type": "string", "enum": [ "open", "completed", "expired", "cancelled" ] }, "payment_url": { "type": "string" }, "amount": { "type": "integer" }, "currency": { "type": "string", "example": "IDR" } } } } } }