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

Role	Description
`user`	Message from the Captain or a collaborator
`assistant`	Response from an AI agent
`system`	System-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.

string

required

Lab ID for the conversation.

string

required

Message text. Supports markdown.

string

Target a specific agent. If omitted, the message goes to the orchestrator.

object

Contextual metadata (e.g., which experiment, paper, or view is currently open).

Show Context fields

string

Active experiment ID.

string

Active paper ID.

string

Current UI view (e.g., captain, experiments, papers).

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"}
  }'

const message = await hubify.messages.send({
  labId: "j57a8k9m2n3p4q5r",
  content: "What is the current status of the Planck+BAO MCMC chains?",
  context: { view: "experiments" },
});

object

Show Message object

string

required

Convex document ID.

string

required

Lab ID.

string

Sender user ID (for user role).

string

Sender agent ID (for assistant role).

string

required

Message role: user, assistant, or system.

string

required

Message content (markdown).

string

JSON-encoded context metadata.

boolean

True while the assistant is still generating.

string

Model that generated the response (e.g., claude-opus-4-8).

number

Total tokens used.

number

Estimated cost in USD.

number

required

Timestamp (ms).

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.

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.

string

required

Lab ID.

number

default:"50"

Number of messages to return (most recent first).

string

Pagination cursor for older messages.

string

Filter by role: user, assistant, system.

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"

const messages = await hubify.messages.list({
  labId: "j57a8k9m2n3p4q5r",
  limit: 20,
});

Search Messages

Full-text search across conversation history.

string

required

Lab ID to search within.

string

required

Search query. Matches against message content.

number

default:"20"

Maximum results.

curl "https://www.hubify.com/api/v1/messages/search?labId=j57a8k9m2n3p4q5r&query=convergence+diagnostics" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const results = await hubify.messages.search({
  labId: "j57a8k9m2n3p4q5r",
  query: "convergence diagnostics",
});

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"

await hubify.messages.delete({ messageId: "p12e3f4g5h6i7j8k" });

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

string

required

Lab ID.

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"

const agentMessages = await hubify.agentMessages.list({
  labId: "j57a8k9m2n3p4q5r",
  channel: "escalation",
});

object[]

Show Agent message object

string

required

Convex document ID.

string

required

Lab ID.

string

required

Sending agent ID.

string

Receiving agent ID. Null for broadcasts.

string

required

Communication channel.

string

required

Message content.

string

JSON-encoded context.

number

required

Timestamp (ms).

Overview

Labs

Data

Compute

Lab Ops

Messages

Messages API

Message Roles

Send a Message

Streaming Responses

HTTP Streaming (Server-Sent Events)

List Messages

Search Messages

Delete a Message

Agent-to-Agent Messages

List Agent Messages

​Messages API

​Message Roles

​Send a Message

​Streaming Responses

​Subscribe to Streaming (Real-Time)

​HTTP Streaming (Server-Sent Events)

​List Messages

​Search Messages

​Delete a Message

​Agent-to-Agent Messages

​List Agent Messages

Messages API

Message Roles

Send a Message

Streaming Responses

Subscribe to Streaming (Real-Time)

HTTP Streaming (Server-Sent Events)

List Messages

Search Messages

Delete a Message

Agent-to-Agent Messages

List Agent Messages