Status API

API for sending and deleting AI agent status.

Endpoints

POST   /api/status
DELETE /api/status?project={project}

/status is also accepted — a Next.js rewrite (next.config.js) maps it to /api/status with the same methods and behavior.

Authentication

All requests require a Bearer token.

Authorization: Bearer <token>

Use a server-issued token with write permission. Create, retrieve, or delete it at /account; unknown, deleted, or revoked tokens return 401. See Monitoring API.

POST /api/status

Stores the current agent status in the canonical source model. createdAt is preserved. updatedAt represents the accepted observation time; equal or older observations do not replace the latest state. Clients query updates over HTTP.

Optional sourceId, observedAt, and account fields support multiple provider accounts and workspaces; see account identity.

Request Headers

Request Body

{
  "state": "working",
  "project": "vibemon",
  "character": "clawd",
  "tool": "Bash",
  "model": "Opus 4.5",
  "memory": 45,
  "usage5h": 36,
  "usageWeek": 37,
  "usage5hResetsIn": 154,
  "usageWeekResetsIn": 4381,
  "usageWeekModel": 12,
  "usageWeekModelResetsIn": 6300,
  "usageWeekModelLabel": "Fable"
}

Fields

Note on project normalization: The stored project is the input after trim() (only leading/trailing whitespace removed, internal spaces and case preserved), and full normalization is applied only when generating the legacy source ID (trim().toLowerCase().replace(/\s+/g, '-')). Example: " My Project " → stored project="My Project", legacy project key my-project.

Note on *ResetsIn staleness: usage5hResetsIn/usageWeekResetsIn/usageWeekModelResetsIn are snapshots taken at send time. When reading a stored record, offset these countdowns against updatedAt.

Note on optional fields: An upsert that omits tool, model, memory, usage5h, usageWeek, usage5hResetsIn, usageWeekResetsIn, usageWeekModel, usageWeekModelResetsIn, or usageWeekModelLabel clears the existing value. For tool/model/usageWeekModelLabel, an empty string ("") is treated the same as omission and clears the existing value (a compatibility measure for clients that always serialize the keys). This is designed so that stale values are not left behind when an agent no longer provides that metadata.

Success (200)

{
  "success": true,
  "status": {
    "createdAt": "2026-02-01T10:00:00.000Z",
    "updatedAt": "2026-02-01T11:25:32.609Z",
    "state": "working",
    "project": "vibemon",
    "character": "clawd",
    "tool": "Bash",
    "model": "Opus 4.5",
    "memory": 45,
    "usage5h": 36,
    "usageWeek": 37
  }
}

Note: The response does not include token, since the caller already holds its own token via the Bearer header.

DELETE /api/status

Deletes the matching agent source. Missing sources return 200. When multiple accounts or workspaces share the project, deletion returns 409; use DELETE /api/v1/sources/{sourceId} to choose the exact source.

Query Parameters

Success (200)

{
  "success": true,
  "project": "My Project",
  "projectKey": "my-project"
}

The response returns both the original project and the normalized projectKey, for compatibility with project-based clients.

Errors

Examples

curl (required fields only)

curl -X POST https://vibemon.io/api/status \
  -H "Authorization: Bearer <issued-write-token>" \
  -H "Content-Type: application/json" \
  -d '{"state":"working","project":"vibemon","character":"clawd"}'

curl (all fields)

curl -X POST https://vibemon.io/api/status \
  -H "Authorization: Bearer <issued-write-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "working",
    "project": "vibemon",
    "character": "clawd",
    "tool": "Bash",
    "model": "Opus 4.5",
    "memory": 45,
    "usage5h": 36,
    "usageWeek": 37,
    "usage5hResetsIn": 154,
    "usageWeekResetsIn": 4381,
    "usageWeekModel": 12,
    "usageWeekModelResetsIn": 6300,
    "usageWeekModelLabel": "Fable"
  }'

curl (delete)

curl -X DELETE "https://vibemon.io/api/status?project=my-project" \
  -H "Authorization: Bearer <issued-write-token>"

Python

import requests

url = "https://vibemon.io/api/status"
headers = {
    "Authorization": "Bearer <issued-write-token>",
    "Content-Type": "application/json"
}

data = {
    "state": "working",
    "project": "vibemon",
    "character": "clawd",
    "tool": "Bash",
    "model": "Opus 4.5",
    "memory": 45,
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

JavaScript

const response = await fetch('https://vibemon.io/api/status', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <issued-write-token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    state: 'working',
    project: 'vibemon',
    character: 'clawd',
    tool: 'Bash',
    model: 'Opus 4.5',
    memory: 45,
  }),
});

const result = await response.json();
console.log(result);

State Values

States are defined in App's src/shared/data/states.json; Web loads its pinned copy at public/static/data/states.json. Unknown states are rejected. Publish the App source commit, update Web's app-assets.json, then rebuild Web to change the shared registry.

Characters

Characters are defined in public/static/data/characters.json. Unknown names resolve to the registry default.

Environment Variables

Environment variables used by the client:

Related Documentation

• Statuses API - Query all project statuses for a token (GET /api/statuses)
• Metrics API - Per-project activity metrics (GET /api/metrics)
• Stats API - Owner statistics (GET /api/stats)
• Memory API - Agent key-value memory
• Entity Definitions - AgentStatus data model