The paths below are provisional. The resource model is stable; the exact paths may change.
Base URL: https://build.tnthub.com/api/v1
Authentication
Bearer tokens. Access tokens live 15 minutes; refresh tokens live 30 days and are sent as a HttpOnly; Secure; SameSite=Lax cookie.
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
Tokens are signed with RS256 and carry a key id, so the platform can rotate keys without downtime. A token carries only identity — user id, tenant id, role, expiry — never entitlements, because entitlements change and a stale token would keep them.
Obtaining a token
Single sign-on from the main site is a POST, not a GET:
POST https://tnthub.com/?tnthub_ticket=1
Content-Type: application/json
{"nonce": "a1b2c3d4e5f6..."}
The nonce is single-use and valid for 30 seconds. The response redirects to:
https://build.tnthub.com/?ticket=<signed>&sig=<signature>
The ticket is signed, expires in 30 seconds, and is bound to a hash of the user agent and IP. It requires no server-side storage: verification is signature validation plus the binding check, which is why the replay window can be as small as 30 seconds without a nonce table.
The redirect response carries Cache-Control: no-store and Referrer-Policy: no-referrer.
Resources
Projects
GET /projects
POST /projects
GET /projects/{projectId}
PATCH /projects/{projectId}
Clauses
GET /projects/{projectId}/clauses
GET /projects/{projectId}/clauses/{clauseId}
POST /projects/{projectId}/clauses/{clauseId}/approve
POST /projects/{projectId}/clauses/{clauseId}/reject
POST /projects/{projectId}/clauses/{clauseId}/defer
A rejection carries a reason, which is required:
POST /projects/orders-api/clauses/refund-window-closed/reject
{
"reason": "The window is 30 days for monthly plans, 7 for annual."
}
Drafts
POST /projects/{projectId}/drafts
GET /projects/{projectId}/drafts/current
GET /projects/{projectId}/drafts/diff?since=<snapshotId>
Builds
POST /projects/{projectId}/builds
GET /projects/{projectId}/builds
GET /builds/{buildId}
GET /builds/{buildId}/logs?offset=<bytes>
GET /builds/{buildId}/results
The logs endpoint is a ranged read. It returns the bytes from the offset and the next offset to use, so a client that drops its connection resumes rather than restarts.
Verification
GET /builds/{buildId}/results
GET /builds/{buildId}/gaps
GET /builds/{buildId}/strength
GET /builds/{buildId}/attribution
Each result carries the clause it belongs to, the outcome, the assertion-strength grade, and the evidence — request, response, and resulting state.
Trial environments
POST /projects/{projectId}/environments
GET /projects/{projectId}/environments
GET /environments/{envId}
GET /environments/{envId}/credentials
DELETE /environments/{envId}
GET /environments/{envId}/credentials is audited as a credential access. It is not a convenience endpoint — it exists because the environment has to be reachable.
Findings
POST /builds/{buildId}/findings
GET /projects/{projectId}/findings
PATCH /findings/{findingId}
Webhooks
Point a webhook at your own infrastructure and the platform delivers events:
POST https://your-endpoint.example/hooks/trigger-trial
| Event | When |
|---|---|
clause.approved |
A clause was approved |
clause.rejected |
A clause was rejected, with the reason |
build.queued |
A build entered the queue |
build.started |
A worker claimed the build |
build.layer.completed |
A verification layer finished |
build.completed |
The build finished, successfully or not |
build.failed |
The build failed, with the attributed clause |
environment.ready |
A trial environment is reachable |
environment.expired |
An environment was reclaimed |
finding.created |
A finding was filed against a clause |
Every delivery carries an event id, a timestamp, and a signature header. Verify the signature before acting on a payload — the endpoint you are pointing at is receiving claims about your project from the internet.
Deliveries are retried with exponential backoff. An endpoint that returns a non-2xx status is retried; one that fails repeatedly is disabled and reported.
Rate limits
Per-token limits, per endpoint class:
| Class | Limit |
|---|---|
| Reads | 600 per minute |
| Writes | 60 per minute |
| Builds | 20 per hour per project |
| Log reads | 2,000 per minute |
The response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A 429 response includes a Retry-After header.
Errors
{
"error": {
"code": "clause_not_in_review",
"message": "Clause 'refund-window-closed' has already been approved.",
"clause_id": "refund-window-closed",
"request_id": "req_2f8a41"
}
}
code is stable and safe to branch on. message is for humans and may change. Always log the request_id — it is what support needs to find the request.