Skip to main content
This section is a pure reference. It holds exhaustive signatures, parameters, return values, and semantics for every public API across every Bitfab SDK. No narrative, no “how to use”, no walkthroughs. For tutorials and getting started, see the individual SDK guides: TypeScript, Python, Ruby, Go.

​
Pages

​
Instrumentation Primitives

The client exposes three instrumentation primitives, not just spans. A span is an explicit boundary you write yourself. A trace records a root plus every first-party call beneath it, with no decorators on those calls. A node applies trace-owned policy (name, type, capture, replay mocking) to one call the trace discovered, and never creates a span or trace on its own. Subtree capture is experimental. TypeScript needs a compatible @bitfab/transform adapter and Python needs 3.12 or newer. Without them the root span still records and descendants are skipped.

​
Trace Seeding

Seeding writes a replayable trace from a case you already hold, so replay has something to select before production has produced a trace for it. A seeded trace carries ingestion_type: seeded and no database pin, so a database branch is refused for it. Seeding records its one call whether capture is on or off, so a seeding script can run against a capture-off client and record exactly the calls it seeds and nothing else. A run-seeded trace has a full recorded subtree, so replay mocking works on it as it does on a captured trace. A case-seeded trace (TypeScript only) has no child spans, so there is nothing recorded to mock. See the TypeScript and Python guides.

​
Datasets

Every SDK exposes the dataset operations the Bitfab MCP tools give a coding agent. Scripts and CI jobs use them to build or maintain datasets with no agent in the loop. All four namespaces cover the same ten operations over the same HTTP routes. These semantics hold across all four SDKs.
  • save is an upsert. It reports whether it created the dataset.
  • Adds are idempotent and accept 1 to 100 ids.
  • An id from outside the organization, or under another trace function, comes back as skipped rather than failing the call.
  • Removing a trace drops its membership and never deletes the trace.
  • A grader re-run waits up to 90 seconds by default. Pass an option to return immediately instead.
  • A dataset id from another organization is a 404.
See Datasets.

​
Assertions and labels

An assertion says what a trace SHOULD do the next time it is replayed. A label is the verdict on a run that already happened. TypeScript and Python expose both. A replay process can read what the case was supposed to do, judge its own run, and write the verdict back, with no coding agent in the loop. Ruby and Go expose neither namespace. client.labels keys a replay verdict by attempt, and neither SDK has replay attempts, so there is nothing for the surface to express there. These semantics hold across TypeScript and Python.
  • Assertions are written against the original trace. A replay with none of its own reads its original’s assertions, naming that trace in inheritedFrom.
  • Saving with an entry’s id edits that assertion in place.
  • saveAssertionsAll / save_assertions_all takes one update per trace, so covering many traces is one request in one transaction. A rejected batch writes nothing. The singular delegates to it.
  • A field omitted from that save keeps its previous value.
  • Editing an assertion never changes its original author, which is always the API key’s user.
  • A verdict is keyed by traceId, or by originalTraceId plus testRunId and attempt for a replay.
  • skip withholds a verdict for a crashed or punctured attempt, and for an assertion whose target could not be resolved. A FAIL in either case would read as a behavior regression rather than a check that never ran.
Same HTTP routes as the MCP tools.

​
Replay execution and results

Every SDK returns a common set of fields on each replay result.
  • The replayed output and the original output.
  • Distinct trace-code and replay-setup errors.
  • Duration and token comparisons.
  • Source lineage.
  • Database branch metadata.
  • Original and replayed trace outlines.
A trace outline holds structure and measurements but no inputs or outputs, so graders can compare execution paths without reloading full trace payloads.

​
Framework Integrations

Per-framework signatures (handlers, processors, wrappers) are documented in the Frameworks section. Language-specific signatures are mirrored in each SDK reference’s Framework Integrations subsection.

​
Invariants Across SDKs

Behavior that is guaranteed to match across all SDKs:

​
Common Span Types

Every SDK accepts the same enum for span type:
See Span Types for full semantics.