API Testing

Test authenticated requests against the local Rudel API (http://localhost:4010).

Prerequisites

1. The API server must be running locally on port 4010
2. A .env file at the project root with test credentials:

API_TESTING_USER=user@example.com
API_TESTING_PASSWORD=yourpassword
API_TESTING_ORG=<organization-id>

The user must already exist in the database (created via the web UI or sign-up endpoint).

Authentication

The API uses better-auth with cookie-based sessions. Sign in once, save the cookie, and reuse it for all subsequent requests.

Step 1: Sign in and save the session cookie

mkdir -p .context && source .env && curl -s -c .context/cookies.txt \
  -X POST http://localhost:4010/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"$API_TESTING_USER\", \"password\": \"$API_TESTING_PASSWORD\"}"

This saves the better-auth.session_token cookie to .context/cookies.txt (gitignored).

Step 2: Set the active organization

The set-active endpoint requires an Origin header.

source .env && curl -s -b .context/cookies.txt -c .context/cookies.txt \
  -X POST http://localhost:4010/api/auth/organization/set-active \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost:4010" \
  -d "{\"organizationId\": \"$API_TESTING_ORG\"}"

This sets the org context for all subsequent analytics calls. Use both -b and -c since this updates the session cookie.

Step 3: Verify the session works

curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/me \
  -H "Content-Type: application/json" \
  -d "{}" | jq

Expected: JSON with id, email, name, activeOrganizationId matching your API_TESTING_ORG.

Contracts and Schemas

All endpoint contracts and Zod schemas live in packages/api-routes/src/:

• packages/api-routes/src/index.ts — The full RPC contract. Defines every endpoint with its input/output schemas. Read this to see all available methods and their exact types.
• packages/api-routes/src/schemas/analytics.ts — All analytics input/output Zod schemas (DaysInputSchema, OverviewKPIsSchema, SessionListInputSchema, etc.). Read this to see exact field names, types, and defaults for any analytics endpoint.
• packages/api-routes/src/schemas/source.ts — Ingest-related schemas (IngestSessionInput, etc.).

To find the exact payload for any endpoint, read the contract in index.ts to find which schema it uses, then read that schema definition in schemas/.

Making RPC Calls

The API uses oRPC. All RPC endpoints use POST /rpc/<method> with JSON body.

Important: Endpoints that take input require the body wrapped in {"json": {...}}. Endpoints without input accept {}.

Pattern

# No input (e.g., me, listMyOrganizations)
curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/<method> \
  -H "Content-Type: application/json" \
  -d '{}' | jq

# With input — wrap in {"json": {...}}
curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/<method> \
  -H "Content-Type: application/json" \
  -d '{"json": {"days": 30}}' | jq

Responses are also wrapped: {"json": {...}}. Extract data with jq '.json'.

Available Endpoints

Auth-only endpoints (require session, no org context):

Org-scoped analytics endpoints (require session + active organization):

Examples

# List organizations (no input)
curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/listMyOrganizations \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.json'

# Get overview KPIs for last 30 days (input wrapped in json)
curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/analytics/overview/kpis \
  -H "Content-Type: application/json" \
  -d '{"json": {"days": 30}}' | jq '.json'

# Get usage trend for last 7 days
curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/analytics/overview/usageTrend \
  -H "Content-Type: application/json" \
  -d '{"json": {"days": 7}}' | jq '.json'

# Get session count for an org
source .env && curl -s -b .context/cookies.txt \
  -X POST http://localhost:4010/rpc/getOrganizationSessionCount \
  -H "Content-Type: application/json" \
  -d "{\"json\": {\"organizationId\": \"$API_TESTING_ORG\"}}" | jq '.json'

Switching Active Organization

To switch to a different org than API_TESTING_ORG mid-session:

curl -s -b .context/cookies.txt -c .context/cookies.txt \
  -X POST http://localhost:4010/api/auth/organization/set-active \
  -H "Content-Type: application/json" \
  -H "Origin: http://localhost:4010" \
  -d '{"organizationId": "<other-org-id>"}'

Bearer Token Alternative

Instead of cookies, you can extract a bearer token and use Authorization headers (this is what the CLI does):

# Extract token from session
TOKEN=$(curl -s -b .context/cookies.txt http://localhost:4010/api/cli-token | jq -r '.token')

# Use bearer token
curl -s -X POST http://localhost:4010/rpc/me \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{}" | jq '.json'

API Server Logs

If you set RUDEL_LOG_DIR (for example, in .env), the API writes logs to a daily file in that directory, resolved from the project root. With RUDEL_LOG_DIR=.context, logs are at:

.context/api-logs-YYYY-MM-DD.txt

For today's date, read .context/api-logs-$(date +%Y-%m-%d).txt. The log file contains all API debug-level output (requests, errors, ClickHouse queries, etc.).

When debugging errors: After a failing request, read the tail of the log file to see the server-side error, stack trace, or query details. This is especially useful for 500 errors where the curl response is generic.

Troubleshooting

• 401 Unauthorized: Cookie expired or missing. Re-run the sign-in step.
• Input validation failed / BAD_REQUEST: Check that input is wrapped in {"json": {...}}. Endpoints with parameters require this wrapper.
• MISSING_OR_NULL_ORIGIN on auth endpoints: Add -H "Origin: http://localhost:4010" to better-auth API calls (/api/auth/*).
• BAD_REQUEST on analytics endpoints: No active organization set. Run step 2 to set the active org.
• Connection refused: API server not running. Start it with bun run dev:local or bun run --cwd apps/api dev.
• Unexpected 500 or unclear error: Read the API log file at .context/api-logs-$(date +%Y-%m-%d).txt for the server-side stack trace.

Best Practices

1. Always sign in first before making RPC calls. Check if .context/cookies.txt exists and is recent; if not, re-authenticate.
2. Use jq '.json' to unwrap oRPC responses.
3. Use -s (silent) with curl to suppress progress bars.
4. Check me first after sign-in to verify the session is valid and see the user's activeOrganizationId.
5. Never log credentials in command output. Use source .env to load them into the shell environment.