Platform API

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.

Next