API Reference

FLXBL automatically generates REST and GraphQL APIs from your schema. This reference covers all available endpoints and operations.

Base URL

All API requests use this base URL:

https://api.flxbl.dev/api/v1

For self-hosted instances, use your configured URL.

Authentication

Use API keys for programmatic access to the FLXBL Dynamic API. Include your API key in the Authorization header: 

# API Key Authentication
curl -X GET https://api.flxbl.dev/api/v1/dynamic/Product \
  -H "Authorization: Bearer flxbl_ab12cd34_..."

# Get your API key from your FLXBL dashboard at platform.flxbl.dev

Generate API keys from your FLXBL dashboard at platform.flxbl.dev. API keys are scoped to your tenant and provide access to the Dynamic API endpoints.

REST API Endpoints

For each entity in your schema, these endpoints are generated:

# Entity CRUD Operations
GET    /api/v1/dynamic/{Entity}           # List all
POST   /api/v1/dynamic/{Entity}           # Create
GET    /api/v1/dynamic/{Entity}/:id       # Read
PUT    /api/v1/dynamic/{Entity}/:id       # Full update
PATCH  /api/v1/dynamic/{Entity}/:id       # Partial update
DELETE /api/v1/dynamic/{Entity}/:id       # Delete
POST   /api/v1/dynamic/{Entity}/query     # Query with DSL

# Relationship Operations
POST   /api/v1/dynamic/{Entity}/:id/relationships/{rel}
GET    /api/v1/dynamic/{Entity}/:id/relationships/{rel}?direction=out
PATCH  /api/v1/dynamic/{Entity}/:id/relationships/{rel}/:targetId
DELETE /api/v1/dynamic/{Entity}/:id/relationships/{rel}/:targetId

# GraphQL Endpoint
POST   /api/v1/dynamic-gql/:tenantId
GET    /api/v1/dynamic-gql/:tenantId/schema.graphql
Important: Entity names in URLs are case-sensitive. Use the exact name from your schema (e.g., Product not products).

Create (POST)

# Create a product
curl -X POST https://api.flxbl.dev/api/v1/dynamic/Product \
  -H "Authorization: Bearer flxbl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "price": 299.99,
    "inStock": true,
    "tags": ["electronics", "audio"]
  }'

# Response
{
  "id": "node_abc123",
  "name": "Wireless Headphones",
  "price": 299.99,
  "inStock": true,
  "tags": ["electronics", "audio"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Read (GET)

# Get a product by ID
curl -X GET https://api.flxbl.dev/api/v1/dynamic/Product/node_abc123 \
  -H "Authorization: Bearer flxbl_your_api_key"

# List all products
curl -X GET https://api.flxbl.dev/api/v1/dynamic/Product \
  -H "Authorization: Bearer flxbl_your_api_key"

Update (PUT/PATCH)

# Full update (PUT) - replaces all fields
curl -X PUT https://api.flxbl.dev/api/v1/dynamic/Product/node_abc123 \
  -H "Authorization: Bearer flxbl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Wireless Headphones",
    "price": 349.99,
    "inStock": true,
    "tags": ["electronics", "audio", "premium"]
  }'

# Partial update (PATCH) - only updates specified fields
curl -X PATCH https://api.flxbl.dev/api/v1/dynamic/Product/node_abc123 \
  -H "Authorization: Bearer flxbl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "price": 279.99
  }'

Delete (DELETE)

# Delete a product
# IMPORTANT: Do NOT include Content-Type header for DELETE without body
curl -X DELETE https://api.flxbl.dev/api/v1/dynamic/Product/node_abc123 \
  -H "Authorization: Bearer flxbl_your_api_key"
Important: Do NOT include Content-Type: application/json header for DELETE requests without a body. This will cause a 400 error.

Relationship Operations

Manage relationships between entities:

# Create a relationship
curl -X POST https://api.flxbl.dev/api/v1/dynamic/Product/node_abc/relationships/BELONGS_TO \
  -H "Authorization: Bearer flxbl_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "targetId": "node_category_xyz",
    "properties": {
      "addedAt": "2025-01-15T10:30:00Z"
    }
  }'

# Get relationships
curl -X GET "https://api.flxbl.dev/api/v1/dynamic/Product/node_abc/relationships/BELONGS_TO?direction=out" \
  -H "Authorization: Bearer flxbl_your_api_key"

# Delete a relationship
curl -X DELETE https://api.flxbl.dev/api/v1/dynamic/Product/node_abc/relationships/BELONGS_TO/node_category_xyz \
  -H "Authorization: Bearer flxbl_your_api_key"

GraphQL API

FLXBL also generates a complete GraphQL API. The endpoint requires your tenant ID: 

# GraphQL endpoint
POST /api/v1/dynamic-gql/:tenantId

# Query example
query {
  products(where: { inStock: true }, limit: 10) {
    id
    name
    price
    belongsTo {
      id
      name
    }
  }
}

# Mutation example
mutation {
  createProduct(input: {
    name: "New Product"
    price: 99.99
  }) {
    id
    name
    createdAt
  }
}

Download the GraphQL schema:

GET /api/v1/dynamic-gql/{tenantId}/schema.graphql

Integrate with External Tools

FLXBL generates standard OpenAPI and GraphQL specifications that work with your favorite API tools.

Postman / Insomnia

Import your schema's OpenAPI spec directly into Postman or Insomnia for interactive API testing:

  1. Download your OpenAPI spec: GET /api/v1/schemas/:schemaId/openapi.json
  2. In Postman: Import → File → Select openapi.json
  3. All your entity endpoints, authentication, and request bodies are ready to use

Apollo Sandbox / GraphiQL

Connect Apollo Sandbox or GraphiQL to your GraphQL endpoint for schema exploration and query building:

  1. Point your GraphQL client to POST /api/v1/dynamic-gql/:tenantId
  2. Include your API key in the Authorization: Bearer flxbl_xxx header
  3. Download the schema: GET /api/v1/dynamic-gql/:tenantId/schema.graphql
Tip: The GraphQL endpoint supports introspection, so tools like Apollo Sandbox will automatically discover your schema's types and operations.

Rate Limiting

FLXBL implements multi-layer rate limiting:

Layer Default Limit Scope
Global 200 req/min Per IP address
Auth endpoints 10 req/min Per IP address
Tenant 100 req/min Per tenant

Rate limit information is included in response headers:

# Rate limit headers in response
X-RateLimit-Limit: 100          # Max requests per window
X-RateLimit-Remaining: 95       # Requests remaining
X-RateLimit-Reset: 60           # Seconds until reset

When rate limited, the API returns 429 Too Many Requests. Use the X-RateLimit-Reset header to know when to retry.

Error Responses

Errors follow a consistent format:

Status Meaning
400 Bad request - Invalid input or missing required fields
401 Unauthorized - Missing or invalid authentication
403 Forbidden - Insufficient permissions
404 Not found - Entity or resource doesn't exist
429 Too many requests - Rate limit exceeded
500 Internal error - Server-side issue

Next Steps