Tradecraft
Overview
Tradecraft API 1.0.1
Section titled “Tradecraft API 1.0.1”The public, versioned Tradecraft API. The organization comes from the access token — never from the path or a header; a token is bound to one organization and one audience (the API).
Authentication: OAuth 2 bearer tokens from the single issuer — authorization code + PKCE (S256, every client) for apps acting for a person, client credentials for machine clients (a service principal with an acting role, never admin). Tokens go in the Authorization header only; a token seen in a URL is revoked.
Conventions: JSON in and out (uploads multipart, downloads the file); { data } / { data: [...], meta: { nextCursor } }; errors { error: { code, message } } from one catalogue; cursor pagination (limit 1–100, opaque cursor); Idempotency-Key on POST (required where marked; kept 24 h); durable rate limits with RateLimit-* and Retry-After; X-Request-Id on every response.
Versioning: breaking changes only in /v2; additive changes (new fields, operations, enum values, error codes) ship in /v1 — tolerate unknown values. Deprecations carry Deprecation and Sunset headers with ≥ 6 months’ notice; /v1 stays ≥ 12 months after /v2.
Discovery: https://api.tradecrafthub.ai/.well-known/oauth-authorization-server (RFC 8414) and https://api.tradecrafthub.ai/.well-known/oauth-protected-resource (RFC 9728).
Authentication
Section titled “Authentication”oauth2
Section titled “oauth2”Opaque access tokens (1 hour), bound to one organization and the API audience. Refresh tokens rotate (30 days idle, 90 days absolute); client-credentials tokens have none. The organization is chosen at consent (tenant-owned clients are fixed to their owner); people in several organizations get one token per organization.
Security scheme type: oauth2
Flow type: authorizationCode
Authorization URL: https://api.tradecrafthub.ai/oauth/authorize
Token URL: https://api.tradecrafthub.ai/oauth/token
Refresh URL: https://api.tradecrafthub.ai/oauth/token
Scopes:
- assessments:read - Read questionnaires and their answers
- assessments:write - Upload questionnaires and start AI drafting (uses your organization's AI budget)
- questions:write - Edit answers during review
- assessments:review - Send questionnaires to Finalize on your behalf
- assessments:finalize - Finalize questionnaires on your behalf — their answers become approved knowledge
- knowledge:read - Read approved answers and their sources
- knowledge:ask - Ask questions — answers may be composed by AI from approved answers and use your organization's AI budget
- knowledge:gaps - See questions without approved answers
- knowledge:propose - Propose answers for review — nothing becomes an approved answer until an approver accepts it
- review:read - See the knowledge review queue
- library:write - Add documents to your knowledge libraries
- documents:download - Download your organization's source documents
- audit:read - Read your organization's audit log
Flow type: clientCredentials
Token URL: https://api.tradecrafthub.ai/oauth/token
Scopes:
- assessments:read - Read questionnaires and their answers
- assessments:write - Upload questionnaires and start AI drafting (uses your organization's AI budget)
- questions:write - Edit answers during review
- knowledge:read - Read approved answers and their sources
- knowledge:ask - Ask questions — answers may be composed by AI from approved answers and use your organization's AI budget
- knowledge:gaps - See questions without approved answers
- knowledge:propose - Propose answers for review — nothing becomes an approved answer until an approver accepts it
- review:read - See the knowledge review queue
- library:write - Add documents to your knowledge libraries
- documents:download - Download your organization's source documents
- audit:read - Read your organization's audit log