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.

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).

Show Context fields

experimentId

string

Active experiment ID.

paperId

string

Active paper ID.

view

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" },
});

data

object

Show Message object

_id

string

required

Convex document ID.

labId

string

required

Lab ID.

userId

string

Sender user ID (for user role).

agentId

string

Sender agent ID (for assistant role).

role

string

required

Message role: user, assistant, or system.

content

string

required

Message content (markdown).

context

string

JSON-encoded context metadata.

streaming

boolean

True while the assistant is still generating.

model

string

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

tokenCount

number

Total tokens used.

costUsd

number

Estimated cost in USD.

createdAt

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.

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"

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

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"

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

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"

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

data

object[]

Show Agent message object

_id

string

required

Convex document ID.

labId

string

required

Lab ID.

fromAgentId

string

required

Sending agent ID.

toAgentId

string

Receiving agent ID. Null for broadcasts.

channel

string

required

Communication channel.

content

string

required

Message content.

metadata

string

JSON-encoded context.

createdAt

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