​
Trace format

SellTraces normalizes source-specific conversations into a shared trace shape before ingest. The public API accepts normalized JSON traces through POST /api/ingest.

​
Minimal accepted shape

Each trace must include a source, source id, creation time, and messages.
The generated OpenAPI reference documents the accepted request body for POST /api/ingest.

​
Supported sources

The current normalized source values are:

​
Extended fields

The ingest package also supports richer V2 trace metadata when a source can provide it:
  • schemaVersion, conversationId, sessionId, parentTraceId
  • provider, client, agent, modelVersion
  • systemPrompt, toolsAvailable, contentBlocks
  • environment with cwd, git, OS, shell, permission, and sandbox fields
  • timing and usage details
  • outcome and trajectory details for coding-agent sessions
  • consent, license, piiScrub, and originalHash provenance fields
  • quality, domain, language, difficulty, and task metadata
When these fields are absent, the server fills what it can during normalization, scoring, and ingest.

​
Long sessions

A session too large for one upload request is split into consecutive segments at message boundaries. Segment k (from 1) has sourceId <session sourceId>#k, segmentIndex k, and parentTraceId set to the session. Boundaries depend only on the messages before them, so as a session grows its earlier segments stay identical and only the last one changes. A single message too large on its own keeps a prefix of its text, ending with a [selltraces truncated N characters] marker, and has truncated: true.

​
Message roles

Messages use one of:
  • system
  • user
  • assistant
  • tool
content is the plain text used for token counts, search, dedupe, and generated OpenAPI validation. Rich sources may also include structured contentBlocks.

​
Deduplication fields

source plus sourceId provides source-level idempotency. originalHash provides content-level dedupe. If originalHash is absent, the server computes a hash from normalized role/content text. Within one ingest batch, duplicate source keys or duplicate content hashes are rejected before DB insert. Across persisted traces, duplicates refresh nullable metadata on the canonical trace instead of creating another trace row. The exception is a session that grew since it was stored: an upload with the same source key and more messages, whose first messages hash to the stored originalHash, replaces the content of the stored trace unless it has been sold.