API Reference
Complete reference for all MCPify gateway endpoints.
Authentication
All API endpoints (except /health) require authentication via the X-API-Key header:
Token Services
POST /tokens/count
Count tokens in text with caching
POST /tokens/count
Content-Type: application/json
X-API-Key: your-api-key
{
"text": "The quick brown fox jumps over the lazy dog",
"model": "claude" // or "gpt-4"
}
// Response
{
"tokens": 10,
"cached": true,
"cache_key": "hash_abc123"
}POST /tokens/truncate
Truncate data to fit token limit
Parameters: data, max_tokens, strategy ("start" | "end" | "middle")
Returns: Truncated data fitting within token limit
POST /tokens/estimate
Estimate response size before fetching
Parameters: sample_data, total_count
Returns: Estimated tokens for full dataset
Cache Services
POST /cache/set
Store value in cache with optional TTL and tags
POST /cache/set
Content-Type: application/json
X-API-Key: your-api-key
{
"key": "api_response_12345",
"value": {"users": [...]},
"ttl": 3600, // seconds
"tags": ["users", "api_v1"]
}
// Response
{
"success": true,
"key": "api_response_12345",
"expires_at": 1234567890
}POST /cache/get
Retrieve cached value with field filtering support
Parameters: key, fields (optional)
Returns: Cached value or null if not found
POST /cache/invalidate/tag/{tag}
Invalidate all cache entries with a specific tag
Returns: Count of invalidated entries
POST /cache/invalidate/mutation
Invalidate cache on mutation operations (POST, PUT, DELETE)
Parameters: resource, operation
Returns: Invalidation strategy applied
OAuth Services
POST /oauth/store
Store OAuth tokens securely with encryption
POST /oauth/store
Content-Type: application/json
X-API-Key: your-api-key
{
"api": "hubspot",
"user_id": "user_123",
"access_token": "token_abc",
"refresh_token": "refresh_xyz",
"expires_at": 1234567890
}
// Response
{
"success": true,
"api": "hubspot",
"user_id": "user_123"
}POST /oauth/get
Get OAuth token with automatic refresh if needed
Parameters: api, user_id
Returns: Valid access token (refreshed if necessary)
DELETE /oauth/{api}/{user_id}
Revoke stored OAuth tokens
Returns: Confirmation of token removal
Field Filtering
POST /filter/apply
Apply Google-style field mask to data
POST /filter/apply
Content-Type: application/json
X-API-Key: your-api-key
{
"data": {
"users": [
{"id": 1, "name": "Alice", "email": "[email protected]"},
{"id": 2, "name": "Bob", "email": "[email protected]"}
],
"total": 2
},
"fields": "users(id,name),total" // Google-style field mask
}
// Response
{
"users": [
{"id": 1, "name": "Alice"},
{"id": 2, "name": "Bob"}
],
"total": 2
}Field Mask Syntax:
- •
field- Single field - •
field1,field2- Multiple fields - •
object(field1,field2)- Nested fields - •
array(*)- All array elements - •
array(field)- Specific field from array elements
Pagination
POST /pagination/create
Create pagination session with optional snapshot
POST /pagination/create
Content-Type: application/json
X-API-Key: your-api-key
{
"total_items": 1000,
"page_size": 50,
"use_snapshot": true // Optional: ensure consistency
}
// Response
{
"session_id": "pag_abc123",
"total_pages": 20,
"page_size": 50,
"snapshot_created": true
}GET /pagination/{session_id}/page
Get page parameters or snapshot data
Query params: page_number
Returns: Page data from snapshot or parameters for fetching
POST /pagination/{session_id}/snapshot
Store data snapshot for consistency
Parameters: data (full dataset)
Returns: Snapshot confirmation with size info
Rate Limiting
POST /ratelimit/check
Check if request is allowed under rate limits
Parameters: api, user_id, operation
Returns: allowed (boolean), remaining, reset_at
Analytics
POST /analytics/track
Track usage event
Parameters: event_type, api, user_id, metadata
Returns: Event ID for tracking
GET /analytics/stats
Get usage statistics
Query params: api, user_id, period, group_by
Returns: Aggregated usage statistics
Health & Admin
GET /health
Health check endpoint (no auth required)
GET /admin/stats
System statistics (requires admin API key)
Returns: Cache stats, token counts, active sessions, memory usage