# 23blocks — Full AI Agent Reference

> Comprehensive reference for AI agents integrating with 23blocks Backend as a Service.
> 18 blocks. 203 skills. Production-ready APIs.

---

## Platform Overview

23blocks is a Backend as a Service (BaaS) platform that provides fully-managed, plug-and-play API blocks. Each block is an independent microservice with its own database, authentication layer, and REST API. Blocks can be enabled independently and compose together through a shared authentication context.

### Key Properties
- Multi-tenant architecture with data isolation per application
- RS256 JWT authentication across all blocks
- RESTful APIs with consistent JSON responses
- Rate limiting: 1000 requests/minute per application
- 99.99% uptime SLA
- AWS infrastructure (US regions)

### API Base URL
```
https://api.23blocks.com/v1
```

### Required Headers (all requests)
```
app-id: YOUR_APP_ID
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json
```

### Standard Response Format
```json
{
  "data": { ... },
  "meta": {
    "pagination": {
      "current_page": 1,
      "total_pages": 10,
      "total_count": 100,
      "per_page": 25
    }
  }
}
```

### Error Response Format
```json
{
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "Email has already been taken"
    }
  ]
}
```

---

## Block 1: Auth (Gateway)

Authentication, authorization, and user management.

**Base path:** `/v1/auth`
**NPM plugin:** `23blocks-auth-mcp`

### Skills (16)
1. `register_user` — Create a new user account with email/password
2. `login` — Authenticate user and receive JWT token
3. `logout` — Invalidate current session token
4. `refresh_token` — Refresh an expired JWT token
5. `forgot_password` — Send password reset email
6. `reset_password` — Reset password with token from email
7. `change_password` — Change password for authenticated user
8. `get_profile` — Get current user profile
9. `update_profile` — Update user profile fields
10. `enable_mfa` — Enable TOTP-based multi-factor authentication
11. `verify_mfa` — Verify MFA code during login
12. `disable_mfa` — Disable MFA for current user
13. `create_api_key` — Generate a new API key
14. `list_api_keys` — List all API keys for current user
15. `revoke_api_key` — Revoke an existing API key
16. `magic_link_login` — Send magic link for passwordless authentication

### Key Endpoints
```
POST   /v1/auth/register
POST   /v1/auth/login
DELETE /v1/auth/logout
POST   /v1/auth/refresh
POST   /v1/auth/forgot-password
POST   /v1/auth/reset-password
PATCH  /v1/auth/password
GET    /v1/auth/profile
PATCH  /v1/auth/profile
POST   /v1/auth/mfa/enable
POST   /v1/auth/mfa/verify
DELETE /v1/auth/mfa/disable
POST   /v1/auth/api-keys
GET    /v1/auth/api-keys
DELETE /v1/auth/api-keys/:id
POST   /v1/auth/magic-link
```

### Auth Patterns
- Token format: RS256 JWT with 24-hour expiry
- Refresh tokens: 30-day expiry, single-use
- MFA: TOTP (RFC 6238) compatible with Google Authenticator
- Magic links: 15-minute expiry, single-use

---

## Block 2: Onboarding

User activation journeys and step tracking.

**Base path:** `/v1/onboarding`
**NPM plugin:** `23blocks-onboarding-mcp`

### Skills (12)
1. `create_journey` — Create a new onboarding journey template
2. `list_journeys` — List all journey templates
3. `get_journey` — Get journey template details
4. `update_journey` — Update journey template
5. `delete_journey` — Delete a journey template
6. `start_user_journey` — Start a journey for a specific user
7. `get_user_progress` — Get user's progress in a journey
8. `complete_step` — Mark a journey step as completed
9. `skip_step` — Skip a journey step
10. `reset_journey` — Reset user's journey progress
11. `send_activation_email` — Send activation/welcome email
12. `get_journey_analytics` — Get completion rates and analytics

---

## Block 3: Files

File storage, CDN delivery, and access control.

**Base path:** `/v1/files`
**NPM plugin:** `23blocks-files-mcp`

### Skills (14)
1. `upload_file` — Upload a file (multipart/form-data)
2. `get_file` — Get file metadata and download URL
3. `list_files` — List files with filtering and pagination
4. `delete_file` — Delete a file
5. `update_file_metadata` — Update file name, description, tags
6. `create_folder` — Create a virtual folder
7. `move_file` — Move file to a different folder
8. `copy_file` — Create a copy of a file
9. `set_file_access` — Set file access level (public/private/shared)
10. `share_file` — Generate a shareable link with expiry
11. `get_file_versions` — List file version history
12. `restore_version` — Restore a previous file version
13. `create_category` — Create a file category
14. `bulk_upload` — Upload multiple files in a batch

### File Limits
- Max file size: 100MB (standard), 5GB (enterprise)
- Supported formats: All common formats
- CDN: AWS CloudFront with global edge locations
- Storage: AWS S3 with AES-256 encryption at rest

---

## Block 4: CRM

Contact and relationship management.

**Base path:** `/v1/crm`
**NPM plugin:** `23blocks-crm-mcp`

### Skills (15)
1. `create_contact` — Create a new contact
2. `get_contact` — Get contact details
3. `list_contacts` — List contacts with search and filters
4. `update_contact` — Update contact information
5. `delete_contact` — Delete a contact
6. `create_company` — Create a new company
7. `get_company` — Get company details
8. `list_companies` — List companies
9. `update_company` — Update company information
10. `create_deal` — Create a new deal/opportunity
11. `update_deal_stage` — Move deal to a different pipeline stage
12. `list_deals` — List deals with pipeline filtering
13. `log_activity` — Log an activity (call, email, meeting)
14. `list_activities` — List activities for a contact or deal
15. `create_pipeline` — Create a custom deal pipeline

---

## Block 5: Forms

Dynamic form creation, submission, and analysis.

**Base path:** `/v1/forms`
**NPM plugin:** `23blocks-forms-mcp`

### Skills (13)
1. `create_form` — Create a new form with field definitions
2. `get_form` — Get form structure and settings
3. `list_forms` — List all forms
4. `update_form` — Update form fields and settings
5. `delete_form` — Delete a form
6. `submit_form` — Submit a form response
7. `list_submissions` — List form submissions with filtering
8. `get_submission` — Get a specific submission
9. `export_submissions` — Export submissions as CSV/JSON
10. `create_survey` — Create a scored survey form
11. `create_appointment_form` — Create appointment booking form
12. `enable_magic_link` — Enable magic link access for form
13. `get_form_analytics` — Get submission analytics and scores

---

## Block 6: Content

Headless CMS with versioning and social features.

**Base path:** `/v1/content`
**NPM plugin:** `23blocks-content-mcp`

### Skills (14)
1. `create_post` — Create a new content post
2. `get_post` — Get post with current version
3. `list_posts` — List posts with filtering
4. `update_post` — Update post (creates new version)
5. `delete_post` — Delete a post
6. `publish_post` — Publish a draft post
7. `create_series` — Create a content series/collection
8. `add_to_series` — Add post to a series
9. `create_comment` — Add a comment to a post
10. `list_comments` — List comments on a post
11. `like_post` — Like/unlike a post
12. `create_tag` — Create a content tag
13. `create_category` — Create a content category
14. `get_post_versions` — List version history of a post

---

## Block 7: Products

Product catalog and inventory management.

**Base path:** `/v1/products`
**NPM plugin:** `23blocks-products-mcp`

### Skills (12)
1. `create_product` — Create a new product
2. `get_product` — Get product details
3. `list_products` — List products with filtering
4. `update_product` — Update product information
5. `delete_product` — Delete a product
6. `create_variant` — Create a product variant (size, color)
7. `update_inventory` — Update stock levels
8. `set_pricing` — Set or update pricing
9. `create_product_category` — Create product category
10. `add_product_image` — Add image to product
11. `bulk_import` — Import products from CSV
12. `search_products` — Full-text search across products

---

## Block 8: Sales

Subscriptions, invoicing, and payment processing.

**Base path:** `/v1/sales`
**NPM plugin:** `23blocks-sales-mcp`

### Skills (13)
1. `create_subscription` — Create a new subscription
2. `get_subscription` — Get subscription details
3. `update_subscription` — Upgrade/downgrade subscription
4. `cancel_subscription` — Cancel a subscription
5. `create_invoice` — Generate an invoice
6. `list_invoices` — List invoices for a customer
7. `pay_invoice` — Process payment for an invoice
8. `create_plan` — Create a subscription plan
9. `list_plans` — List available plans
10. `apply_coupon` — Apply discount coupon
11. `create_coupon` — Create a discount coupon
12. `get_revenue_metrics` — Get MRR, churn, LTV metrics
13. `sync_stripe` — Sync with Stripe payment processor

---

## Block 9: Rewards

Gamification, loyalty points, and achievements.

**Base path:** `/v1/rewards`
**NPM plugin:** `23blocks-rewards-mcp`

### Skills (12)
1. `award_points` — Award points to a user
2. `deduct_points` — Deduct points from a user
3. `get_balance` — Get user's point balance
4. `create_badge` — Create a new achievement badge
5. `award_badge` — Award a badge to a user
6. `list_badges` — List all badges
7. `get_leaderboard` — Get leaderboard rankings
8. `create_challenge` — Create a challenge/quest
9. `complete_challenge` — Mark challenge as completed
10. `create_reward_tier` — Create a loyalty tier
11. `redeem_points` — Redeem points for a reward
12. `get_user_achievements` — Get all user achievements

---

## Block 10: Geolocation

Maps, geocoding, and location-based services.

**Base path:** `/v1/geolocation`
**NPM plugin:** `23blocks-geolocation-mcp`

### Skills (10)
1. `geocode_address` — Convert address to coordinates
2. `reverse_geocode` — Convert coordinates to address
3. `create_geofence` — Create a geographic boundary
4. `check_geofence` — Check if point is inside geofence
5. `track_location` — Update user/device location
6. `get_location_history` — Get location history for entity
7. `calculate_distance` — Calculate distance between points
8. `find_nearby` — Find nearby points of interest
9. `create_place` — Create a place/location entity
10. `list_places` — List places with geo-filtering

---

## Block 11: Realtime

WebSocket communication and live updates.

**Base path:** `/v1/realtime`
**NPM plugin:** `23blocks-realtime-mcp`

### Skills (8)
1. `create_channel` — Create a realtime channel
2. `subscribe_channel` — Subscribe to a channel
3. `unsubscribe_channel` — Unsubscribe from a channel
4. `publish_message` — Publish message to a channel
5. `get_presence` — Get online users in a channel
6. `send_direct_message` — Send a direct message to a user
7. `list_channels` — List available channels
8. `get_channel_history` — Get message history for a channel

---

## Block 12: Search

Full-text search engine with facets and autocomplete.

**Base path:** `/v1/search`
**NPM plugin:** `23blocks-search-mcp`

### Skills (8)
1. `index_document` — Add a document to the search index
2. `search` — Perform a full-text search
3. `autocomplete` — Get autocomplete suggestions
4. `create_index` — Create a new search index
5. `delete_document` — Remove a document from the index
6. `bulk_index` — Index multiple documents at once
7. `get_facets` — Get faceted search results
8. `update_index_settings` — Update index configuration

---

## Block 13: AI (Jarvis)

AI agent orchestration, prompts, and workflows.

**Base path:** `/v1/jarvis`
**NPM plugin:** `23blocks-jarvis-mcp`

### Skills (15)
1. `create_agent` — Create a new AI agent
2. `get_agent` — Get agent configuration
3. `list_agents` — List all agents
4. `update_agent` — Update agent settings
5. `create_prompt` — Create a versioned prompt template
6. `execute_prompt` — Execute a prompt with variables
7. `create_workflow` — Create a BPMN workflow
8. `execute_workflow` — Execute a workflow
9. `create_conversation` — Start a new conversation
10. `send_message` — Send a message in a conversation
11. `get_conversation` — Get conversation history
12. `create_digital_twin` — Create a digital twin entity
13. `create_cluster` — Create an agent cluster
14. `register_tool` — Register an external tool for agents
15. `list_conversations` — List all conversations

---

## Block 14: University

Learning management system with courses and certifications.

**Base path:** `/v1/university`
**NPM plugin:** `23blocks-university-mcp`

### Skills (12)
1. `create_course` — Create a new course
2. `get_course` — Get course details
3. `list_courses` — List available courses
4. `update_course` — Update course information
5. `create_lesson` — Create a lesson within a course
6. `enroll_user` — Enroll a user in a course
7. `complete_lesson` — Mark a lesson as completed
8. `get_progress` — Get user's learning progress
9. `create_quiz` — Create a quiz for a lesson
10. `submit_quiz` — Submit quiz answers
11. `issue_certificate` — Issue a completion certificate
12. `get_analytics` — Get course analytics

---

## Block 15: Companies

Organization and team management.

**Base path:** `/v1/companies`
**NPM plugin:** `23blocks-companies-mcp`

### Skills (10)
1. `create_company` — Create a new organization
2. `get_company` — Get organization details
3. `update_company` — Update organization info
4. `create_team` — Create a team within organization
5. `add_member` — Add a member to organization/team
6. `remove_member` — Remove a member
7. `set_role` — Set member's role/permissions
8. `list_members` — List organization members
9. `create_invitation` — Send an invitation to join
10. `get_org_settings` — Get organization settings

---

## Block 16: Assets

Digital asset management with metadata and transformations.

**Base path:** `/v1/assets`
**NPM plugin:** `23blocks-assets-mcp`

### Skills (10)
1. `create_asset` — Create a new digital asset
2. `get_asset` — Get asset details and metadata
3. `list_assets` — List assets with filtering
4. `update_asset` — Update asset metadata
5. `delete_asset` — Delete an asset
6. `transform_asset` — Apply transformations (resize, crop, convert)
7. `create_collection` — Create an asset collection
8. `add_to_collection` — Add asset to collection
9. `tag_asset` — Add tags to asset
10. `get_asset_analytics` — Get asset usage analytics

---

## Block 17: Wallet

Digital wallet with balances and transaction ledger.

**Base path:** `/v1/wallet`
**NPM plugin:** `23blocks-wallet-mcp`

### Skills (10)
1. `create_wallet` — Create a wallet for a user
2. `get_balance` — Get wallet balance
3. `credit` — Add funds to wallet
4. `debit` — Deduct funds from wallet
5. `transfer` — Transfer between wallets
6. `get_transactions` — Get transaction history
7. `create_ledger_entry` — Create a manual ledger entry
8. `freeze_wallet` — Freeze a wallet
9. `unfreeze_wallet` — Unfreeze a wallet
10. `get_wallet_summary` — Get wallet summary with stats

---

## Block 18: Salesforce

CRM synchronization and lead management.

**Base path:** `/v1/salesforce`
**NPM plugin:** `23blocks-salesforce-mcp`

### Skills (8)
1. `sync_contacts` — Sync contacts with Salesforce
2. `create_lead` — Create a new lead
3. `update_lead` — Update lead information
4. `convert_lead` — Convert lead to opportunity
5. `create_opportunity` — Create a new opportunity
6. `update_opportunity_stage` — Update opportunity pipeline stage
7. `get_sync_status` — Get synchronization status
8. `configure_mapping` — Configure field mappings

---

## Agent Installation

### Claude Code MCP Plugins

Install any block as a Claude Code MCP server:

```bash
# Auth block
claude mcp add-json "23blocks-auth" '{"type":"stdio","command":"npx","args":["23blocks-auth-mcp"]}'

# Files block
claude mcp add-json "23blocks-files" '{"type":"stdio","command":"npx","args":["23blocks-files-mcp"]}'

# Forms block
claude mcp add-json "23blocks-forms" '{"type":"stdio","command":"npx","args":["23blocks-forms-mcp"]}'

# Content block
claude mcp add-json "23blocks-content" '{"type":"stdio","command":"npx","args":["23blocks-content-mcp"]}'

# CRM block
claude mcp add-json "23blocks-crm" '{"type":"stdio","command":"npx","args":["23blocks-crm-mcp"]}'

# AI/Jarvis block
claude mcp add-json "23blocks-jarvis" '{"type":"stdio","command":"npx","args":["23blocks-jarvis-mcp"]}'
```

### Recommended Agent Setup
1. Start with Auth block for user management
2. Add blocks based on your use case
3. Use the same `app-id` across all blocks
4. Authenticate once, use the JWT across all blocks

---

## Common Patterns

### Authentication Flow
```
1. POST /v1/auth/register → creates user, returns JWT
2. Use JWT in Authorization header for all subsequent requests
3. POST /v1/auth/refresh → refresh expired tokens
```

### Multi-Block Workflow Example
```
1. Auth: Register user → get JWT
2. Files: Upload avatar → get file URL
3. CRM: Create contact with avatar URL
4. Forms: Create feedback form
5. Content: Create welcome post
```

### Pagination
```
GET /v1/[block]/[resource]?page=1&per_page=25
```

### Filtering
```
GET /v1/[block]/[resource]?filter[status]=active&filter[created_at_gt]=2024-01-01
```

### Sorting
```
GET /v1/[block]/[resource]?sort=-created_at (descending)
GET /v1/[block]/[resource]?sort=name (ascending)
```

---

## Common Mistakes

1. **Missing app-id header** — Every request needs the `app-id` header
2. **Using expired tokens** — JWT tokens expire after 24 hours; use refresh endpoint
3. **Wrong content type** — File uploads use `multipart/form-data`, everything else uses `application/json`
4. **Ignoring pagination** — Default page size is 25; use pagination for large datasets
5. **Not handling rate limits** — 1000 req/min; implement exponential backoff on 429 responses

---

## Links

- Website: https://23blocks.com
- Documentation: https://23blocks.com/developers/docs
- AI Agents: https://23blocks.com/agents
- Skills Directory: https://23blocks.com/agents/skills
- GitHub: https://github.com/23blocks-OS
- Status: https://status.23blocks.com
- Support: https://23blocks.com/support
- API Base: https://api.23blocks.com/v1