Add an agent trace

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

JavaScript

JavaScript

import Hyperspell from 'hyperspell';

const client = new Hyperspell({
  apiKey: process.env['HYPERSPELL_API_KEY'], // This is the default and can be omitted
});

const memoryStatus = await client.sessions.add({ history: 'history' });

console.log(memoryStatus.resource_id);

200

{
  "source": "reddit",
  "resource_id": "<string>",
  "status": "pending"
}

Authorizations

APIKeyAsUser

Authorization · string · header · required

API Key or JWT User Token. If using an API Key, set the X-As-User header to act as a specific user. A JWT User Token is always scoped to a specific user.

Body

application/json

Request to add an agent trace.

history · string · 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.

session_id · string

Resource identifier for the trace.

format · enum<string> | null

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

Available options: vercel, hyperdoc, openclaw

title · string | null

Title of the trace

metadata · Metadata · object

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

Show child attributes

date · string<date-time>

Date of the trace

extract · enum<string>[]

What kind of memories to extract from the trace

Available options: procedure, memory

Response

200

application/json

Successful Response

source · enum<string> · required

Available options: reddit, notion, slack, google_calendar, google_mail, box, dropbox, google_drive, github, vault, web_crawler, trace, microsoft_teams, gmail_actions

resource_id · string · required

status · enum<string> · required

Available options: pending, processing, completed, failed, pending_review, skipped