Traces

Add an agent trace

Changed on

Add an agent trace/transcript to the index.

Accepts traces as a string in Hyperdoc format (native), Vercel AI SDK format, or OpenClaw JSONL format. The format is auto-detected if not specified.

Hyperdoc format (JSON array, snake_case with type discriminators):

{"history": "[{\"type\": \"trace_message\", \"role\": \"user\", \"text\": \"Hello\"}]"}

Vercel AI SDK format (JSON array, camelCase):

{"history": "[{\"role\": \"user\", \"content\": \"Hello\"}]"}

OpenClaw JSONL format (newline-delimited JSON):

{"history": "{\"type\":\"session\",\"id\":\"abc\"}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",...}}"}
post/trace/add

Request

  • Base URL
    https://api.hyperspell.com
  • URL
    https://api.hyperspell.com/trace/add
  • Auth
    HTTP bearer

Headers

X-As-Userstring nullable

Optionally set this header to act as a specific user when using an API Key, equivalent to first exchanging the API Key for a User Token

Request body

session_idstring

Resource identifier for the trace.

historystring required

The trace history as a string. Can be a JSON array of Hyperdoc steps, a JSON array of Vercel AI SDK steps, or OpenClaw JSONL.

format'vercel' | 'hyperdoc' | 'openclaw' nullable

Trace format: 'vercel', 'hyperdoc', or 'openclaw'. Auto-detected if not set.

titlestring nullable

Title of the trace

metadataobject nullable

Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars.

datestring date-time

Date of the trace

extractMemoryType[]

What kind of memories to extract from the trace

Response

Successful Response

source'reddit' | 'notion' | 'slack' | 'google_calendar' | 'google_mail' | 'imap' | 'google_meet' | 'box' | 'dropbox' | 'github' | 'gitlab' | 'google_drive' | 'vault' | 'web_crawler' | 'trace' | 'microsoft_outlook' | 'microsoft_teams' | 'granola' | 'fathom' | 'fireflies' | 'figma' | 'linear' | 'hubspot' | 'salesforce' | 'coda' | 'confluence' | 'jira' | 'metabase' | 'gong' | 'clickup' | 'lightfield' | 'pylon' | 'fellow' | 'odoo' | 'external_mcp' | 'page' required
resource_idstring required
status'pending' | 'processing' | 'completed' | 'failed' | 'pending_review' | 'skipped' | 'filtered' | 'cancelled' required

Changes