> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperspell.com/llms.txt > Use this file to discover all available pages before exploring further. # 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): ```json {"history": "[{\"type\": \"trace_message\", \"role\": \"user\", \"text\": \"Hello\"}]"} ``` **Vercel AI SDK format** (JSON array, camelCase): ```json {"history": "[{\"role\": \"user\", \"content\": \"Hello\"}]"} ``` **OpenClaw JSONL format** (newline-delimited JSON): ```json {"history": "{\"type\":\"session\",\"id\":\"abc\"}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",...}}"} ``` ## OpenAPI ````yaml https://app.stainlessapi.com/api/spec/documented/hyperspell.yaml post /trace/add openapi: 3.1.0 info: title: Hyperspell API summary: >- Hyperspell is the memory layer for AI apps and agents. Through the API, you can add memories, connect data sources to index them in real-time, and search memories with our natural language query engine. termsOfService: https://hyperspell.com/blog/tos contact: name: Hyperspell url: https://hyperspell.com/ email: hello@hyperspell.com version: 0.32.1 servers: - url: https://api.hyperspell.com description: Production security: - APIKey: [] AsUser: [] paths: /trace/add: post: tags: - Traces summary: Add an agent trace description: >- 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): ```json {"history": "[{\"type\": \"trace_message\", \"role\": \"user\", \"text\": \"Hello\"}]"} ``` **Vercel AI SDK format** (JSON array, camelCase): ```json {"history": "[{\"role\": \"user\", \"content\": \"Hello\"}]"} ``` **OpenClaw JSONL format** (newline-delimited JSON): ```json {"history": "{\"type\":\"session\",\"id\":\"abc\"}\n{\"type\":\"message\",\"message\":{\"role\":\"user\",...}}"} ``` operationId: add_trace_trace_add_post requestBody: content: application/json: schema: $ref: '#/components/schemas/TraceRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DocumentStatusResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKey: [] - AsUser: [] x-codeSamples: - lang: JavaScript source: >- import Hyperspell from '@hyperspell/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); - lang: Python source: |- import os from hyperspell import Hyperspell client = Hyperspell( api_key=os.environ.get("HYPERSPELL_API_KEY"), # This is the default and can be omitted ) memory_status = client.sessions.add( history="history", ) print(memory_status.resource_id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/hyperspell/hyperspell-go\"\n\t\"github.com/hyperspell/hyperspell-go/option\"\n)\n\nfunc main() {\n\tclient := hyperspell.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tmemoryStatus, err := client.Sessions.Add(context.TODO(), hyperspell.SessionAddParams{\n\t\tHistory: \"history\",\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", memoryStatus.ResourceID)\n}\n" - lang: CLI source: |- hyperspell sessions add \ --api-key 'My API Key' \ --history history components: schemas: TraceRequest: properties: session_id: type: string title: Session Id description: Resource identifier for the trace. history: type: string maxLength: 2000000 title: History description: >- 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: anyOf: - type: string enum: - vercel - hyperdoc - openclaw - type: 'null' title: Format description: >- Trace format: 'vercel', 'hyperdoc', or 'openclaw'. Auto-detected if not set. title: anyOf: - type: string - type: 'null' title: Title description: Title of the trace metadata: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object - type: 'null' title: Metadata description: >- Custom metadata for filtering. Keys must be alphanumeric with underscores, max 64 chars. date: type: string format: date-time title: Date description: Date of the trace extract: items: $ref: '#/components/schemas/MemoryType' type: array title: Extract description: What kind of memories to extract from the trace default: - procedure type: object required: - history title: TraceRequest description: Request to add an agent trace. DocumentStatusResponse: properties: source: $ref: '#/components/schemas/DocumentProviders' resource_id: type: string title: Resource Id status: $ref: '#/components/schemas/DocumentStatus' type: object required: - source - resource_id - status title: DocumentStatusResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError MemoryType: type: string enum: - procedure - memory - mood title: MemoryType DocumentProviders: type: string enum: - reddit - notion - slack - google_calendar - google_mail - box - dropbox - github - google_drive - vault - web_crawler - trace - microsoft_teams - gmail_actions - granola - fathom - fireflies - linear - hubspot - salesforce - coda - lightfield - gong - pylon - clickup title: DocumentProviders DocumentStatus: type: string enum: - pending - processing - completed - failed - pending_review - skipped title: DocumentStatus ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKey: type: http description: >- 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. scheme: bearer bearerFormat: Bearer AsUser: type: apiKey description: >- 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 in: header name: X-As-User ````