Tradecraft API

Available after launch

The API is built, but api.tradecrafthub.ai is not live yet. It opens when Tradecraft moves to its tradecrafthub.ai addresses. These pages describe the API as it will work then.

The Tradecraft API lets your scripts, integrations and apps work with your organization’s questionnaires and knowledge: list and upload assessments, run Analyze and Process, edit answers in Review, read approved answers, ask security questions, propose new answers and export audit events.

• One address for every organization. Your organization is never in the URL or a header. It comes from the access token: each token is bound to one organization.
• Standard OAuth 2. Machine clients use client credentials; apps that act for a person use the authorization code flow with PKCE. There are no static API keys.
• Stable. The API is versioned in the path (/v1) and only grows within a version. See Versioning.

Plans

The API is part of the Enterprise plan. On a trial, Starter or Pro, the token endpoint refuses to issue tokens and API calls answer 403 PLAN_FEATURE_UNAVAILABLE. See Pricing.

Base URLs

• Production: https://api.tradecrafthub.ai/v1
• Local development (app on its own hosts): https://api.tradecraft.local:3000/v1
• Local development (app on one host): http://localhost:3000/v1

The OAuth issuer is the same host without /v1 (https://api.tradecrafthub.ai). Its endpoints are /oauth/authorize, /oauth/token and /oauth/revoke; discovery documents are at /.well-known/oauth-authorization-server (RFC 8414) and /.well-known/oauth-protected-resource (RFC 9728). The OpenAPI 3.1 description is public at /v1/openapi.json and drives the reference.

Before you start

1. An admin turns the API on: Admin → API → Settings → Allow the Tradecraft API. It is off until an admin enables it; while it is off, calls answer 403 API_DISABLED.
2. An admin registers a client in Admin → API → Clients → New API client: a Machine client for scripts and integrations, or a Public app / Confidential app for apps that act for people.
3. People who connect an app for themselves need the role permission Connect apps to the API on my behalf and must turn on Settings → Connected apps → Allow apps and AI tools to act for me.

Your first call

With a machine client’s id and secret, get a token and ask who you are:

TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d "scope=assessments:read knowledge:read" \
  https://api.tradecrafthub.ai/oauth/token | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" https://api.tradecrafthub.ai/v1/me
curl -s -H "Authorization: Bearer $TOKEN" "https://api.tradecrafthub.ai/v1/assessments?limit=5"

const base = "https://api.tradecrafthub.ai"
const basic = btoa(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`)

const tokenRes = await fetch(`${base}/oauth/token`, {
  method: "POST",
  headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({ grant_type: "client_credentials", scope: "assessments:read knowledge:read" }),
})
const { access_token } = (await tokenRes.json()) as { access_token: string }

const me = await fetch(`${base}/v1/me`, { headers: { Authorization: `Bearer ${access_token}` } })
console.log(await me.json()) // { data: { organization, principal, client, scopes, audience, rateLimits } }

Conventions

• JSON in and out, except uploads (multipart/form-data) and downloads (the file itself). Field names are camelCase, ids are UUIDs and timestamps are RFC 3339 in UTC.
• Success is { "data": … }; lists add "meta": { "nextCursor": … } (Pagination). Errors are { "error": { "code", "message" } } (Errors).
• Send the token only in the Authorization: Bearer header. A token found in a URL is refused and revoked.
• Every response carries X-Request-Id. Send your own (8–128 characters of A–Z a–z 0–9 . _ : -) to correlate logs.
• POST requests take an Idempotency-Key (Idempotency); every response carries RateLimit-* headers (Rate limits).
• Knowledge you write through the API is always a proposal: it waits in the review queue, labelled API · client name, until an approver decides in Tradecraft.
• Operations that call AI models can answer 402 when the AI budget is used up (AI budget).

The API does not cover administration (users, roles, SSO, integrations, settings), Knowledge Hub decisions (approve, reject, resolve) or chat. Those stay in Tradecraft. Provisioning uses SCIM.

Machine clientsClient credentials for scripts and integrations.

Apps acting for peopleAuthorization code with PKCE and the organization picker.

ScopesThe 13 scopes and what each allows.

API referenceEvery operation, generated from the OpenAPI description.