OcomxDeveloper API
Introduction
The Ocomx API turns a plain-language outcome ("Reduce supplier MOQ from 1,000 to 300") into a parsed task, an explainable negotiation strategy, an execution plan, and a (simulated) execution timeline you can watch or intervene in. It is a clean REST surface you can embed in your own product, CRM, or workflow.
Execution on this API is simulated by a controlled counterparty so you can build and test end-to-end without live calls, emails, or costs. To go live, swap the executor/email/call adapters — the request/response contract stays identical.
Authentication
The demo uses a lightweight token returned by /api/auth/signup or /api/auth/login. Include it as:
- Auth endpoints (signup/login): send
tokenis returned in the response body. - User endpoints (
/api/user/me,/api/user/tasks,/api/admin/users): pass the token as a query parameter?token=…. - Task creation (
/api/plan): include"token": "…"in the JSON body to associate the task with the user.
In production, use Authorization: Bearer <token> on every request and hash passwords server-side. The endpoints accept both forms today for backwards compatibility with the demo.
Base URL & errors
All responses are JSON. Success uses HTTP 200; client errors use 400/401/403/404 with { "error": "message" }.
GET https://ocomx.com/api/categories
Authorization: Bearer <token> # recommended in production
{ "success": false, "error": "not authenticated" }GET /api/categories
List supported task categories and cross-cutting capabilities (used to render the console sidebar).
GET /api/categories
{
"categories": [
{ "id":"bill_negotiation", "name":"Bill Negotiation", "icon":"bill",
"examples":["Negotiate my Verizon wireless bill down"],
"needed":["provider","currentRate"], "baseSuccess":0.93 }
],
"features": [
{ "id":"follow_up", "name":"Persistent Follow-Up", "icon":"follow",
"blurb":"Tracks open loops and follows up automatically." }
]
}POST /api/parse
Parse free text into a structured task (category, entities, hypothesis).
POST /api/parse
{ "text": "Reduce supplier MOQ from 1000 to 300", "role": "buyer" }
{ "parsed": {
"category":"business_negotiation",
"entities":{ "current":1000, "target":300 },
"hypothesis":{ "category":"business_negotiation",
"evidence":"mentions MOQ 1000→300", "confidence":0.82 }
} }POST /api/plan
Parse + build an execution plan. For negotiation tasks it also returns the explainable KK strategy layer. Creates a task and returns taskId.
POST /api/plan
{ "text":"Customer wants a 20% price cut — defend margin",
"role":"seller", "acceptable":"max 10%",
"current":100, "target":80, "max":90,
"token":"<optional user token>" }
{ "taskId":"P00012",
"parsed":{ … },
"plan":{ "objective":"…", "steps":[ … ], "confidence":0.78,
"risks":[ … ], "alternativeStrategy":"…" },
"pineAddress":"[email protected]",
"kkLayer":{ "you":{ "persistence":{ "score":72, "confidence":"Medium",
"evidence":"…" } },
"counterparty":{ "priceSensitivity":{ "level":"High", … } },
"strategy":{ "objective":"…", "evidence":[ … ],
"strategy":"…", "risks":[ … ], "alternativeStrategy":"…",
"confidence":"Medium" },
"relationship":{ "type":"…", "evidence":"…" } } }kkLayer is only returned for negotiation-relevant tasks (heuristic match on category or keywords: moq/price/terms/discount/rate/negotiat/reduce/lower/extend).
POST /api/strategy
Return only the KK strategy layer for a piece of text (lightweight, no task created).
POST /api/strategy
{ "text":"Negotiate 20% lower price", "role":"buyer",
"current":100, "target":80, "max":90 }
{ "you":{ … }, "counterparty":{ … }, "strategy":{ … },
"relationship":{ "type":"…", "evidence":"…" } }POST /api/execute
Run the (simulated) execution timeline for a created task. Returns the timeline and outcome.
POST /api/execute
{ "taskId":"P00012", "seed":"demo" }
{ "taskId":"P00012",
"timeline":[ { "kind":"email", "action":"draft", "text":"…", "atMin":0 },
{ "kind":"negotiate", "channel":"email", "text":"…", "atMin":12 } ],
"outcome":{ "status":"success", "amount":null,
"detail":"Counterparty agreed to revised terms.",
"metrics":{ "success":true, "timeSavedMin":240 } },
"totalMinutes":48 }POST /api/intervene
Human intervention mid-task. Appends user + agent-adaptation nodes; can flip a stalled case to success (demo behavior).
POST /api/intervene
{ "taskId":"P00012", "message":"Push harder on the volume commitment." }
{ "taskId":"P00012",
"appended":[ { "kind":"user", "action":"intervene", "text":"…" },
{ "kind":"agent", "action":"adapt", "text":"…" } ],
"outcome":{ "status":"success", "detail":"Resolved after your intervention." } }GET /api/metrics
Aggregate demo metrics (success rate, avg savings, time saved).
GET /api/metrics
{ "successRate":0.80, "avgSavingsPct":0.18, "avgTimeSavedMin":247, "tasks":42 }GET /api/kkpresets
Preset negotiation scenarios for the A/B page (carries explicit current/target/max + counterparty overrides).
GET /api/kkpresets
{ "presets":[ { "title":"Supplier MOQ cut", "text":"Reduce supplier MOQ from 1000 to 300",
"role":"buyer", "current":1000, "target":300, "max":500,
"counterpartyOverrides":{ "priceSensitivity":"High" } } ] }POST /api/ab
Run the KK-vs-Generic A/B. Returns verdict, the KK layer, per-metric bars, and sample timelines for both arms.
POST /api/ab
{ "text":"Reduce supplier MOQ from 1000 to 300", "role":"buyer",
"runs":10, "current":1000, "target":300, "max":500 }
{ "hypothesisSupported":true, "runs":10,
"generic":{ "successRate":0.42, "positiveReplyRate":0.51, … },
"kk":{ "successRate":0.80, "positiveReplyRate":0.88, … },
"lift":{ "successRate":0.38, "positiveReplyRate":0.37, "humanInterventionRate":-0.21 },
"layer":{ … }, "sample":{ "generic":[ … ], "kk":[ … ] } }POST /api/auth/signup
POST /api/auth/signup
{ "email":"[email protected]", "password":"secret", "name":"You" }
{ "token":"<token>", "user":{ "email":"[email protected]", "name":"You", "tier":"Free", "isAdmin":false } }POST /api/auth/login
POST /api/auth/login
{ "email":"[email protected]", "password":"secret" }
{ "token":"<token>", "user":{ … } }GET /api/user/me
GET /api/user/me?token=<token>
{ "user":{ "email":"[email protected]", "name":"You", "tier":"Free", "isAdmin":false, "createdAt":1234567890 } }GET /api/user/tasks
GET /api/user/tasks?token=<token>
{ "tasks":[ { "id":"P00012", "text":"Reduce supplier MOQ…", "status":"done",
"category":"business_negotiation", "createdAt":1234567890 } ] }GET /api/admin/users
Admin only (seat: [email protected]). Lists all users with task counts.
GET /api/admin/users?token=<admin-token>
{ "users":[ { "email":"[email protected]", "name":"You", "tier":"Free",
"isAdmin":false, "tasks":3, "createdAt":1234567890 } ] }Typical flow
POST /api/auth/login→ storetoken.POST /api/planwith the user's text (+token) → showplan+kkLayerin your UI; let the user approve.POST /api/executewithtaskId→ streamtimelineinto your activity view.- On user input,
POST /api/interveneto adapt and continue. GET /api/user/tasksto list the user's history.
JS example
const r = await fetch('/api/plan', {
method:'POST',
headers:{ 'Content-Type':'application/json' },
body: JSON.stringify({ text:'Reduce supplier MOQ from 1000 to 300',
role:'buyer', token: localStorage.getItem('ocomx_token') })
}).then(r => r.json());
console.log(r.plan.objective, r.kkLayer?.strategy?.strategy);
const ex = await fetch('/api/execute', {
method:'POST', headers:{ 'Content-Type':'application/json' },
body: JSON.stringify({ taskId: r.taskId })
}).then(r => r.json());
console.log(ex.outcome.status);