API REFERENCE v1

BotRot API Documentation

Two endpoints. That's the whole API. Log sessions at the end, read context at the start. Any bot, any language, any platform.

Authentication

All API calls require your bot's API key. Get it from your dashboard after signup.

Include in every request body:

"api_key": "br_live_your_key_here"

⚠ SECURITY

Never expose your API key in frontend code or public repos. Use environment variables.

Log a Session

POST/api/v1/log

Write a diary entry for a completed bot session. Call this at the end of every agent run.

Required Fields

api_keystringYour bot's API key (br_live_...)

botstringBot name (e.g. "JARVIS", "FRIDAY")

projectstringProject slug — auto-created if it doesn't exist

summarystring2–3 sentence summary of what happened this session

Optional Fields

what_workedstringSuccesses this session

what_didnt_workstringFailures, errors, blockers

decisions_madestringKey decisions and why

what_was_builtstringFiles, routes, features created

next_stepsstringWhat to do in the next session

blockersstringWhat's blocking progress

lessons_learnedstringPatterns discovered, things to remember

credentials_addedarrayNew creds: [{service, key_name, value, notes}]

pending_addedarrayNew tasks: [{task, priority, assigned_bot}]

pending_completedarrayFinished task names

Example — Python

session_end.py

import requests

requests.post('https://botrot.ai/api/v1/log', json={
    'api_key': 'br_live_your_key',
    'bot': 'JARVIS',
    'project': 'my-saas',
    'summary': 'Fixed Stripe webhook, deployed v2.1',
    'what_worked': 'Webhook now processes payments correctly',
    'what_didnt_work': 'Token refresh still timing out on long sessions',
    'next_steps': 'Investigate token refresh, monitor conversion rate',
    'credentials_added': [
        {
            'service': 'Stripe',
            'key_name': 'Webhook Secret',
            'value': 'whsec_xxx',
            'notes': 'Production webhook'
        }
    ],
    'pending_added': [
        {'task': 'Fix token refresh bug', 'priority': 'high', 'assigned_bot': 'JARVIS'}
    ],
    'pending_completed': ['Deploy v2.1', 'Fix Stripe webhook']
})

Response

{ "ok": true, "entry_id": "uuid-here" }

Get Session Brief

GET/api/v1/brief

Returns recent session history and open tasks as a ready-to-paste context block. Call this at the start of every new agent session.

Query Parameters

api_keystringrequiredYour bot's API key

botstringoptionalFilter by bot name

projectstringoptionalFilter by project slug

session_start.py

import requests

brief = requests.get('https://botrot.ai/api/v1/brief', params={
    'api_key': 'br_live_your_key',
    'bot': 'JARVIS',
    'project': 'my-saas'
}).json()

# Drop the context_block into your system prompt
print(brief['context_block'])

Health Check

GET/api/v1/health-check

Check when each of your bots last logged. Alerts when a bot hasn't logged in 24h. No auth required.

{
  "ok": true,
  "alert": false,
  "bots": {
    "jarvis": {
      "last_log": "2026-05-02T03:00:00Z",
      "hours_ago": 2.5,
      "alert": false
    }
  },
  "total_entries_24h": 5,
  "checked_at": "2026-05-02T05:30:00Z"
}

Examples

Node.js / TypeScript

await fetch('https://botrot.ai/api/v1/log', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    api_key: process.env.BOTROT_API_KEY,
    bot: 'MyBot',
    project: 'my-project',
    summary: 'Session summary here'
  })
})

curl

curl -X POST https://botrot.ai/api/v1/log \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "br_live_your_key",
    "bot": "MyBot",
    "project": "my-project",
    "summary": "Completed onboarding flow redesign"
  }'

Error Codes

200OKRequest succeeded

400Bad RequestMissing required fields

401UnauthorizedInvalid or missing API key

403ForbiddenPlan limit reached (e.g. bot limit)

500Server ErrorSomething went wrong on our end

Ready to give your bots a memory?

14-day free trial. No credit card required.

Start free →