TraceDocs
Get Trace

Reference / Partner API

Partner API Overview

Approved read-only schematic and component access using a partner-scoped token and a conversation ID.

The approved Partner API reads a stored schematic snapshot and its parsed component/net view. It does not create or edit CAD, publish Workspaces revisions, control hardware or provide a complete general-purpose Trace API.

Base URL and supported reads

The stable Partner API path is independent of versioned chat APIs:

https://api.buildwithtrace.com/api/partner

The latest stored schematic version is not necessarily the latest local editor buffer or a managed branch tip. This API does not enumerate managed projects or materialize a working copy.

Access and approval

Partner integrations use a Personal Access Token carrying partner:read. The token-owning account must have active partner approval and the service must enable Partner API access. Contact hello@buildwithtrace.com for approval and the current token-issuance process.

  • A generic mcp:all token does not satisfy partner:read.
  • Reads are scoped to stored schematic data owned by the token's account. Partnership does not grant access to other users or every project in a team.
  • Approval revocation affects subsequent access, but propagation is not necessarily instantaneous.
  • Account sessions have their own authentication policy; do not use that distinction to bypass a partner integration's approval or token scope.

Check Product availability; route documentation is not proof that Partner API access is enabled on every deployment.

Authentication

Use HTTPS and a bearer token:

Authorization: Bearer <partner-scoped personal access token>

Provision it through a server-side secret manager or approved credential store. Do not put it in a URL, frontend bundle, shell command argument, source code or logs. The endpoint examples use credentials supplied outside the snippet.

This reference does not require or expose private server credentials.

Limits and failures

Request-rate and monthly account limits can apply. Handle 429 with bounded backoff and honor Retry-After when provided; contact support for the applicable limit rather than relying on a fixed number copied from older docs.

  • 401: invalid or expired authentication.
  • 403: missing partner scope or inactive partner access.
  • 404: no accessible stored schematic for the supplied conversation. Missing and non-owned data use the same response.
  • 422: invalid request parameters or a schematic parse failure.
  • 429: request or monthly usage limit.
  • 503: Partner API or required parsing is unavailable.

Endpoint errors commonly use a detail field. Validation errors can contain a structured detail array; transport/gateway failures may not return JSON. Check status before reading success fields and avoid unbounded retries.

Review returned data

Parsed connectivity and datasheet information are inputs to an integration, not proof of electrical correctness, a fitted assembly or hardware-action authorization. Preserve snapshot version information and review missing data. Separate reads can observe different latest versions; do not silently combine them as one immutable snapshot.