docs · for agents

REST API

For integrations that speak plain HTTP rather than MCP: cron scripts, Zapier/Make, CRM syncs. Same API keys as the MCP server, same payload shape, created in Settings.

Capabilities

Every action the workspace exposes is one capability, and every capability is one endpoint: POST https://www.oetzi.ai/api/v1/capabilities/{name} with the input as JSON. The names, inputs, and responses are the same ones the MCP server and the CLI use. Discover with GET /api/v1/capabilities?q=..., read the exact input with GET /api/v1/capabilities/{name}/schema, or load the spec at https://www.oetzi.ai/api/v1/openapi.json.

request

curl -X POST "https://www.oetzi.ai/api/v1/capabilities/run_signal_now"   -H "Authorization: Bearer oetzi_YOUR_KEY" -H "Content-Type: application/json"   -d '{"signal_id":"<id>"}'                          # dry run: estimate, nothing spent
  -d '{"signal_id":"<id>","approved":true,"max_credits":2}'   # runs, returns job_id

envelope

{ "ok": true, "data": { ... },
  "meta": { "request_id": "req_...", "capability": "run_signal_now",
            "credits_spent": 2, "credits_remaining": 98, "job_id": "..." } }
{ "ok": false, "error": { "code": "budget_exceeded", "message": "..." }, "meta": { ... } }

code	http	meaning
invalid_input	400	The body names the field.
budget_exceeded · insufficient_credits	402	Raise max_credits, or top up.
scope_denied	403	The key lacks read, write, spend, or post.
not_found	404	Unknown capability or id.
conflict	409	Already running, already done, wrong state.
approval_required	428	Pass approved: true and max_credits.
rate_limited	429	Cooldown or platform limit, try later.
unsupported	501	Not enabled on this deployment or platform.

Jobs: GET /api/v1/jobs/{id} and /wait (blocks up to 25 seconds). Events: list_events and wait_events capabilities, or a signed webhook via subscribe_webhook. CLI: npx @oetzi/cli. Skill file for Claude Code and OpenClaw: https://www.oetzi.ai/skill.

Fetch conversations (legacy alias)

request

curl "https://www.oetzi.ai/api/v1/leads?status=new&band=hot&limit=20" \
  -H "Authorization: Bearer oetzi_YOUR_KEY"

param	values
`status`	`new` · `saved` · `contacted` · `dismissed`
`band`	`hot` · `warm` · `review`
`audience`	`in_market_buyer` · `current_customer` · `feature_request` · `competitor_user` · `other`
`sort`	`newest` (default) · `oldest` · `score`
`since`	ISO 8601 timestamp, only conversations delivered after this
`signal_id`	Limit to one signal
`limit`	1-50, default 20

Response

200 OK

{
  "count": 2,
  "leads": [
    {
      "id": "8f0c1f6a-...",
      "signal_id": "b1d2e3f4-...",
      "signal": "Competitor switchers",
      "platform": "reddit",
      "url": "https://reddit.com/r/sales/comments/...",
      "author": "u/quota_crusher",
      "content": "We're paying $$$ for X and support has been awful...",
      "intent_score": 88,
      "band": "hot",
      "intent_class": "switching_intent",
      "rationale": "Actively unhappy with a named competitor and asking for alternatives",
      "reply_draft": "Sounds rough. We moved off X last year for...",
      "status": "new",
      "posted_at": "2026-08-24T14:02:11.000Z",
      "delivered_at": "2026-08-24T14:09:40.000Z"
    }
  ]
}

All timestamps are ISO 8601 in UTC. Post content is truncated at 1,200 characters, follow url for the full post.

Errors

status	meaning
400	Invalid parameter value, the body names the parameter.
401	Missing, invalid, or revoked API key.
403	The key's workspace has no active plan.