Report completed chargeable units

View as Markdown

POST /api/v1/usage · operationId recordCompletedUsage

For developers: your server sends this request with a server key; it is not a button in the dashboard.

Requires server-verified identity. Identical eventId/session/action/units reuse returns the original record with replayed=true, even after the browser session expired or was withdrawn (the eventId is checked before the token). New work needs a live session token, so report it within the 24-hour session life. Conflicting reuse returns 409 conflict. This records your attestation of completion; it does not independently verify work or charge money. No automatic retries.

Authentication

Send Authorization: Bearer YOUR_SERVER_KEY (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

Request body

Content-Type: application/json (required)

JSON
{
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "eventId": "event_00000001",
  "actionId": "export_report",
  "units": 1
}

Responses

Success body fields

Failures are not verdicts. Error bodies follow the Error schema: code is one of bad_request, unauthorized, session_reinit_required, forbidden, not_found, conflict, identity_required, payload_too_large, rate_limited, internal_error, service_unavailable, request_failed, approval_invalid, approval_used, approval_expired, approval_mismatch, step_up_not_held, step_up_mismatch, step_up_settled, step_up_expired, step_up_superseded, agent_tokens_disabled, tool_not_approved, tool_not_read_only. Errors and retries explains each code and what to do.

Example

curl
curl -sS -X POST 'https://app.trytelltale.dev/api/v1/usage' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"sessionToken":"PASTE_BROWSER_SESSION_TOKEN","eventId":"event_00000001","actionId":"export_report","units":1}'
fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/usage", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
    "eventId": "event_00000001",
    "actionId": "export_report",
    "units": 1
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
Node adapter
// server.js is the server adapter: download /adapters/v1/server.js (see Server adapters).
import { createTelltaleServer } from './lib/telltale/server.js';

const telltale = createTelltaleServer({ endpoint: "https://app.trytelltale.dev", serverKey: process.env.TELLTALE_SERVER_KEY });
const result = await telltale.recordUsage({
  "sessionToken": "PASTE_BROWSER_SESSION_TOKEN",
  "eventId": "event_00000001",
  "actionId": "export_report",
  "units": 1
});

Machine-readable contract: openapi.json. Request builder: the API explorer shows every operation as curl; it sends requests only on a local dashboard.