Record calls to your own API (Telltale for APIs)

View as Markdown

POST /api/v1/api-calls · operationId recordApiCalls

For developers: your server sends this request with a server key; it is not a button in the dashboard. To see the same information without code, open Tools › All tools in the dashboard.

Shapes only: unknown fields are refused, never dropped, so no body, query value, header or credential can be stored. A call with agent evidence (agent token, Web Bot Auth signature, a declared name checked against its operator's IP list, an AI agent provider's published IP range, or a declared name) is one approved-route call with channel api, once per eventId; every other call is Unknown (never Human) and only counted per route and day. Sent by the API middleware (/adapters/v1/api.js; see Telltale for APIs).

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
{
  "framework": "express",
  "calls": [
    {
      "eventId": "call_00000001",
      "method": "GET",
      "route": "/v1/invoices/:id",
      "status": 200,
      "startedAt": 1794268800000,
      "endedAt": 1794268800085,
      "size": "1kb_10kb",
      "accountId": "acct_456"
    }
  ]
}

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/api-calls' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"framework":"express","calls":[{"eventId":"call_00000001","method":"GET","route":"/v1/invoices/:id","status":200,"startedAt":1794268800000,"endedAt":1794268800085,"size":"1kb_10kb","accountId":"acct_456"}]}'
fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/api-calls", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "framework": "express",
    "calls": [
      {
        "eventId": "call_00000001",
        "method": "GET",
        "route": "/v1/invoices/:id",
        "status": 200,
        "startedAt": 1794268800000,
        "endedAt": 1794268800085,
        "size": "1kb_10kb",
        "accountId": "acct_456"
      }
    ]
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();

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