API Reference — SaaSClaw

Overview #

SaaSClaw exposes a REST API at /api/v1/ for programmatic access. All endpoints return JSON and require authentication.

Base URL: https://saasclaw.ai/api/v1/

Authentication #

Two authentication methods are supported depending on your use case:

JWT (for user-facing apps)

Login: POST /auth/token/ with {"email": "...", "password": "***"} → returns {"access", "refresh", "email"}
Send Authorization: Bearer <access> on every request
Access tokens expire (5 min). On 401, refresh via POST /auth/token/refresh/ with {"refresh": "..."}

Signed in with Google or GitHub? You don't have a password. Use the session exchange endpoint instead:

curl -X POST https://saasclaw.ai/api/v1/auth/exchange-session-token/ \
  -H "Cookie: sessionid=..."  # or use the browser cookie

Or just visit Account → SaaSClaw API Keys in the dashboard to create keys with one click — no terminal needed.

API Keys (for server-to-server / SDK)

Create a key: POST /admin/keys/ with JWT auth → returns {"key": "sk_..."} (shown once)
Send the key as either Authorization: Bearer *** or X-API-Key: ***
Keys don't expire. Revoke via POST /admin/keys/<id>/revoke/
Key management endpoints require JWT (not API key) to prevent privilege escalation

Security note: API keys are long-lived credentials. Store them securely (environment variables, secret managers) and never expose them in client-side code.

Java SDK #

Spring Boot Starter for the SaaSClaw API. Provides auto-configured client beans, automatic token refresh, and type-safe DTOs.

Maven

pom.xml

<dependency>
  <groupId>com.saasclaw</groupId>
  <artifactId>saasclaw-spring-boot-starter</artifactId>
  <version>0.1.0-SNAPSHOT</version>
</dependency>

Gradle

build.gradle

implementation 'com.saasclaw:saasclaw-spring-boot-starter:0.1.0-SNAPSHOT'

Configuration

application.yml

saasclaw:
  base-url: https://saasclaw.ai
  # Option 1: API key (recommended for servers)
  api-key: sk_...
  # Option 2: Email/password (auto-login + refresh)
  email: [email protected]
  password: secret

Quick start

Java

@Autowired
private SaaSClawClient client;

// List projects
List<ProjectDto> projects = client.listProjects();

// Create a project
client.createProject(new ProjectCreateRequest("My App", "desc", "spring-boot"));

// Deploy
DeployStatus status = client.deploy("my-app");

// Send agent message
MessageDto msg = client.sendMessage("my-app", sessionId, "Add a login page");

GitHub: github.com/saasclawai-org/saasclaw-java-sdk

Projects #

Manage projects — list, create, check status, and inspect infrastructure.

Method	Path	Description
GET	`/projects/`	List all projects
POST	`/projects/`	Create a project
GET	`/projects/{slug}/`	Get project details
GET	`/projects/{slug}/status/`	Infrastructure status

Sessions #

Interactive agent sessions within a project. Send messages to the AI wizard and receive responses.

Method	Path	Description
GET	`/projects/{slug}/sessions/`	List sessions
POST	`/projects/{slug}/sessions/`	Create session
GET	`/projects/{slug}/sessions/{id}/`	Get session
POST	`/projects/{slug}/sessions/{id}/send/`	Send message to agent

Files #

Read and write files within a project workspace. All paths are validated to stay within the project root.

Method	Path	Description
GET	`/projects/{slug}/files/`	List files (tree)
GET	`/projects/{slug}/files/{path}`	Read file
POST	`/projects/{slug}/files/{path}`	Write file

Environment Variables #

Manage environment variables for deployed projects. These are injected into the project's runtime environment on deploy.

Method	Path	Description
GET	`/projects/{slug}/env/`	List env vars
POST	`/projects/{slug}/env/`	Set env var
DELETE	`/projects/{slug}/env/{key}/`	Delete env var

Deploy #

Trigger and monitor deployments. Each deploy creates a new commit and provisions the project at the preview or production URL.

Method	Path	Description
POST	`/projects/{slug}/deploy/`	Trigger deploy
GET	`/projects/{slug}/deploy/status/`	Deploy status
GET	`/projects/{slug}/deploy/history/`	Deploy history

Git #

Inspect and commit changes to the project's Git repository without leaving the API.

Method	Path	Description
GET	`/projects/{slug}/git/status/`	Git status
GET	`/projects/{slug}/git/diff/`	Git diff
POST	`/projects/{slug}/git/commit/`	Commit changes

Infrastructure #

Inspect the infrastructure state of a deployed project — running services, Nginx config, systemd status, and resource usage.

See also: Technical Documentation for the full SaaSClaw architecture diagram and component breakdown.

Errors #

The API uses standard HTTP status codes. Error responses include a detail field with a human-readable message.

Status	Meaning
400	Bad request — invalid input
401	Authentication required or token expired
403	Permission denied
404	Project or resource not found
429	Rate limited
500	Server error