API Keys � FAE

Your Workspace Keys

Each workspace has a unique API key. Use it in the x-api-key request header. Regenerating a key immediately invalidates the previous one.

Keep your API key secret. Never expose it in client-side JavaScript. Use it only from your own server or backend. If compromised, regenerate it immediately.

Overview

Base URL

https://faeframeworks.com/api

Response Format

application/json

Auth Header (API key)

x-api-key: <your-key>

API Status

checking�

All responses are JSON. Arrays are returned directly (not wrapped). Timestamps use ISO 8601. IDs are MongoDB ObjectIds (24-char hex strings).

Authentication

API Key Auth � for external integrations

Pass your workspace API key in the x-api-key header on every request. Keys are generated per workspace from the panel above.

            
# Works on any workspace-scoped endpoint (characters, nfts, apps, stories, bots, media...)
curl https://faeframeworks.com/api/characters?workspace=WORKSPACE_ID \
  -H "x-api-key: YOUR_API_KEY"
          

Dual Auth � workspace-scoped routes

All workspace-scoped CRUD routes (characters, apps, stories, NFTs, bots, media, scenes) accept either method. Use API key from external servers, automation scripts, or embedded tools. Use session cookies when calling from the FAE frontend.

Endpoints labeled accept both an x-api-key header and a session cookie. Endpoints labeled are public-embed routes. Endpoints labeled require a logged-in user (TTS, tokens).

Error Responses

All errors return a JSON object with an error field describing the problem.

Code	Meaning	Common Cause
200 OK	Success	Request completed normally
201 Created	Resource created	POST returned new resource
400 Bad Request	Validation failed	Missing or invalid fields
401 Unauthorized	Not logged in	Session expired or missing
403 Forbidden	Invalid API key or no access	Wrong key, wrong workspace, or insufficient permissions
404 Not Found	Resource missing	Bad ID or deleted resource
500 Server Error	Internal error	Unexpected server-side failure
503 Unavailable	Service offline	Stripe not configured, no AI agents online

NFTs

Fetch public NFTs for a workspace. No user session required � just your workspace ID and API key.

GET /api/public/nfts?workspace={workspaceId} List public NFTs

Returns all NFTs in the workspace where public: true. Pass your API key in the x-api-key header.

Query Parameters

Name	Type	Required	Description
workspace	string	required	Your workspace ID (24-char hex)

Headers

Name	Type	Required	Description
x-api-key	string	required	Your workspace API key

JavaScript

cURL

                
const res = await fetch('/api/public/nfts?workspace=' + WORKSPACE_ID, {
  headers: { 'x-api-key': YOUR_API_KEY }
});
const nfts = await res.json();
// nfts ? Array of NFT objects
              

Payments Embed

Embed a FAE-powered Stripe checkout on any site. Create payment products in your workspace, then use these endpoints to surface them publicly and initiate checkout sessions � no Stripe keys on the client side.

Requires a connected Stripe account. Set up Stripe Connect from your workspace settings before accepting payments.

GET /api/payments/embed/product/{productId} Get product info

Returns public product details for embedding in a checkout widget. Pass your API key as x-api-key header or ?key= query param.

Path Parameters

Name	Type	Required	Description
productId	string	required	The product's ObjectId

JavaScript

cURL

                
const res = await fetch(`/api/payments/embed/product/${PRODUCT_ID}`, {
  headers: { 'x-api-key': YOUR_API_KEY }
});
const product = await res.json();
// { id, name, description, amount, currency, images }
              

POST /api/payments/embed/checkout Create Stripe checkout

Creates a Stripe Checkout session for a product. Returns a url to redirect the customer to. Pass API key in x-api-key header.

Request Body (JSON)

Name	Type	Required	Description
productId	string	required	ID of an active payment product
successUrl	string	required	Redirect URL after successful payment (https)
cancelUrl	string	required	Redirect URL if customer cancels (https)
customerEmail	string	optional	Pre-fill customer email in checkout
ref	string	optional	Custom reference string saved with the order

JavaScript

cURL

                
const res = await fetch('/api/payments/embed/checkout', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': YOUR_API_KEY
  },
  body: JSON.stringify({
    productId:  'PRODUCT_ID',
    successUrl: 'https://yoursite.com/success',
    cancelUrl:  'https://yoursite.com/cancel',
    ref:        'order_42'   // optional reference
  })
});
const { url } = await res.json();
window.location.href = url;  // redirect to Stripe Checkout
              

NFTs

Full CRUD for NFTs (masters, editions, collections). Accepts API key or session auth.

GET/api/nfts?workspace={workspaceId}List NFTs

Query Parameters

Name	Type	Required	Description
workspace	string	optional	Filter by workspace ID
collection	string	optional	Filter by collection ID

POST/api/nftsCreate NFT

Request Body (JSON)

Name	Type	Required	Description
workspace	string	required	Workspace ID
name	string	required	NFT name
nftKind	string	optional	`master`, `edition`, or `collection`
public	boolean	optional	Visible in public API (default: false)
mintCount	number	optional	For edition kind � bulk mint count

PUT/api/nfts/{id}Update NFT

Update any fields on an existing NFT. Send only the fields to change.

DELETE/api/nfts/{id}Delete NFT

Permanently deletes an NFT record. Returns {"success":true}.

Characters

AI Character profiles � traits, prompts, avatar, Ollama model assignment, memory.

GET/api/characters?workspace={workspaceId}List characters

Returns all characters for the workspace. Results are cached server-side (60s) and refreshed in the background � first call may be slower.

POST/api/charactersCreate character

Key Body Fields

Name	Type	Required	Description
workspace	string	required	Workspace ID
name	string	required	Character name
traits	string[]	optional	Personality trait list
background	string	optional	Character backstory
model	string	optional	Ollama model name for AI responses

POST/api/characters/responseGet AI response

Routes a message through the AI relay to an available Electron agent (Ollama). Requires a connected FAE desktop app to be online. Times out after 20s.

Request Body

Name	Type	Required	Description
characterId	string	required	ID of the character to respond
text	string	required	User message
model	string	optional	Override Ollama model

PUT/api/characters/{id}Update character

Update character fields. All fields are optional.

DELETE/api/characters/{id}Delete character

Permanently deletes the character and clears related caches.

Apps

Create and manage hosted web apps. Files are stored on GCS and served via Traefik.

GET/api/apps?workspace={workspaceId}List apps

Returns all apps in the workspace.

GET/api/apps/templatesList templates

Returns all available app starter templates.

POST/api/appsCreate app

Request Body

Name	Type	Required	Description
name	string	required	App name (auto-generates slug)
workspace	string	required	Workspace ID
templateId	string	optional	Starter template ID
githubRepo	string	optional	GitHub repo URL to link
domain	string	optional	Custom domain (default: slug.faeframeworks.com)

GET/api/apps/{id}/filesList app files (GCS)

Returns list of file paths in Google Cloud Storage for this app.

POST/api/apps/{id}/uploadUpload app file

Multipart form upload. Sends a file to GCS under the app's prefix.

Form Fields

Name	Type	Required	Description
file	File	required	The file binary
filename	string	optional	Override destination filename

Stories

Book Studio stories � create, read, update, and delete story documents.

GET/api/stories?workspace={workspaceId}List stories

Returns all stories in the workspace.

GET/api/stories/{id}Get story

Returns a single story by ID.

POST/api/storiesCreate story

Creates a new story. Pass all story fields in the request body.

PUT/api/stories/{id}Update story

Updates the story. Auto-sets updatedAt.

DELETE/api/stories/{id}Delete story

Permanently deletes a story.

Bots

Automation bots with node/edge pipelines, trigger configs, and run logs.

GET/api/bots?workspace={workspaceId}List bots

Returns bots for the workspace (nodes/edges/logs are excluded from list response).

GET/api/bots/{id}Get bot

Returns full bot including pipeline nodes and edges.

POST/api/botsCreate bot

Creates a new bot. Pass name, workspace, and pipeline config in body.

POST/api/bots/{id}/runRun bot

Starts the bot pipeline. Returns immediately with {"status":"running"}; pipeline runs async.

POST/api/bots/{id}/stopStop bot

Sets bot status to idle.

GET/api/bots/{id}/logsGet run logs

Returns {"logs":[...],"status":"idle|running|error"} for the bot.

DELETE/api/bots/{id}/logsClear logs

Clears all run log entries for the bot.

DELETE/api/bots/{id}Delete bot

Permanently deletes the bot and all its data.

Media Files

Workspace file records for images, videos, audio, documents, and 3D models. Files are stored in Google Cloud Storage; these endpoints manage the metadata records.

Replace {type} with one of: images, videos, audios, documents, models.

GET/api/{type}?workspace={workspaceId}List files

Returns all files of the given type in the workspace, sorted newest first.

POST/api/{type}Register file

Creates a file record after you've uploaded the binary to GCS directly. The caller must be a workspace editor.

Request Body

Name	Type	Required	Description
workspace	string	required	Workspace ID
url	string	required	GCS public URL
name	string	optional	Display name
size	number	optional	File size in bytes
mimeType	string	optional	MIME type

PUT/api/{type}/{id}Update file

Update metadata fields for a file record (e.g. rename). Caller must be a workspace editor.

DELETE/api/{type}/{id}Delete file

Deletes the DB record and removes the file from GCS. Returns {"success":true,"freed":<bytes>}.

GET/api/models/{id}/contentProxy-stream GLB

Streams the GLB binary from GCS through the FAE server (bypasses browser CORS restrictions for the 3D viewer).

Text-to-Speech

Kokoro TTS via the AI relay. Requires a connected FAE desktop app with Kokoro loaded.

GET/api/tts/statusPUBLICTTS availability

Returns TTS availability and available voices. No auth required.

                // Response when ready
{ "available": true, "state": "ready", "voices": [
  { "id": "af_heart", "label": "Heart (US Female)" },
  { "id": "af_bella", "label": "Bella (US Female)" },
  // ... 6 more voices
]}
              

POST/api/ttsGenerate speech

Returns audio/wav binary. Routed through AI relay to Electron. Persists a TTSJob record.

Request Body

Name	Type	Required	Description
text	string	required	Text to synthesize (max 2000 chars)
voice	string	optional	Voice ID (default: `af_heart`)
speed	number	optional	Speed multiplier 0.5�2.0 (default: 1.0)
workspaceId	string	optional	Associates job with a workspace

Scenes

3D scene definitions for the Scene Builder.

GET/api/scenes?workspace={workspaceId}List scenes

Returns all scenes for the workspace.

POST/api/scenesCreate scene

Creates a new scene. Pass scene definition fields in the body.

PUT/api/scenes/{id}Update scene

Updates an existing scene record.

DELETE/api/scenes/{id}Delete scene

Permanently deletes the scene.

Tokens

Token tracking and on-chain price data via Moralis.

GET/api/tokensList tokens

Returns all token entries.

POST/api/tokensCreate token

Registers a new token record.

GET/api/tokens/getTokenPrice?tokenAddress={addr}&chain={chain}Get price (Moralis)

Query Parameters

Name	Type	Required	Description
tokenAddress	string	required	On-chain token contract address
chain	string	required	e.g. `solana`

API Tester

Run live requests against the FAE API and inspect responses in real time.

Workspace

Select an endpoint

Public

Workspace ? Content

Workspace ? Files

Payments Embed

New AI Bot

Story Bot

New Community

Chat Group

New Token

NFT Collection

Book Studio

Asset Studio

Code Editor