# Cruss — Complete Documentation

Cruss is a free, open-source API workspace for teams. It is a Postman
alternative with no paywalls. All collaboration features are free forever.
Source: https://cruss.io | API: https://api.cruss.io | GitHub: https://github.com/Cruss-API

---

## 1. What is Cruss?

Cruss is an HTTP API client and team workspace. Use it to:
- Build and send REST, GraphQL, and raw HTTP requests
- Organise requests into collections that your team can share
- Run entire collections sequentially (Collection Runner)
- Chain requests by passing response values into later requests
- Generate and publish public API documentation from your collections
- Test localhost APIs without CORS using the VS Code extension or local agent

Cruss is not a monitoring tool and not a mock server. It is an API client.

---

## 2. Core concepts

### Workspaces
A workspace is a shared space for a team. It contains collections, environments,
and member roles. Every user can create workspaces for free with no member limit.
Roles: admin (full control), editor (create/edit requests), viewer (read + send only).

### Collections
A collection is a named group of requests. Collections can contain folders
(nested collections with a parent_id). Requests inside collections are saved
to the Cruss database and synced across all team members in real time.

### Requests
A request has: method (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS), URL, headers,
query params, body (JSON/raw/form-data/urlencoded/GraphQL), auth config,
and a description. Requests inside collections are persisted; scratch tab
requests are session-only.

### Environments
An environment is a named set of key-value variables. Reference them in any
field with {{variableName}} syntax. Switch environments without editing requests.
Example: set baseUrl=https://staging.api.com in Staging env, https://api.com in Prod.

### Organisations
An Organisation groups multiple workspaces under one billing entity. Free orgs
get up to 3 workspaces. Pro orgs ($15/month flat) get unlimited workspaces.
Org admins can invite members, manage branding, and publish to the API Network.

---

## 3. Sending requests

### Basic request
1. Select method from the dropdown (GET is default)
2. Enter URL in the address bar
3. Click Send or press Enter

### Query parameters
Add params in the Params tab as key-value rows. They are appended to the URL
as ?key=value pairs. Use {{variable}} syntax to reference environment values.

### Request headers
Add headers in the Headers tab. Content-Type is automatically set based on
body type selection. Use environment variables for Authorization headers.

### Request body types
- None: no body (default for GET/HEAD)
- JSON: textarea for JSON, Content-Type: application/json injected automatically
- GraphQL: split editor with Query panel and Variables panel
- Form Data: key-value table, sent as multipart/form-data
- URL Encoded: key-value table, sent as application/x-www-form-urlencoded
- Raw: free-text textarea with selectable Content-Type

### Authentication
Auth is configured per-request in the Auth tab:
- Bearer Token: adds Authorization: Bearer <token> header
- Basic Auth: base64-encodes username:password into Authorization header
- API Key: adds key to a header or appends as a query parameter
- No Auth: request sent without authentication headers

Best practice: store tokens in environment variables ({{authToken}}) and
reference them in the auth fields rather than hardcoding.

---

## 4. Collection Runner

The Collection Runner executes all requests in a collection sequentially.

### Running a collection
Right-click any collection in the sidebar → "Run collection" (or use the ▶
inline button). A modal opens showing all requests in order.

### Options
- Select which requests to include (checkboxes)
- Choose active environment
- Set delay between requests (0–5000ms)
- Set number of iterations

### Results
Each request shows: status code, response time, pass/fail for any assertions.
A summary shows total passed/failed at the end.

### Request chaining in the runner
Add extraction rules in the Tests tab of any request:
- Variable name: the env var to write to (e.g. authToken)
- Source: body (JSON dot-path), header, or status
- Path: e.g. data.token for a JSON body, or Authorization for a header

The runner executes extractions after each request and injects the extracted
values into subsequent requests as {{variableName}} interpolation.

Example chain:
1. POST /auth/login → extract data.token → authToken
2. GET /me → headers: Authorization: Bearer {{authToken}}

The runner resolves {{authToken}} to the value extracted in step 1.

---

## 5. Environment variables

### Creating environments
Go to the environment selector (top bar) → "+ New" → name the environment
and add key-value pairs. Environments are per-workspace.

### Using variables
Type {{variableName}} anywhere in URL, headers, params, or body. A live
preview below the URL bar shows the resolved URL as you type.

### Variable autocomplete
Type {{ in the URL bar to open an autocomplete dropdown showing available
variable names from the active environment.

---

## 6. API documentation generation

### Generate docs from a collection
Right-click any collection → "Generate docs". The Gemini 2.0 Flash AI
analyses all requests in the collection and generates:
- Endpoint name and description
- Parameter documentation
- Request body documentation
- Example responses

### Publishing
After generation, toggle "Publish" to make the docs public. A shareable URL
is created at https://cruss.io/docs/<slug>. Share it with API consumers.

### Manual editing
Any field in the generated docs can be edited inline. Descriptions support
Markdown. Changes are saved automatically.

### Per-request descriptions
Add descriptions to individual requests in the Docs tab of the request builder.
These are used as the endpoint description in generated documentation.

---

## 7. Local API testing

### The problem
When using the web app from https://cruss.io, the browser blocks
HTTPS → HTTP requests (mixed-content) and CORS errors occur for APIs
that do not allow the cruss.io origin.

### Solution 1: VS Code extension (recommended)
Install the Cruss VS Code extension (Cruss-code.cruss). The extension
makes requests from Node.js directly, bypassing all CORS and mixed-content
restrictions. No account required for local-only use.

### Solution 2: Cruss Agent
Run: npx cruss-agent
This starts a local proxy at http://localhost:9119. The web app detects it
automatically and routes all requests through the agent, which forwards them
from Node.js without CORS restrictions.

### Solution 3: Direct mode
In the request builder, switch the mode selector to "Direct". The browser
will make the request directly. This works for APIs that allow your origin
or for local development (HTTP→HTTP is allowed on localhost).

---

## 8. VS Code extension

### Installation
Search "Cruss" in the VS Code Extensions marketplace, or:
code --install-extension Cruss-code.cruss

### Features
- Full request builder panel (method, URL, headers, body, auth, params)
- Collections tree showing your saved requests
- Local mode (no account required) — requests stored in VS Code globalState
- Connected mode (account required) — syncs with your Cruss workspaces
- All requests made directly via Node.js fetch (no CORS, no proxy)
- Response history with expandable entries
- Save state indicator (dirty/saved) with Cmd+S shortcut
- Environment variable support in connected mode
- Org context strip in workspace selector showing Free/Pro badge

### Local mode (no account)
Create collections and requests without signing in. Data is stored locally
in VS Code's globalState. Right-click collections for: New Request, Import
from cURL, Export as Postman JSON, Rename, Delete. Right-click requests for:
Duplicate, Move to Collection, Rename, Delete.

### Connecting an account
Click the workspace selector → Connect Account. A browser window opens to
https://cruss.io/vscode. Sign in and copy the token back to VS Code.
After connecting, your workspaces load automatically.

---

## 9. Worker API reference

Base URL: https://api.cruss.io
All authenticated endpoints require: Authorization: Bearer <JWT>

### Authentication
Obtain a JWT from Supabase Auth (email OTP or OAuth), then include it as:
Authorization: Bearer eyJ...

### Workspaces
GET  /workspaces
  Returns: { data: [{ workspace: { id, name, slug }, role }] }

### Collections
GET  /collections/workspace/:workspaceId
  Returns: { data: [{ id, name, parent_id, sort_order, requests: [...] }] }

POST /collections/workspace/:workspaceId
  Body: { name: string, parent_id?: string }
  Returns: { data: { id, name, ... } }

PATCH /collections/:id
  Body: { name?: string }

DELETE /collections/:id

### Requests
GET  /requests/:id
POST /requests/collection/:collectionId
  Body: { name, method, url, headers?, params?, body?, body_type?, auth?, description? }

PATCH /requests/:id
  Body: any subset of request fields

DELETE /requests/:id

POST /requests/:id/duplicate
  Duplicates a request within its collection.

### Proxy
POST /proxy
  Body: { method, url, headers, body?, timeout_ms? }
  Auth: required
  Returns: { data: { status, statusText, headers, body, responseTime, size } }
  Note: not needed in VS Code extension (uses direct Node.js fetch)

### Environments
GET  /environments/workspace/:workspaceId
POST /environments/workspace/:workspaceId
  Body: { name, variables: { key: value } }

### Documentation
GET  /docs/public
  Returns all published doc pages: [{ slug, title, updated_at }]

GET  /docs/:slug
  Returns full doc content for a published page (no auth required)

POST /docs/workspace/:workspaceId/generate
  Auth: required. Triggers AI generation for a collection.
  Body: { collection_id: string }

### History
GET  /history
  Returns last 100 requests for authenticated user

DELETE /history
  Clears all history for authenticated user

### Organisations
GET  /organizations
  Returns orgs for authenticated user: { data: [{ id, name, slug, plan, role }] }

GET  /organizations/:id/workspaces
  Returns workspaces in an org

POST /organizations
  Body: { name: string }

---

## 10. Import formats

### cURL import
Paste any curl command in the sidebar → right-click collection → "Import from cURL".
Supported flags: -X (method), -H (headers), -d / --data / --data-raw (body),
URL (first https?:// token). Body presence without explicit -X implies POST.

### Postman Collection v2.1 import
Right-click collection → "Import from Postman". Paste the JSON content of
a Postman Collection v2.1 export. All requests, headers, and auth configs
are imported. Folders become nested collections.

### OpenAPI / Swagger import
Paste an OpenAPI 3.x or Swagger 2.0 spec (JSON or YAML). All endpoints
become requests with auto-populated paths, methods, and parameter docs.

---

## 11. Export

### Export as Postman JSON
Right-click any local collection → "Export as Postman JSON". Saves a
Postman Collection v2.1 .json file that imports cleanly into Postman,
Insomnia, or other compatible tools.

### Copy as cURL
Right-click any request → "Copy as cURL". Generates a complete curl command
with all headers, method, and body included.

---

## 12. Self-hosting

Cruss is MIT licensed. Three services required:
1. Frontend: deploy frontend/ to Vercel (free tier sufficient)
2. Worker: deploy worker/ to Cloudflare Workers (free tier sufficient)
3. Database: create a Supabase project, run supabase/schema.sql

Required environment variables:
- NEXT_PUBLIC_SUPABASE_URL
- NEXT_PUBLIC_SUPABASE_ANON_KEY
- NEXT_PUBLIC_WORKER_URL (your Worker URL)
- NEXT_PUBLIC_SITE_URL (your frontend URL)

Worker secrets (set via wrangler secret put):
- SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY
- GEMINI_API_KEY (for AI doc generation)
- RESEND_API_KEY (for transactional email)
- STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET (for Organisations Pro)

---

## 13. Pricing

| Feature                  | Free  | Organisations Pro ($15/mo) |
|--------------------------|-------|---------------------------|
| Workspace members        | ∞     | ∞                         |
| Workspaces               | ∞     | ∞                         |
| Collections & requests   | ∞     | ∞                         |
| Collection Runner        | ✓     | ✓                         |
| API doc generation (AI)  | 10/day| unlimited                 |
| Org workspaces           | up to 3 | unlimited               |
| Custom org branding      | ✗     | ✓                         |
| Public API Network page  | ✗     | ✓                         |
| Priority support         | ✗     | ✓                         |

---

Source: https://cruss.io | Last updated: 2026-05-25