How Do I Log AI Agent Actions With a REST API Call?
Log agent actions with a REST API call: one POST to WaveBrain with curl, the fields and status codes, plus cron, GitHub Actions and n8n examples.
Reviewed by WaveBrain Operations TeamReviewed 6 min readPublished
The short answer
To log an AI agent action with a REST API call, send a JSON POST to https://getwavebrain.com/api/v1/actions with your API key as a Bearer token and at least an agent, a type and a title. One curl command is enough, and it works from any script, cron job, CI step or automation tool that can send HTTP. A 201 response means the action is in your WaveBrain timeline.
Not every agent speaks MCP. The nightly job that generates offer codes is a Python script, the deploy runs in GitHub Actions, and the lead-routing flow lives in n8n. They all do things you'd want on record, and none of them can call an MCP tool.
They can all send an HTTP POST, though. WaveBrain's REST endpoint takes the same fields as the log_action MCP tool, so a script and a Claude Code session end up in the same timeline.
How do I log an AI agent action with a REST API call?#
Send a POST to https://getwavebrain.com/api/v1/actions with an Authorization: Bearer header carrying your WaveBrain API key and a JSON body. This is the example from the WaveBrain homepage:
curl -X POST https://getwavebrain.com/api/v1/actions \
-H "Authorization: Bearer $WAVEBRAIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "offers-script",
"type": "api_call",
"title": "Generated 500 one-time offer codes",
"project": "northwind/growth",
"status": "success"
}'
A successful call returns 201 with { "id": ... }. Get the key from the API keys page after you sign up free, and keep it in an environment variable rather than in the script. The same key works for MCP clients, so you can see this entry next to what your coding agents logged (see how it works).
What fields does the actions endpoint accept?#
Three fields are required (agent, type and title), and the rest are optional. Write the title as a short past-tense sentence, the way you'd write a commit message, and put what changed, why and the result in details.
| Field | Required | Format | Example |
|---|---|---|---|
agent | Yes | String, up to 64 chars, stored lowercase | "offers-script" |
type | Yes | One of the 14 action types below | "api_call" |
title | Yes | Short past-tense sentence, up to 200 chars | "Generated 500 one-time offer codes" |
details | No | Up to 10,000 chars | "Batch for the November promo, expires Dec 1" |
project | No | String, up to 200 chars | "northwind/growth" |
url | No | A full URL | "https://github.com/acme/web/actions/runs/123" |
status | No | success, failure or pending (default success) | "failure" |
session_id | No | UUID from an MCP start_session call | "3f2c..." |
metadata | No | JSON object | {"host": "vps-1", "rows": 500} |
The 14 action types are commit, push, pull_request, merge, deploy, release, publish, email, message, file_change, command, database, api_call and other. Don't put secrets in any field. WaveBrain doesn't filter text you send yourself, so treat an entry like a commit message.
What status codes can the endpoint return?#
The endpoint returns 201 when the action is stored and a 4xx code when it isn't. Your script should check for 201 and treat everything else as "not logged", without failing the job it is reporting on.
| Code | Meaning | What to do |
|---|---|---|
| 201 | Action stored, body is { "id": ... } | Nothing |
| 400 | Validation error (missing field, unknown type, bad URL) | Fix the body; the response lists the problem |
| 401 | Invalid API key | Check the key and the Bearer prefix |
| 402 | Monthly action quota reached | New actions are rejected until next month; history is kept |
| 429 | Rate limit of 120 requests per minute per workspace | Wait for the seconds in the Retry-After header, then retry |
On the free plan the quota is 1,000 actions a month. Pro is coming with 50,000.
How do I log a cron job's result?#
Wrap the job so both outcomes send a log. The script below runs the job, sets the status from its exit code and posts the result. The || true and --max-time keep a slow or failed log call from breaking the cron run.
#!/usr/bin/env bash
# /opt/jobs/sync-offers.sh, run from crontab: 0 3 * * * /opt/jobs/sync-offers.sh
if python3 /opt/jobs/sync_offers.py > /tmp/sync-offers.log 2>&1; then
status=success; title="Synced offer codes to Shopify"
else
status=failure; title="Offer code sync to Shopify failed"
fi
jq -n --arg s "$status" --arg t "$title" --arg d "$(tail -c 2000 /tmp/sync-offers.log)" \
'{agent: "offers-cron", type: "api_call", title: $t, details: $d, project: "northwind/growth", status: $s}' |
curl -s --max-time 10 -X POST https://getwavebrain.com/api/v1/actions \
-H "Authorization: Bearer $WAVEBRAIN_API_KEY" \
-H "Content-Type: application/json" -d @- || true
Cron runs with a minimal environment, so set WAVEBRAIN_API_KEY in the crontab or source it in the script. With a Slack channel connected, the failure branch also posts an alert (more in Slack alerts for agent failures).
How do I log from a GitHub Actions step?#
Store the key as a repository secret and add a final step that runs whether the job passed or failed. GitHub's docs show secrets passed to a step as environment variables with ${{ secrets.NAME }}, and the if: ${{ !cancelled() }} condition runs a step regardless of earlier failures (GitHub recommends it over always()).
- name: Log deploy to WaveBrain
if: ${{ !cancelled() }}
env:
WAVEBRAIN_API_KEY: ${{ secrets.WAVEBRAIN_API_KEY }}
JOB_STATUS: ${{ job.status }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: |
if [ "$JOB_STATUS" = "success" ]; then s=success; else s=failure; fi
jq -n --arg s "$s" --arg u "$RUN_URL" --arg sha "$GITHUB_SHA" \
'{agent: "ci-deploy", type: "deploy", title: ("Deployed " + $sha[0:7] + " to production"), project: "northwind/web", url: $u, status: $s}' |
curl -s --max-time 10 -X POST https://getwavebrain.com/api/v1/actions \
-H "Authorization: Bearer $WAVEBRAIN_API_KEY" \
-H "Content-Type: application/json" -d @- || true
For a failure-only log, use if: ${{ failure() }}, which GitHub's expressions reference says returns true when any previous step of the job fails. The url field links each entry back to the run.
How do I log from an n8n HTTP Request node?#
Add an HTTP Request node at the end of the workflow, set it to POST to the actions endpoint, and send a JSON body. The n8n docs say the node can import a curl command (Import cURL on the Parameters tab), so the quickest route is to paste the curl example above and edit the fields.
To set it up by hand:
- Method
POST, URLhttps://getwavebrain.com/api/v1/actions. - Authentication with a generic Header Auth credential, name
Authorization, valueBearer <YOUR_API_KEY>. - Turn on Send Body, content type JSON, and set
agent,type,title,projectandstatus, using expressions for values from earlier nodes, such as the post URL a publish step returned.
Put a second node on the workflow's error path with "status": "failure" if you want failed runs logged too.
Can I read actions back over REST?#
No. The REST API is write-only, and there is no list or read endpoint. You read history in the dashboard, or from an MCP client with the list_actions and list_recent_actions tools. If a script needs to check what already happened before it runs, give that job to an MCP-connected agent.
WaveBrain is also not a tracing tool. It won't record tokens, latency or prompts from your scripts, only the actions you send.
If you have scripts, cron jobs or workflows doing work nobody can see, try WaveBrain free and add one POST to the end of each. The free plan includes 1,000 actions a month with no credit card.
Frequently asked questions#
Which fields are required in the REST call?#
agent, type and title. Everything else, including details, project, url, status, session_id and metadata, is optional.
What is the rate limit for the actions endpoint?#
120 requests per minute per workspace. Above that the endpoint returns 429 with a Retry-After header.
What happens when I hit the monthly limit?#
The endpoint returns 402 and new actions are rejected until next month. Your existing history is kept.
Can I use the same API key for REST and MCP?#
Yes. The same key works for both, and actions from both land in the same timeline.
Does the REST endpoint redact secrets?#
No. WaveBrain stores what you send, so keep tokens and passwords out of titles, details and metadata.