REST API Endpoints Reference

Auth: Bearer token (user)

Register a new OAuth2 client. The client secret is only shown once in the response.

POST /api/v1/oauth2/clients
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "clientName": "My App",                    // required, 3-255 chars
  "redirectUris": ["myapp://auth/callback"], // redirect URIs
  "requestedScopes": ["api:access", "profile:read"],
  "requireConsent": true,                    // default: true
  "accessTokenTtlSeconds": 3600,             // default: 3600
  "refreshTokenTtlSeconds": 2592000          // default: 30 days
}

// Response 201:
{
  "success": true,
  "data": {
    "id": 1,
    "clientId": "abc123",
    "clientSecret": "secret_shown_once",
    "clientName": "My App",
    "clientType": "PUBLIC",
    "redirectUris": ["myapp://auth/callback"],
    "scopes": ["api:access", "profile:read"],
    "accessTokenTtlSeconds": 3600,
    "requirePkce": true,
    "requireConsent": true,
    "isActive": true,
    "createdAt": "2024-01-15T10:00:00",
    "updatedAt": "2024-01-15T10:00:00"
  }
}

Auth: Bearer token (user)

List all OAuth2 clients owned by the current user.

GET /api/v1/oauth2/clients
Authorization: Bearer ACCESS_TOKEN

// Response: { "success": true, "data": [OAuth2ClientDto, ...] }

Auth: Bearer token (owner)

Get details of a specific client. Only accessible by the owner.

Auth: Bearer token (owner)

Update an OAuth2 client. Same body as POST.

Auth: Bearer token (owner)

Delete a client and all its associated authorizations.

Auth: Bearer token (owner)

Soft-delete (deactivate) a client without removing data.

Auth: Bearer token (owner)

Get usage stats for a client. Defaults to last 30 days.

GET /api/v1/oauth2/clients/{clientId}/usage?startDate=2024-01-01&endDate=2024-01-31
Authorization: Bearer ACCESS_TOKEN

// Query params (optional): startDate, endDate (ISO date format)

Auth: Bearer token (user)

List all apps the current user has authorized.

Auth: Bearer token (user)

Revoke access for a specific app. Deletes consent and invalidates tokens.

Auth: Bearer token (user)

Get count of authorized apps.

GET /api/v1/oauth2/consents/count
Authorization: Bearer ACCESS_TOKEN

// Response: { "success": true, "data": 3 }

Auth: Bearer token (user)

Create a Stripe checkout session to add funds.

POST /api/v1/payment/create-checkout-session
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "amount": 10.00   // required, minimum $0.50
}

// Response:
{
  "success": true,
  "data": {
    "sessionId": "cs_live_abc123",
    "checkoutUrl": "https://checkout.stripe.com/..."
  }
}

Auth: Bearer token (user)

Verify and capture payment after Stripe redirect.

POST /api/v1/payment/verify-and-capture?session_id=cs_live_abc123
Authorization: Bearer ACCESS_TOKEN

Auth: Bearer token (user)

Redeem a gift card to add funds to your balance.

POST /api/v1/giftcard/redeem
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "code": "GIFT-XXXX-XXXX"   // required
}

// Response:
{
  "success": true,
  "data": {
    "success": true,
    "message": "Gift card redeemed successfully",
    "amountAdded": 5.00,
    "newBalance": 15.00
  }
}

Auth: Bearer token (user)

Set your space handle (username).

PUT /api/v1/spaces/handle
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "handle": "my-space"   // 3-40 chars, pattern: ^[a-z0-9][a-z0-9_-]{1,38}[a-z0-9]$
}

Auth: Public

Check if a handle is available.

GET /api/v1/spaces/handle/check?handle=my-space

// Response: { "success": true, "data": { "available": true } }

Auth: Public

Get a space profile with published apps. Returns profile info, apps list, and isOwner flag.

Auth: Bearer token (user)

Get all space apps for the current user (including unpublished).

Auth: Bearer token (user)

Generate a new AI app from a prompt.

POST /api/v1/spaces/generate
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "prompt": "Create a color palette generator tool",  // 10-2000 chars
  "models": ["gpt-4o-mini"]                           // optional
}

Auth: Bearer token (owner)

Edit an existing space app with a new prompt.

PUT /api/v1/spaces/{slug}/edit
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "prompt": "Add dark mode support"   // 5-2000 chars
}

Auth: Bearer token (owner)

Delete a space app by slug.

Auth: Bearer token (user)

Create a new app.

POST /api/v1/apps
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "slug": "my-cool-app",           // optional, pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
  "name": "My Cool App",           // required, max 200
  "shortDescription": "A brief description",  // required, max 300
  "longDescription": "...",         // max 5000
  "category": "productivity",      // max 50
  "tags": ["ai", "tools"],
  "features": ["Feature 1"],
  "iconUrl": "https://...",
  "appType": "HTML",               // required: HTML or EXTERNAL
  "htmlContent": "<div>...</div>",  // for HTML apps
  "externalUrl": "https://..."      // for EXTERNAL apps
}

Auth: Bearer token (user)

Get all apps owned by the current user.

Auth: Bearer token (owner or admin)

Update an app. All fields are optional — only send fields to change.

Auth: Bearer token (owner or admin)

Delete an app by slug.

Auth: Bearer token (owner or admin)

Publish an app (makes it visible in the catalog).

Auth: Bearer token (owner or admin)

Unpublish an app (removes from catalog but keeps data).

Auth: Bearer token (owner or admin)

Unlist an app (accessible by direct link only).

Auth: Bearer token (user)

Upload an app icon image.

POST /api/v1/apps/upload-icon
Authorization: Bearer ACCESS_TOKEN
Content-Type: multipart/form-data

// Form field: "file" (image file)

// Response: { "success": true, "data": { "url": "https://..." } }