---

name: restspace-api description: Interact with Restspace Runtime servers. Use when you need to make HTTP requests to a Restspace instance for data, files, or other operations. Always discover services first via /.well-known/restspace/services. allowed-tools: Bash, Read

Restspace Runtime API

Interact with a running Restspace Runtime instance via HTTP.

Key Concept: Dynamic Service Discovery

Restspace has no fixed URLs except for the discovery endpoint. Services are mounted at configurable paths, so you must always discover services first before performing operations.

Configuration

Workflow

Step 1: Discover Available Services (ALWAYS DO THIS FIRST)

IMPORTANT: Always use $RESTSPACE_URL directly. Do NOT use intermediate variable assignments like BASE_URL=... as they can cause shell expansion issues on Windows.

Copy# Get raw JSON (recommended - avoids jq piping issues)
curl -s "$RESTSPACE_URL/.well-known/restspace/services"

# Optional: pretty print with jq if needed
curl -s "$RESTSPACE_URL/.well-known/restspace/services" | jq '.'

If RESTSPACE_URL is not set, it defaults to http://localhost:3100.

Response shows services with their paths and types:

Copy{
  "/api/users": {
    "name": "User Data",
    "source": "./services/data.rsm.json",
    "apis": ["store"]
  },
  "/files": {
    "name": "File Storage",
    "source": "./services/file.rsm.json",
    "apis": ["store"]
  },
  "/auth": {
    "name": "Authentication",
    "source": "./services/auth.rsm.json",
    "apis": ["auth"]
  }
}

Step 2: Find Services by Type

Copy# Find data services
curl -s "$RESTSPACE_URL/.well-known/restspace/services" | \
  jq 'to_entries | map(select(.value.source | contains("data.rsm"))) | .[] | {path: .key, name: .value.name}'

# Find file services
curl -s "$RESTSPACE_URL/.well-known/restspace/services" | \
  jq 'to_entries | map(select(.value.source | contains("file.rsm"))) | .[] | {path: .key, name: .value.name}'

# Find auth service
curl -s "$RESTSPACE_URL/.well-known/restspace/services" | \
  jq 'to_entries | map(select(.value.source | contains("auth.rsm"))) | .[] | {path: .key, name: .value.name}'

Step 3: Handle Multiple Services

If multiple services of the same type exist (e.g., multiple data services), present them to the user and ask which to use.

If the user specifies a URL path in their prompt, use that path directly.

Step 4: Authenticate

See AUTH.md for authentication patterns.

Step 5: Perform Operations

Use the discovered service path for all operations. See:

• AUTH.md - Authentication (login, logout, sessions)
• DATA.md - Data CRUD operations
• FILES.md - File operations
• PIPELINES.md - Pipelines and transforms (compose services)

Service Type Patterns

Common Response Codes

Security Notes

• Never echo or log $RESTSPACE_EMAIL or $RESTSPACE_PASSWORD
• Use -s (silent) flag to suppress curl output
• Keep cookies.txt in a secure, non-committed location