API and CLI for developers (Rigsfactory OpenAPI & CLI, Rigsplan API)

Tekspaz exposes programmatic APIs and command-line interfaces (CLIs) so developers can trigger architecture planning, execute builds, inspect gate states, and automate workflows from CI/CD pipelines or local terminal environments.

This guide covers:

1. The Rigsfactory CLI (pnpm rigs)
2. The CodeFactory CLI (pnpm cf)
3. Rigsfactory OpenAPI Reference & cURL examples
4. Rigsplan API Reference

---

1. Setting up your environment

All developer CLI commands read their credentials and endpoints from environment variables or a .env file in your project root:

# Rigsfactory Orchestrator endpoint and secret key
RIGSFACTORY_URL="https://teks1platform.tekspaz.ai"
RIGSFACTORY_API_KEY="tkrf_live_sec_abcdef1234567890"

# CodeFactory execution backend
CODEFACTORY_URL="https://teksbuild.tekspaz.ai"
CODEFACTORY_API_KEY="tkcf_live_sec_9876543210fedcba"

# Optional database URL for local lifecycle check scripts
DATABASE_URL="postgresql://user:pass@localhost:5432/tekspaz"

Verify your local environment is configured:

node -e "console.log(process.env.RIGSFACTORY_URL ? 'Configured' : 'Missing env vars')"

---

2. Rigsfactory CLI (pnpm rigs)

The rigs CLI provides direct interaction with the Rigsfactory lifecycle orchestrator, managing gate decisions and run statuses.

Command Reference

Command	Usage	Description
health	pnpm rigs health [--json]	Checks liveness and lists active gate evaluators. Does not require credentials.
whoami	pnpm rigs whoami	Validates that your RIGSFACTORY_API_KEY passes authentication and role gates.
start	pnpm rigs start "<intent>" [--json]	Initializes a new agent execution run with your intent string. Prints envelope ID.
get	pnpm rigs get <envelope-id> [--json]	Fetches the current envelope, stage, status, and error logs of a run.
gate	pnpm rigs gate <id> <stage> <action> [reason]	Submits a human decision (approve, deny, edit, abort) for a pending gate.
check	pnpm rigs check "<intent>"	Executes an end-to-end automated sanity check: health → start → intent gate → delivery.

Tested Command Examples

1. Check Service Health

pnpm rigs health

Output:

rigsfactory-service 1.4.0: ok · up 142850s · https://teks1platform.tekspaz.ai
Gates: AuthGate(active), TenancyGate(active), PolicyGate(active)

2. Verify Authentication Credentials

pnpm rigs whoami

Output:

Authenticated · the gates passed and the probe envelope was not found (404 invalid_request)

3. Start a Run

pnpm rigs start "Build a Stripe webhook receiver in TypeScript that logs charge events to SQLite"

Output:

Started: {"envelope_id":"env_98f4b1a2","status":"drafting","stage":"intent"}

4. Approve a Gate Stage

pnpm rigs gate env_98f4b1a2 intent approve "Architecture verified by engineering lead"

Output:

Decided: {"envelope_id":"env_98f4b1a2","stage":"intent","decision":"approve","status":"running"}

5. Output Raw JSON

Add --json to any command for shell piping and CI automation:

pnpm rigs get env_98f4b1a2 --json | jq .stage

---

3. CodeFactory CLI (pnpm cf)

The cf CLI interacts with the CodeFactory build, evaluation, and background cron systems.

Command Reference

Command	Usage	Description
health	pnpm cf health [--json]	Evaluates CodeFactory backend health, CPU, memory, and LLM providers.
status	pnpm cf status	Checks the factory execution loop status, queue length, and last error.
workflows	pnpm cf workflows	Lists available automated orchestration workflows.
run	pnpm cf run <workflow> "<input>"	Synchronously runs an agent workflow and prints step execution logs.
eval	pnpm cf eval	Displays results and pass rate of the latest automated evaluation suite.
sync	pnpm cf sync	Manually runs the Vercel cron loop (recovers lost runs, sends approval reminders).
capabilities	pnpm cf capabilities	Reports which backend features and fixes (B1–B21) are live.

Tested Command Examples

1. Inspect Backend Health & Providers

pnpm cf health

Output:

CodeFactory: ok · https://teksbuild.tekspaz.ai
CPU 12% · memory 38% of 16 GB · disk 44%
Providers: anthropic-claude-3-5-sonnet*, openai-gpt-4o, google-gemini-1-5-pro

2. Check Factory Queue Status

pnpm cf status

Output:

Factory: running · phase idle · 0 queued

3. Inspect Live Backend Capabilities

pnpm cf capabilities

Output:

✓ webhooks
✓ dynamic_service_keys
✓ streaming_chat
✓ sandbox_previews
✓ multi_org_tenancy

---

4. Rigsfactory OpenAPI Reference

Rigsfactory exposes a complete OpenAPI 3.1 specification at https://teks1platform.tekspaz.ai/openapi.json.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer <YOUR_RIGSFACTORY_API_KEY>

Endpoints

GET /v1/health

Checks API availability and gate readiness.

curl -X GET https://teks1platform.tekspaz.ai/v1/health \
  -H "Accept: application/json"

POST /v1/runs

Initializes a new execution run.

Request:

curl -X POST https://teks1platform.tekspaz.ai/v1/runs \
  -H "Authorization: Bearer $RIGSFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Add a health check endpoint to src/pages/api/health.ts",
    "source": "ci-script",
    "project_id": "proj_94821a0f"
  }'

Response (201 Created):

{
  "id": "run_01jbc458a",
  "envelope_id": "env_98f4b1a2",
  "status": "awaiting_gate",
  "stage": "intent",
  "version": 1,
  "tenant_id": "org_acme_corp"
}

POST /v1/runs/{id}/gate

Submits a decision for a pending human gate.

Request:

curl -X POST https://teks1platform.tekspaz.ai/v1/runs/run_01jbc458a/gate \
  -H "Authorization: Bearer $RIGSFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stage": "intent",
    "decision": "approve",
    "reason": "Automated approval from staging pipeline"
  }'

---

5. Rigsplan API Reference

The Rigsplan API powers autonomous problem statement interrogation and architecture generation.

Endpoint: POST /v1/plan

Submits a requirement to generate a structured Plan Bundle.

curl -X POST https://teks1platform.tekspaz.ai/v1/plan \
  -H "Authorization: Bearer $RIGSFACTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "problem_statement": "Real-time chat widget for customer support with WebSocket gateway",
    "stack_preferences": {
      "framework": "astro",
      "database": "postgresql",
      "language": "typescript"
    }
  }'

Response (200 OK):

{
  "plan_id": "plan_77491",
  "version": 1,
  "status": "ready",
  "bundle": {
    "architecture": "Single-page Astro application communicating over secure WebSockets with a Node.js edge proxy",
    "schemas": ["users", "chat_rooms", "messages"],
    "api_endpoints": [
      { "path": "/api/chat/ws", "method": "GET", "protocol": "websocket" },
      { "path": "/api/chat/history", "method": "GET" }
    ],
    "tasks": [
      { "id": "TASK-1", "title": "Setup PostgreSQL schema for messages", "estimate_hours": 1 },
      { "id": "TASK-2", "title": "Implement WebSocket upgrade handler", "estimate_hours": 2 }
    ]
  }
}

---

What to explore next

• TeksPlan: plan bundles and authorization gates
• TeksBuild: execution loops and previews
• FAQ and troubleshooting