AI Tool Integration

Give your AI coding assistant full context about your Fascia backend. By creating an API Key and sharing your spec bundle, tools like Claude Code, Cursor, and other AI assistants can understand your Entity definitions, Tool schemas, and API structure — making frontend development faster and more accurate.

How It Works

1. You create an API Key in your Fascia workspace
2. Fetch your spec bundle using the API key
3. Feed the bundle (or llms.txt) to your AI assistant as context
4. The assistant now knows your exact data model, API endpoints, and business rules

Step 1: Create an API Key

API Keys are managed from the Settings page in your dashboard, or via the API:

curl -X POST https://api.fascia.run/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Assistant Access",
    "scopes": ["bundle:read", "entity:read"]
  }'

The response includes a rawKey starting with fsk_ — save this immediately, as it won't be shown again:

{
  "id": "key-uuid",
  "name": "AI Assistant Access",
  "keyPrefix": "fsk_abc",
  "rawKey": "fsk_abc...full-key...",
  "scopes": ["bundle:read", "entity:read"]
}

Available Scopes

Scope	Description
bundle:read	Read the complete spec bundle (all Entities, Tools, Policies)
entity:read	Read individual Entity specs
tool:call	Invoke deployed Tools via the API

For AI integration, bundle:read is typically sufficient.

Step 2: Fetch Your Spec Bundle

Use the API key to retrieve your workspace's complete spec bundle:

curl https://api.fascia.run/api/v1/bundle \
  -H "Authorization: Bearer fsk_your-api-key-here"

This returns all Entity specs, Tool specs, and Policies as structured JSON. The endpoint supports ETag headers for efficient polling — if specs haven't changed, the server returns 304 Not Modified.

For an AI-optimized text format, use the llms.txt endpoint:

curl https://api.fascia.run/api/v1/docs/llms.txt \
  -H "Authorization: Bearer fsk_your-api-key-here"

Step 3: Use with AI Assistants

Claude Code

Add the spec bundle as project context. Save the llms.txt output to your project:

# Download your backend spec as context
curl https://api.fascia.run/api/v1/docs/llms-full.txt \
  -H "Authorization: Bearer fsk_your-api-key-here" \
  -o fascia-backend.md

Then reference it in your CLAUDE.md:

@fascia-backend.md

Claude Code will automatically read this file and understand your backend when helping you build the frontend.

Cursor

Add the spec bundle as documentation context in Cursor:

1. Save the llms.txt output to your project root (e.g., fascia-backend.md)
2. Cursor will index this file and use it as context when answering questions about your API

Other AI Tools

Any AI coding assistant that supports custom context can use the bundle or llms.txt output. The key workflow is:

1. Fetch the spec bundle or llms.txt via API
2. Save it as a file in your project
3. Configure your AI tool to read that file as context

What Your AI Assistant Learns

Once your assistant has the spec bundle, it understands:

Knowledge	Example
Entity fields and types	"Reservation has fields: customerId (reference), startDate (datetime), totalPrice (number)"
Status machines	"Reservation states: pending → confirmed → checked_in → completed"
API endpoints	"POST /reservations/:id/pay expects paymentMethod, cardToken"
Business rules	"End date must be after start date, total price must be positive"
Relationships	"Reservation belongs to Customer, has many Payments"

Example Conversations

With spec context loaded, you can have conversations like:

"Build a React form for the createReservation tool"

The assistant knows the exact input schema, required fields, and validation rules

"Create a dashboard that shows all Reservations grouped by status"

The assistant knows the Entity fields and status machine states

"Write API integration code for the payment flow"

The assistant knows the endpoint, request format, and expected responses

Keeping Context Fresh

Your spec bundle changes as you design new Entities and Tools. To keep your AI assistant up to date:

• Manual: Re-fetch the llms.txt file periodically
• Automated: Use the ETag header to poll for changes efficiently:

# First request — save the ETag
curl -D- https://api.fascia.run/api/v1/bundle \
  -H "Authorization: Bearer fsk_your-api-key-here" \
  | grep ETag

# Subsequent requests — check if changed
curl -H "If-None-Match: \"previous-etag-value\"" \
  https://api.fascia.run/api/v1/bundle \
  -H "Authorization: Bearer fsk_your-api-key-here"
# Returns 304 if unchanged, 200 with new data if changed

Managing API Keys

List Keys

curl https://api.fascia.run/api/v1/api-keys \
  -H "Authorization: Bearer $TOKEN"

Revoke a Key

curl -X DELETE https://api.fascia.run/api/v1/api-keys/{key-id} \
  -H "Authorization: Bearer $TOKEN"

Revoked keys stop working immediately. All API key operations are recorded in the audit log.

Security Notes

• API Keys provide read-only access by default (unless tool:call scope is granted)
• Keys can be scoped to specific operations
• Keys can have expiration dates
• All access is logged in the audit trail
• Revoke keys immediately if compromised
• Never commit API keys to source control — use environment variables