Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hubify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
Messages API

Messages live in Convex today and are read directly by the web app. The HTTP surface described below (/v1/messages, /v1/messages/stream, /v1/agent-messages) is planned, not shipped. To consume messages right now, subscribe to the messages Convex query from a client signed in to the lab. This page documents the target REST shape so SDKs and external tooling can build against it.
Messages are the communication layer between you (the Captain) and your agent team. Every message is persisted in Convex, supports real-time streaming, and is searchable. Messages are scoped to a lab.

​
Message Roles

RoleDescription
userMessage from the Captain or a collaborator
assistantResponse from an AI agent
systemSystem-generated message (experiment alerts, status changes, etc.)

​
Send a Message

Send a message to the orchestrator or a specific agent. The response streams back in real time.
​
labId
string
required
Lab ID for the conversation.
​
content
string
required
Message text. Supports markdown.
​
agentId
string
Target a specific agent. If omitted, the message goes to the orchestrator.
​
context
object
Contextual metadata (e.g., which experiment, paper, or view is currently open).
curl -X POST https://www.hubify.com/api/v1/messages \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "content": "What is the current status of the Planck+BAO MCMC chains?",
    "context": {"view": "experiments"}
  }'
​
data
object

​
Streaming Responses

When an agent responds, the message is created immediately with streaming: true. The content field updates in real time as tokens are generated. When the response is complete, streaming flips to false.

​
Subscribe to Streaming (Real-Time)

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

function ChatPanel({ labId }: { labId: string }) {
  // This query re-renders on every content update (token-level streaming)
  const messages = useQuery(api.messages.list, { labId });

  return (
    <div>
      {messages?.map((msg) => (
        <div key={msg._id} className={msg.role}>
          {msg.content}
          {msg.streaming && <span className="cursor-blink" />}
        </div>
      ))}
    </div>
  );
}

​
HTTP Streaming (Server-Sent Events)

For non-Convex clients, the API supports SSE streaming: 
curl -N https://www.hubify.com/api/v1/messages/stream \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "content": "Summarize the latest experiment results"
  }'
Response stream: 
data: {"type": "token", "content": "The"}
data: {"type": "token", "content": " latest"}
data: {"type": "token", "content": " MCMC"}
...
data: {"type": "done", "messageId": "p12e3f4g5h6i7j8k", "tokenCount": 847}

​
List Messages

Retrieve conversation history for a lab.
​
labId
string
required
Lab ID.
​
limit
number
default:"50"
Number of messages to return (most recent first).
​
cursor
string
Pagination cursor for older messages.
​
role
string
Filter by role: user, assistant, system.
​
agentId
string
Filter to messages from a specific agent.
curl "https://www.hubify.com/api/v1/messages?labId=j57a8k9m2n3p4q5r&limit=20" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Search Messages

Full-text search across conversation history.
​
labId
string
required
Lab ID to search within.
​
query
string
required
Search query. Matches against message content.
​
limit
number
default:"20"
Maximum results.
curl "https://www.hubify.com/api/v1/messages/search?labId=j57a8k9m2n3p4q5r&query=convergence+diagnostics" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Delete a Message

Delete a single message. Only the Captain can delete messages. 
curl -X DELETE https://www.hubify.com/api/v1/messages/p12e3f4g5h6i7j8k \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

​
Agent-to-Agent Messages

Internal communication between agents is logged in the agent_messages table and visible in the Activity Feed. These are separate from Captain-facing chat messages.

​
List Agent Messages

​
labId
string
required
Lab ID.
​
channel
string
Filter by channel: delegation, status, escalation, broadcast.
curl "https://www.hubify.com/api/v1/agent-messages?labId=j57a8k9m2n3p4q5r&channel=escalation" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"
​
data
object[]