API Reference
API Reference
Programmatic access to JHorizon's Convex backend and Tinybird analytics
Overview
JHorizon provides two types of programmatic access:
Convex Functions
Server-side queries, mutations, and actions for operational data and workflow management.
Tinybird Endpoints
HTTP API endpoints for high-performance analytics queries with sub-second response times.
Authentication
Convex
JHorizon uses Clerk for authentication with JWT tokens.
import { ConvexReactClient } from "convex/react";
import { ClerkProvider, useAuth } from "@clerk/clerk-react";
import { ConvexProviderWithClerk } from "convex/react-clerk";
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);
function App() {
return (
<ClerkProvider publishableKey="...">
<ConvexProviderWithClerk client={convex} useAuth={useAuth}>
{/* Your app */}
</ConvexProviderWithClerk>
</ClerkProvider>
);
}# Get JWT token from Clerk
export CLERK_TOKEN="your-jwt-token"
# Call Convex function
curl https://your-deployment.convex.cloud/api/query \
-H "Authorization: Bearer $CLERK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"path": "organizations/getById", "args": {"organizationId": "..."}}'Tinybird
Tinybird uses token-based authentication with read/write scopes.
Tinybird tokens are server-side only. Never expose them in client-side code.
# Set environment variable
export TINYBIRD_TOKEN="your-token"
# Query analytics endpoint
curl "https://api.tinybird.co/v0/pipes/prompts_analytics.json?organization_id=..." \
-H "Authorization: Bearer $TINYBIRD_TOKEN"Rate Limits
| Service | Limit | Reset |
|---|---|---|
| Convex Queries | 10,000/min | Rolling window |
| Convex Mutations | 1,000/min | Rolling window |
| Tinybird Analytics | 100 req/s | Per token |
Contact support for enterprise rate limits.
Error Handling
Both APIs use standard HTTP status codes:
- 200: Success
- 400: Bad request (invalid parameters)
- 401: Unauthorized (missing/invalid auth)
- 403: Forbidden (insufficient permissions)
- 404: Not found
- 429: Rate limit exceeded
- 500: Server error
Error Response Format
{
"code": "VALIDATION_ERROR",
"message": "Invalid organizationId format",
"path": "organizations/getById"
}{
"error": "Invalid parameter",
"message": "organization_id must be a valid UUID",
"query_id": "abc-123"
}