{ "openapi": "3.0.3", "info": { "title": "Cruss API", "description": "The Cruss Worker API — backend for the free team API workspace. All collaboration features are free. Organisations Pro ($15/month flat) unlocks unlimited org workspaces.", "version": "1.0.0", "contact": { "name": "Cruss", "url": "https://cruss.io", "email": "support@cruss.io" }, "license": { "name": "MIT", "url": "https://github.com/Cruss-API/blob/main/LICENSE" }, "x-logo": { "url": "https://cruss.io/android-chrome-512x512.png" } }, "servers": [ { "url": "https://api.cruss.io", "description": "Production" }, { "url": "https://cruss-worker.westwizo.workers.dev", "description": "Staging" } ], "tags": [ { "name": "workspaces", "description": "Workspace management" }, { "name": "collections", "description": "Request collections and folders" }, { "name": "requests", "description": "Individual API requests" }, { "name": "environments", "description": "Environment variables" }, { "name": "proxy", "description": "HTTP proxy for sending requests" }, { "name": "docs", "description": "Published API documentation" }, { "name": "history", "description": "Request history" }, { "name": "organizations", "description": "Organisations (Pro feature)" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT obtained from Supabase Auth. Include as: Authorization: Bearer " } }, "schemas": { "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Backend Team" }, "slug": { "type": "string", "example": "backend-team" }, "created_at": { "type": "string", "format": "date-time" } } }, "WorkspaceWithRole": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/Workspace" }, "role": { "type": "string", "enum": [ "admin", "editor", "viewer" ] } } }, "Collection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "User API" }, "parent_id": { "type": "string", "format": "uuid", "nullable": true }, "sort_order": { "type": "integer" }, "requests": { "type": "array", "items": { "$ref": "#/components/schemas/Request" } }, "workspace_id": { "type": "string", "format": "uuid" } } }, "Request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Get user profile" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS" ] }, "url": { "type": "string", "example": "https://api.example.com/users/{{userId}}" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "params": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "nullable": true }, "body_type": { "type": "string", "enum": [ "none", "json", "raw", "form-data", "urlencoded" ] }, "auth": { "nullable": true }, "description": { "type": "string", "nullable": true }, "sort_order": { "type": "integer" }, "collection_id": { "type": "string", "format": "uuid" } } }, "Environment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Production" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "baseUrl": "https://api.example.com", "apiKey": "sk-..." } } } }, "ProxyRequest": { "type": "object", "required": [ "method", "url" ], "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS" ] }, "url": { "type": "string", "example": "https://api.example.com/users" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string", "nullable": true }, "timeout_ms": { "type": "integer", "default": 30000, "maximum": 120000 } } }, "ProxyResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "integer", "example": 200 }, "statusText": { "type": "string", "example": "OK" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "body": { "type": "string" }, "responseTime": { "type": "integer", "description": "Milliseconds" }, "size": { "type": "integer", "description": "Bytes" } } } } }, "DocPage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "slug": { "type": "string", "example": "my-api-v1" }, "is_published": { "type": "boolean" }, "collection_id": { "type": "string", "format": "uuid", "nullable": true }, "updated_at": { "type": "string", "format": "date-time" }, "content": { "type": "object", "description": "Structured doc content with endpoints array" } } }, "Organisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Acme Engineering" }, "slug": { "type": "string", "example": "acme-engineering" }, "plan": { "type": "string", "enum": [ "free", "pro" ] } } }, "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/workspaces": { "get": { "tags": [ "workspaces" ], "summary": "List workspaces for the authenticated user", "operationId": "listWorkspaces", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceWithRole" } } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/collections/workspace/{workspaceId}": { "get": { "tags": [ "collections" ], "summary": "List all collections in a workspace", "operationId": "listCollections", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "collections" ], "summary": "Create a collection in a workspace", "operationId": "createCollection", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "parent_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Collection" } } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Insufficient permissions" } } } }, "/collections/{id}": { "patch": { "tags": [ "collections" ], "summary": "Update a collection", "operationId": "updateCollection", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } }, "delete": { "tags": [ "collections" ], "summary": "Delete a collection and all its requests", "operationId": "deleteCollection", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/requests/collection/{collectionId}": { "post": { "tags": [ "requests" ], "summary": "Create a request in a collection", "operationId": "createRequest", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "method", "url" ], "properties": { "name": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS" ] }, "url": { "type": "string" }, "headers": { "type": "object" }, "params": { "type": "object" }, "body": {}, "body_type": { "type": "string" }, "auth": {}, "description": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Request" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/requests/{id}": { "get": { "tags": [ "requests" ], "summary": "Get a single request", "operationId": "getRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "404": { "description": "Not found" } } }, "patch": { "tags": [ "requests" ], "summary": "Update a request", "operationId": "updateRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Request" } } } }, "responses": { "200": { "description": "Updated" }, "401": { "description": "Unauthorized" } } }, "delete": { "tags": [ "requests" ], "summary": "Delete a request", "operationId": "deleteRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "description": "Unauthorized" } } } }, "/requests/{id}/duplicate": { "post": { "tags": [ "requests" ], "summary": "Duplicate a request within its collection", "operationId": "duplicateRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Duplicated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Request" } } } } } }, "401": { "description": "Unauthorized" } } } }, "/proxy": { "post": { "tags": [ "proxy" ], "summary": "Proxy an HTTP request through the Cruss Worker", "description": "Forwards an HTTP request from the Cloudflare Worker edge. Use this to avoid CORS restrictions in the browser. In the VS Code extension, use direct Node.js fetch instead.", "operationId": "proxyRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyRequest" } } } }, "responses": { "200": { "description": "Response from the proxied endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyResponse" } } } }, "400": { "description": "Invalid request" }, "429": { "description": "Rate limited (200 requests/min)" } } } }, "/environments/workspace/{workspaceId}": { "get": { "tags": [ "environments" ], "summary": "List environments for a workspace", "operationId": "listEnvironments", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } } } } } } } } }, "post": { "tags": [ "environments" ], "summary": "Create an environment", "operationId": "createEnvironment", "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Created" } } } }, "/docs/public": { "get": { "tags": [ "docs" ], "summary": "List all published API documentation pages", "operationId": "listPublishedDocs", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } } } }, "/docs/{slug}": { "get": { "tags": [ "docs" ], "summary": "Get a published API documentation page by slug", "operationId": "getDocPage", "security": [], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "example": "my-api-v1" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DocPage" } } } } } }, "404": { "description": "Not found" } } } }, "/history": { "get": { "tags": [ "history" ], "summary": "List request history for the authenticated user", "operationId": "listHistory", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "response_status": { "type": "integer", "nullable": true }, "response_time_ms": { "type": "integer", "nullable": true } } } } } } } } } } }, "delete": { "tags": [ "history" ], "summary": "Clear all request history for the authenticated user", "operationId": "clearHistory", "responses": { "200": { "description": "Cleared" } } } }, "/organizations": { "get": { "tags": [ "organizations" ], "summary": "List organisations for the authenticated user", "operationId": "listOrganizations", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Organisation" }, { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ] } } } ] } } } } } } }, "401": { "description": "Unauthorized" } } }, "post": { "tags": [ "organizations" ], "summary": "Create an organisation", "operationId": "createOrganization", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } } } } }, "responses": { "200": { "description": "Created" }, "401": { "description": "Unauthorized" } } } }, "/organizations/{id}/workspaces": { "get": { "tags": [ "organizations" ], "summary": "List workspaces in an organisation", "operationId": "listOrgWorkspaces", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "description": "Unauthorized" }, "403": { "description": "Not a member" } } } } } }