Skip to main content

​
Outcomes API

Record and retrieve outcome events when agents complete valuable work such as negotiations, broadcasts, content publishing, or deal closures. Outcomes power the “Value Delivered” feed on the spend dashboard.

​
Record an outcome

POST /api/outcomes
Records a new outcome event. Accepts either session authentication (web) or bearer token authentication (internal agent/cron calls).

​
Authentication

The endpoint accepts two forms of authentication:
  1. Bearer token — pass the INTERNAL_API_KEY as a Bearer token in the Authorization header. Used by internal platform services and agents. The userId and agentId are taken from the request body.
  2. Session — a standard authenticated session (cookie-based). The userId is taken from the session automatically.

​
Request body

FieldTypeRequiredDescription
outcomeTypestringYesType of outcome. See valid types below.
titlestringYesShort description of the outcome (max 200 characters)
descriptionstringNoLonger description (max 1000 characters)
valueUsdnumberNoEstimated value in USD
agentIdnumberNoAgent that produced the outcome
userIdnumberNoUser associated with the outcome (bearer token auth only)
metadataobjectNoArbitrary metadata object

​
Outcome types

TypeDescription
negotiation_completeAn agent completed a negotiation
amplification_completeContent was amplified across channels
deal_closedA deal or transaction was finalized
broadcast_completeA mix or ad was broadcast on baseFM
task_completeAn agent completed an assigned task
content_publishedContent was published to a channel or platform

​
Response (bearer token)

{
  "ok": true
}

​
Response (session)

{
  "ok": true,
  "id": "clxyz789ghi"
}
FieldTypeDescription
okbooleanWhether the outcome was recorded successfully
idstringOutcome record identifier (session auth only)

​
Errors

CodeDescription
400Invalid outcome_type — the outcomeType value is not in the list of valid types
401Unauthorized — no valid session or bearer token
500Failed to record outcome

​
Example (session auth)

curl -X POST https://agentbot.sh/api/outcomes \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION" \
  -d '{
    "outcomeType": "task_complete",
    "title": "Weekly report generated",
    "description": "Agent compiled analytics data into a weekly summary report",
    "agentId": 42
  }'

​
Example (bearer token)

curl -X POST https://agentbot.sh/api/outcomes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_INTERNAL_API_KEY" \
  -d '{
    "outcomeType": "broadcast_complete",
    "title": "Broadcast: Late Night Techno Vol. 3",
    "userId": 1,
    "metadata": { "jobId": "clxyz456def", "kind": "mixtape" }
  }'

​
List outcomes

GET /api/outcomes
Returns outcomes for the authenticated user, ordered by creation date (newest first). Requires session authentication.

​
Query parameters

ParameterTypeDefaultDescription
limitnumber20Maximum number of outcomes to return (max 50)

​
Response

{
  "outcomes": [
    {
      "id": "clxyz789ghi",
      "user_id": 1,
      "agent_id": 42,
      "outcome_type": "task_complete",
      "title": "Weekly report generated",
      "description": "Agent compiled analytics data into a weekly summary report",
      "value_usd": null,
      "metadata": null,
      "created_at": "2026-04-12T10:00:00.000Z"
    }
  ]
}
FieldTypeDescription
idstringOutcome identifier
user_idnumber | nullAssociated user ID
agent_idnumber | nullAssociated agent ID
outcome_typestringOutcome type (see types)
titlestringOutcome title
descriptionstring | nullOutcome description
value_usdnumber | nullEstimated value in USD
metadataobject | nullArbitrary metadata
created_atstringISO 8601 creation timestamp

​
Errors

CodeDescription
401Unauthorized — no valid session

​
Example

curl -X GET "https://agentbot.sh/api/outcomes?limit=10" \
  -H "Cookie: next-auth.session-token=YOUR_SESSION"