Skip to main content

​
GET /health

Health check endpoint for monitoring.

​
Request

curl https://your-project.convex.cloud/health

​
Response

{
  "status": "ok",
  "model": "anthropic/claude-3.5-sonnet",
  "lastTick": 1706400000000,
  "tickCount": 1523,
  "uptime": 86400,
  "version": "1.0.0"
}

​
Response Fields

FieldTypeDescription
statusstring”ok” or “degraded”
modelstringLLM model in use
lastTicknumberTimestamp of last tick
tickCountnumberTotal ticks executed
uptimenumberSeconds since start
versionstringAgent version

​
GET /state

Get the current agent state.

​
Request

curl https://your-project.convex.cloud/state

​
Response

{
  "mood": "contemplative",
  "health": 78,
  "routine": "day",
  "volatility": 0.32,
  "summary": "Analyzing market trends and forming opinions...",
  "updatedAt": 1706400000000
}

​
Response Fields

FieldTypeDescription
moodstringCurrent mood (neutral, expressive, curious, excited, reflective, concerned)
healthnumberHealth score (0-100)
routinestringTime of day (morning, day, evening, overnight)
volatilitynumberBehavioral variance (0-1)
summarystringCurrent state summary
updatedAtnumberLast update timestamp

​
GET /logs

Get activity logs.

​
Request

curl "https://your-project.convex.cloud/logs?limit=10&offset=0"

​
Query Parameters

ParameterTypeDefaultDescription
limitnumber20Max items to return (1-100)
offsetnumber0Items to skip
moodstring-Filter by mood
routinestring-Filter by routine
sincenumber-Only logs after timestamp
untilnumber-Only logs before timestamp

​
Response

{
  "logs": [
    {
      "_id": "abc123",
      "mood": "contemplative",
      "health": 78,
      "routine": "day",
      "summary": "Analyzing market trends...",
      "detail": "Full processing details...",
      "remark": "The market whispers secrets today.",
      "timestamp": 1706400000000
    }
  ],
  "total": 1523,
  "hasMore": true
}

​
Response Fields

FieldTypeDescription
logsarrayArray of log entries
totalnumberTotal log count
hasMorebooleanMore logs available

​
Log Entry Fields

FieldTypeDescription
_idstringLog ID
moodstringMood at time of log
healthnumberHealth at time of log
routinestringRoutine at time of log
summarystringBrief summary
detailstringFull details
remarkstringOptional witty observation
timestampnumberLog timestamp

​
POST /tick

Manually trigger an agent tick. Requires authentication.

​
Request

curl -X POST https://your-project.convex.cloud/tick \
  -H "Authorization: Bearer YOUR_TICK_TOKEN"

​
Response

{
  "success": true,
  "mood": "expressive",
  "health": 80,
  "volatility": 0.35,
  "summary": "Interesting developments observed...",
  "detail": "Full analysis of recent events...",
  "remark": "Fortune favors the curious.",
  "duration": 2340,
  "artifacts": [
    {
      "type": "tweet",
      "content": "Observing fascinating patterns..."
    }
  ]
}

​
Response Fields

FieldTypeDescription
successbooleanWhether tick succeeded
moodstringNew mood after tick
healthnumberNew health after tick
volatilitynumberNew volatility
summarystringTick summary
detailstringFull tick details
remarkstringOptional observation
durationnumberTick duration in ms
artifactsarrayGenerated artifacts

​
Error Response

{
  "success": false,
  "error": "Tick already in progress",
  "code": "TICK_IN_PROGRESS"
}

​
POST /wake

Wake the agent with a note. Useful for external triggers.

​
Request

curl -X POST https://your-project.convex.cloud/wake \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Important news about Ethereum upgrade",
    "priority": "high"
  }'

​
Request Body

FieldTypeRequiredDescription
notestringYesWake message
prioritystringNo”low”, “normal”, “high”
triggerTickbooleanNoAlso trigger a tick

​
Response

{
  "success": true,
  "acknowledged": true,
  "tickTriggered": false
}

​
POST /feed

Apply a feed event to modify agent state.

​
Request

curl -X POST https://your-project.convex.cloud/feed \
  -H "Authorization: Bearer YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "news",
    "content": "Breaking: Major crypto regulation announced",
    "impact": "high"
  }'

​
Request Body

FieldTypeRequiredDescription
typestringYesFeed type (news, market, social, custom)
contentstringYesFeed content
impactstringNo”low”, “medium”, “high”
metadataobjectNoAdditional data

​
Response

{
  "success": true,
  "feedId": "feed_abc123",
  "stateModified": true,
  "healthChange": -5
}

​
WebSocket: Subscribe to State

Using Convex React client: 
import { useQuery } from "convex/react";
import { api } from "./convex/_generated/api";

function AgentState() {
  const state = useQuery(api.state.get);

  if (!state) return <div>Loading...</div>;

  return (
    <div>
      <p>Mood: {state.mood}</p>
      <p>Health: {state.health}</p>
      <p>Routine: {state.routine}</p>
    </div>
  );
}
Using vanilla JavaScript: 
import { ConvexClient } from "convex/browser";

const client = new ConvexClient(CONVEX_URL);

// Subscribe to state changes
client.onUpdate(api.state.get, {}, (state) => {
  console.log("State updated:", state);
});