{ "openapi": "3.1.0", "info": { "title": "Vlendo API — proposed contract", "version": "0.1.0-draft", "description": "Design reference and local simulator, not an available production API. All amounts are integer euro cents. All data is fictional. Stripe is an existing integration; the Vlendo public API and Zapier connector require implementation and validation.", "contact": { "email": "hello@vlendo.com" } }, "servers": [ { "url": "https://api.vlendo.example/v1", "description": "Reserved example hostname — not a live API" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Centers" }, { "name": "Plans" }, { "name": "Checkout" }, { "name": "Memberships" }, { "name": "Requests" }, { "name": "Events" }, { "name": "Webhooks" } ], "paths": { "/centers": { "get": { "operationId": "centers", "tags": [ "Centers" ], "summary": "List locations", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "centers:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor. Unknown cursors are rejected." } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CenterList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/plans": { "get": { "operationId": "plans", "tags": [ "Plans" ], "summary": "List plans", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "plans:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor. Unknown cursors are rejected." }, { "name": "center_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/checkout/sessions": { "post": { "operationId": "checkout", "tags": [ "Checkout" ], "summary": "Create a checkout session", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "checkout:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutInput" }, "example": { "center_id": "ctr_north", "plan_id": "plan_month", "member_reference": "demo_member_003", "start_date": "2026-11-06" } } } } } }, "/memberships": { "get": { "operationId": "memberships", "tags": [ "Memberships" ], "summary": "List memberships", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "memberships:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor. Unknown cursors are rejected." }, { "name": "center_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembershipList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/memberships/{membership_id}": { "get": { "operationId": "membership", "tags": [ "Memberships" ], "summary": "Retrieve a membership", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "memberships:read", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Membership" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/requests": { "post": { "operationId": "requests", "tags": [ "Requests" ], "summary": "Create a member request", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "requests:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRequest" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestInput" }, "example": { "membership_id": "mem_demo_001", "type": "cancellation" } } } } } }, "/requests/{request_id}": { "get": { "operationId": "request", "tags": [ "Requests" ], "summary": "Retrieve a request", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "requests:read", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRequest" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/events": { "get": { "operationId": "events", "tags": [ "Events" ], "summary": "List events, newest first", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "events:read", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "starting_after", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor. Unknown cursors are rejected." }, { "name": "center_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/webhook-endpoints": { "post": { "operationId": "webhooks", "tags": [ "Webhooks" ], "summary": "Subscribe to events", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "webhooks:write", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" }, "example": { "url": "https://hooks.example/your-workflow", "events": [ "membership.activated", "request.created" ] } } } } } }, "/webhook-endpoints/{endpoint_id}": { "delete": { "operationId": "delete_webhook", "tags": [ "Webhooks" ], "summary": "Delete an event subscription", "description": "PROPOSED CONTRACT. Browser-only simulator; no production endpoint exists at the example origin.", "x-required-scope": "webhooks:write", "parameters": [ { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Simulated success", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "409": { "$ref": "#/components/responses/409" }, "422": { "$ref": "#/components/responses/422" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Proposed server-side credential. The playground uses a fixed demo placeholder only." } }, "schemas": { "Center": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "center" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "status": { "type": "string", "enum": [ "active" ] } }, "required": [ "id", "object", "name", "timezone", "status" ], "additionalProperties": false }, "Plan": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "plan" }, "center_id": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "integer", "minimum": 0 }, "joining_fee": { "type": "integer", "minimum": 0 }, "currency": { "const": "eur" }, "duration": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "day", "week", "month" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "unit", "count" ], "additionalProperties": false }, "renewable": { "type": "boolean" } }, "required": [ "id", "object", "center_id", "name", "amount", "joining_fee", "currency", "duration", "renewable" ], "additionalProperties": false }, "CheckoutInput": { "type": "object", "properties": { "center_id": { "type": "string", "minLength": 1 }, "plan_id": { "type": "string", "minLength": 1 }, "member_reference": { "type": "string", "minLength": 1, "maxLength": 120 }, "start_date": { "type": "string", "format": "date" } }, "required": [ "center_id", "plan_id", "member_reference", "start_date" ], "additionalProperties": false }, "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "checkout.session" }, "center_id": { "type": "string" }, "plan_id": { "type": "string" }, "member_reference": { "type": "string" }, "start_date": { "type": "string", "format": "date" }, "amount_total": { "type": "integer" }, "currency": { "const": "eur" }, "status": { "type": "string", "enum": [ "pending_payment" ] }, "provider": { "const": "stripe" }, "checkout_url": { "type": "string", "format": "uri" }, "livemode": { "const": false } }, "required": [ "id", "object", "center_id", "plan_id", "member_reference", "start_date", "amount_total", "currency", "status", "provider", "checkout_url", "livemode" ], "additionalProperties": false }, "Membership": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "membership" }, "center_id": { "type": "string" }, "plan_id": { "type": "string" }, "member_reference": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "pending_payment", "cancelled" ] }, "started_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "center_id", "plan_id", "member_reference", "status", "started_at" ], "additionalProperties": false }, "RequestInput": { "type": "object", "properties": { "membership_id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "cancellation", "plan_change" ] } }, "required": [ "membership_id", "type" ], "additionalProperties": false }, "MemberRequest": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "member_request" }, "membership_id": { "type": "string" }, "type": { "type": "string", "enum": [ "cancellation", "plan_change" ] }, "status": { "type": "string", "enum": [ "received" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "object", "membership_id", "type", "status", "created_at" ], "additionalProperties": false }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://" }, "events": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": [ "membership.activated", "payment.confirmed", "request.created" ] } } }, "required": [ "url", "events" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "status": { "const": "enabled" } }, "required": [ "id", "object", "url", "events", "status" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "event" }, "type": { "type": "string", "enum": [ "membership.activated", "payment.confirmed", "request.created" ] }, "created_at": { "type": "string", "format": "date-time" }, "api_version": { "const": "2026-11-05" }, "data": { "type": "object", "properties": { "object_id": { "type": "string" }, "center_id": { "type": "string" } }, "required": [ "object_id", "center_id" ], "additionalProperties": false }, "livemode": { "const": false } }, "required": [ "id", "object", "type", "created_at", "api_version", "data", "livemode" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "param", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "Deleted": { "type": "object", "properties": { "id": { "type": "string" }, "deleted": { "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "CenterList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Center" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "PlanList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MembershipList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Membership" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "EventList": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false } }, "responses": { "400": { "description": "Malformed request", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing authentication", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient permissions", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource not found", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation error", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "X-Request-Id": { "schema": { "type": "string" } }, "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }