Reference

API Documentation

The S8t API lets you manage users, agents, email, and storage programmatically. Base URL: https://api.s8t.ai

Authentication

User endpoints require a JWT obtained via magic link. Pass as Authorization: Bearer <jwt>.

Agent endpoints (email send, storage) use agent bearer tokens (s8t_ag_...).

Ingest endpoint uses X-Ingest-Secret header (internal only).

Endpoints

Authentication

GET /auth/verify

Verify a magic link token. Sets a session cookie (web) or redirects to the app with a JWT.

Request
GET /auth/verify?token={uuid}
Response
302 Redirect
Set-Cookie: s8t_session={jwt}; HttpOnly; Secure

// Or if ?app=true:
302 Redirect → openclaw://auth?token={jwt}
POST /auth/refresh

Refresh an expiring JWT. Tokens expire after 7 days.

Request
POST /auth/refresh
Authorization: Bearer {jwt}
Response 200
{
  "token": "eyJhbG..."
}

Users

POST /users

Create a new user and claim a username namespace. Usernames: 3-40 chars, lowercase alphanumeric with hyphens.

Request
POST /users
Content-Type: application/json
Authorization: Bearer {jwt}

{
  "username": "arun",
  "email": "arun@example.com"
}
Response 201
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "arun",
  "email_domain": "arun.s8t.ai"
}
GET /users/:username/available

Check if a username is available for registration.

Request
GET /users/arun/available
Response 200
{
  "username": "arun",
  "available": true
}

Agents

POST /users/:user_id/agents

Create a new agent with email address and Drive folder. Returns a bearer token for API access.

Request
POST /users/550e8400-.../agents
Content-Type: application/json
Authorization: Bearer {jwt}

{
  "name": "claude"
}
Response 201
{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "name": "claude",
  "email": "claude@arun.s8t.ai",
  "agent_token": "s8t_ag_a1b2c3d4e5f6...",
  "drive_folder": "/S8t/claude/"
}

Storage Connection

GET /auth/google/connect

Initiate Google OAuth to connect Drive. Requests drive.file scope (only app-created files).

Response
302 Redirect → https://accounts.google.com/o/oauth2/v2/auth?...
GET /auth/google/callback

OAuth callback. Exchanges code for tokens, creates /S8t/ folder structure, stores encrypted refresh token.

Response
302 Redirect → /dashboard (success)
302 Redirect → /dashboard?error=drive_failed (failure)

Email

POST /email/ingest

Ingest inbound email from Cloudflare Email Worker.

Internal — requires X-Ingest-Secret header

Request
POST /email/ingest
Content-Type: message/rfc822
X-Envelope-To: claude@arun.s8t.ai
X-Envelope-From: sender@example.com
X-Ingest-Secret: {secret}

{raw RFC822 email bytes}
Responses
200 OK          — Queued for processing
401 Unauthorized — Bad or missing secret
404 Not Found    — Unknown agent or user
POST /email/send

Send email from an agent's address via Amazon SES.

Requires agent bearer token

Request
POST /email/send
Content-Type: application/json
Authorization: Bearer s8t_ag_a1b2c3d4...

{
  "to": "human@example.com",
  "subject": "Hello from Claude",
  "body": "Plain text body",
  "html": "<p>HTML body</p>"
}
Response 200
{
  "message_id": "<uuid@arun.s8t.ai>"
}
Rate limits: Free: 100/hour, Pro: 500/hour per agent

Storage

All storage endpoints require an agent bearer token. Paths are relative to the agent's Drive folder.

GET /storage/files/:path

Read a file from the agent's Drive folder.

Request
GET /storage/files/notes/todo.md
Authorization: Bearer s8t_ag_a1b2c3d4...
Response 200
Content-Type: text/markdown

{file contents}
PUT /storage/files/:path

Write a file to the agent's Drive folder. Creates parent directories if needed.

Request
PUT /storage/files/notes/todo.md
Content-Type: text/markdown
Authorization: Bearer s8t_ag_a1b2c3d4...

{file contents}
Response 200
{
  "ok": true,
  "drive_file_id": "1a2b3c4d..."
}
GET /storage/files/:path?list

List files and folders in a directory.

Request
GET /storage/files/notes/?list
Authorization: Bearer s8t_ag_a1b2c3d4...
Response 200
{
  "files": [
    {
      "name": "todo.md",
      "size": 1234,
      "modified": "2026-02-11T10:30:00Z",
      "type": "file"
    },
    {
      "name": "drafts",
      "type": "folder"
    }
  ]
}
DELETE /storage/files/:path

Delete a file from the agent's Drive folder.

Request
DELETE /storage/files/notes/todo.md
Authorization: Bearer s8t_ag_a1b2c3d4...
Response 200
{
  "ok": true
}

Error Responses

{
  "error": "not_found",
  "message": "Agent not found"
}
400 Bad request — invalid parameters
401 Unauthorized — missing or invalid token
403 Forbidden — insufficient permissions
404 Not found — resource doesn't exist
409 Conflict — username already taken
429 Rate limited — too many requests