API surface

The local API is HTTP, served at http://127.0.0.1:8000 by default. Every mutating endpoint requires a same-site rewind_session cookie, which the server sets on the first GET request from an allowed origin.

Routes are versioned under /api/v1 and /api/v2. v2 supersedes v1 in the few places where both exist; the request area uses v2 for sending, and history uses v2 for the v2-style body payload. When the table says "v1", that's the only version.

The endpoint groups below match the modules/ folders in apps/api/src/modules/. Each module is a thin Elysia sub-app that delegates to a domain service in apps/api/src/core/<domain>/; the composition root in app.ts is the only place that wires them together. See Architecture → Backend modules for the file map.

For concept-level explanations of each resource, see Workspace overview (regions of the UI), Collections and folders, Request settings (network options), Environments, Viewing and filtering history, Importing OpenAPI, Restoring a backup, and Running a collection.

Health (modules/health)

Method	Path	Notes
GET	/health	Returns { status: "ok", service: "rewind-api-studio", timestamp }. Useful as a liveness check.

Workspace summary (modules/workspace)

Method	Path	Notes
GET	/api/v1/workspace	Returns collections, environments, and the 50 most recent history entries. Used by the sidebar on boot.

Collections & folders (modules/collection)

Method	Path	Notes
GET	/api/v1/collections	List every collection.
POST	/api/v1/collections	Create a collection. Body: { name, description? }.
GET	/api/v1/collections/:id	Get one collection, including its folders and requests.
PUT	/api/v1/collections/:id	Update name/description.
DELETE	/api/v1/collections/:id	Delete and cascade.
POST	/api/v1/collections/:id/duplicate	Create a copy of the collection.
POST	/api/v1/collections/:id/folders	Create a folder. Body: { name, parentId? }.
PATCH	/api/v1/folders/:id	Rename or move a folder.
DELETE	/api/v1/folders/:id	Delete the folder. Requests inside are moved to the folder's parent.
PATCH	/api/v1/workspace/tree	Bulk-mutate folder/request ordering and parent. Body shape: { collectionId, items: [{ type, id, parentFolderId, sortOrder }] }. Lives on the collection module but stays under /workspace for backward compatibility.

Requests (modules/request)

Method	Path	Notes
POST	/api/v1/collections/:id/requests	Create a saved request inside a collection. Body: full request draft.
GET	/api/v1/requests/:id	Get a saved request.
PUT	/api/v1/requests/:id	Update. Body must include expectedRevision to detect conflicts.
DELETE	/api/v1/requests/:id	Delete.
POST	/api/v1/requests/:id/duplicate	Create a copy.

The actual send and runner endpoints live on the execution module; they're listed below under that heading.

Execution (modules/execution)

Method	Path	Notes
POST	/api/v1/requests/send	Send a draft. Body: { requestId?, draft, executionId? }. Returns the v1 SendResult shape.
POST	/api/v2/requests/send	Send a draft. Same input, returns the v2 response shape with the response body wrapped in a body: { kind, contentType, bodyUrl, ... } envelope.
DELETE	/api/v1/executions/:id	Cancel an in-flight request.
POST	/api/v1/runner	Run every request in a collection. Body: { collectionId, environmentId?, stopOnFailure? }. Returns the same shape the UI dialog shows.

Concept overview: Running a collection.

Environments (modules/environment)

Method	Path	Notes
GET	/api/v1/environments	List every environment.
POST	/api/v1/environments	Create. Body: { name, isActive?, variables? }.
PUT	/api/v1/environments/:id	Update.
DELETE	/api/v1/environments/:id	Delete.

History (modules/history)

Method	Path	Notes
GET	/api/v1/history	List entries. Supports query, method, outcome, collectionId, from, to, limit, cursor.
DELETE	/api/v1/history	Clear all history.
GET	/api/v1/history/:id	Get one entry, v1 shape.
GET	/api/v2/history/:id	Get one entry, v2 shape (response body in envelope).
GET	/api/v2/history/:id/body	Download the stored response body.
DELETE	/api/v1/history/:id	Delete one entry.

Concept overview: Viewing and filtering and Reopening from history.

Attachments (modules/attachment)

Method	Path	Notes
POST	/api/v1/attachments	Multipart upload. Form field: file. Max size 100 MB.
GET	/api/v1/attachments/:id	Download a stored file.
DELETE	/api/v1/attachments/:id	Delete.

Cookies (modules/cookie)

Method	Path	Notes
GET	/api/v1/cookies?jarId=default	List cookies in the named jar.
DELETE	/api/v1/cookies?jarId=default	Clear all cookies in the named jar.

Settings (modules/settings)

Method	Path	Notes
GET	/api/v1/settings/network	Get proxy and TLS settings.
PUT	/api/v1/settings/network	Update.
GET	/api/v1/settings/storage	Get the four storage knobs.
PUT	/api/v1/settings/storage	Update.

Import & export (modules/importer)

Method	Path	Notes
POST	/api/v1/import/openapi	Body: { source } — the OpenAPI document as text.
POST	/api/v1/import/postman	Body: { source } — the Postman collection as text.
POST	/api/v1/import/workspace	Body: a WorkspaceExport payload (see Request schema).
GET	/api/v1/export/workspace?includeSecrets=false	Workspace as JSON.
GET	/api/v1/export/postman/:id	Download a single collection as Postman v2.1 JSON.

Archive (modules/archive)

The archive endpoints are v2 because they require the v2 send/response shape on the request side.

Method	Path	Notes
GET	/api/v2/workspace/archive?includeSecrets=&includeResponseBodies=&confirm=	Download a .rewind archive. The two opt-in flags require confirm=true for that flag.
POST	/api/v2/workspace/archive/preview	Multipart upload of a .rewind file. Returns the manifest preview.
POST	/api/v2/workspace/archive/restore?confirmSecrets=&confirmResponseBodies=	Multipart upload of a .rewind file. Restores the workspace.

Concept overview: Exporting and backups and Restoring a backup.

Diagnostics (modules/diagnostic)

Method	Path	Notes
GET	/api/v1/diagnostics/archive	Downloads a .tar.gz with a diagnostic.json and the current log files.

Concept overview: Data and storage → Diagnostic archive.

Error responses

Every error response has the centralized Api.Error shape from apps/api/src/http/response.ts:

{ "error": "<code>", "message": "<human readable>", "details": "<optional extra>" }

The error value is one of the codes in the ApiErrorCode union:

• validation_error — request body failed Elysia validation. details is the Elysia validation report.
• request_validation_error — request draft is invalid (e.g. unresolved variables, bad URL). details is an object with the specific cause.
• not_found — the resource doesn't exist.
• forbidden — the request crossed the origin allowlist or the same-site session check.
• conflict — save revision mismatch. details.current is the current stored state.
• internal_error — anything else; the message is the underlying error message.

Status codes

The API uses these status codes consistently:

• 200 for successful reads and updates
• 201 for successful creates
• 400 for validation errors
• 403 for origin or session errors
• 404 for missing resources
• 409 for revision conflicts
• 500 for anything else

What's next?

• Request schema — the shape of the bodies
• Environment variables — the REWIND_DATA_DIR, SQLITE_PATH, HOST, PORT knobs
• Architecture — the higher-level data flow