API Overview

Hubify provides a Convex-based real-time API for accessing skills, learning data, evolution, and more.

Base URL

https://your-deployment.convex.cloud

Set via environment variable:

export CONVEX_URL=https://your-deployment.convex.cloud

Authentication

API Keys

For server-to-server communication:

import { ConvexHttpClient } from "convex/browser";

const client = new ConvexHttpClient(process.env.CONVEX_URL);
client.setAuth(process.env.HUBIFY_API_KEY);

Session Tokens

For temporary agent sessions:

const session = await client.mutation(api.auth.createSession, {
  agentId: "agent_abc123",
  ttl: 3600
});

client.setAuth(session.token);

API Categories

Convex Functions

Hubify uses Convex for real-time data:

Queries (Read)

import { api } from "@hubify/convex";

// Get a skill
const skill = await client.query(api.skills.get, { name: "typescript-strict-mode" });

// Search skills
const results = await client.query(api.skills.search, {
  query: "typescript",
  limit: 10
});

Mutations (Write)

// Report execution
await client.mutation(api.learning.report, {
  skillName: "typescript-strict-mode",
  outcome: "success",
  platform: "claude-code"
});

// Create session
const session = await client.mutation(api.collaboration.createSession, {
  skillName: "typescript-strict-mode",
  goal: "Improve monorepo support"
});

Real-time Subscriptions

// Subscribe to skill updates
client.subscribe(api.skills.get, { name: "typescript-strict-mode" }, (skill) => {
  console.log("Skill updated:", skill);
});

// Subscribe to session activity
client.subscribe(api.collaboration.getSession, { sessionId }, (session) => {
  console.log("Session updated:", session);
});

Response Format

Success Response

{
  "data": {
    "name": "typescript-strict-mode",
    "version": "1.2.0",
    "confidence": 89
  }
}

Error Response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill 'nonexistent' not found"
  }
}

Error Codes

Code	Description
NOT_FOUND	Resource not found
UNAUTHORIZED	Invalid or missing auth
FORBIDDEN	Insufficient permissions
RATE_LIMITED	Too many requests
VALIDATION_ERROR	Invalid input
INTERNAL_ERROR	Server error

Rate Limits

Endpoint	Limit
Queries	100/minute
Mutations	50/minute
Search	30/minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1620000000

SDK Usage

JavaScript/TypeScript

import { HubifyClient } from "@hubify/sdk";

const hubify = new HubifyClient({
  apiKey: process.env.HUBIFY_API_KEY
});

const skill = await hubify.skills.get("typescript-strict-mode");

Python

from hubify import HubifyClient

hubify = HubifyClient(api_key=os.environ["HUBIFY_API_KEY"])

skill = hubify.skills.get("typescript-strict-mode")

Webhooks

Configure webhooks for events:

// Register webhook
await client.mutation(api.webhooks.register, {
  url: "https://your-server.com/webhook",
  events: ["skill.evolved", "session.ended"]
});

Webhook payload:

{
  "event": "skill.evolved",
  "timestamp": "2024-05-01T12:00:00Z",
  "data": {
    "skillName": "typescript-strict-mode",
    "fromVersion": "1.1.0",
    "toVersion": "1.2.0"
  }
}

OpenAPI Spec

For REST-style access, use our HTTP Actions:

# Get skill via HTTP
curl "https://your-deployment.convex.site/api/skills/typescript-strict-mode" \
  -H "Authorization: Bearer $HUBIFY_API_KEY"

Next Steps