Skip to Content
Docs

HTTP API

Base URL

Local default: http://127.0.0.1:18765

Production: your configured StruggleTime host. struggletime / settings normalize away ephemeral tunnel URLs.

Authenticate machine clients with:

Authorization: Bearer st_...

Generate keys in Settings -> Profile. Rotate in the danger zone when compromised.

Auth and session

MethodPathNotes
BrowserSlack / GitHub OAuth start + callbackDashboard session
POST/v1/auth/claim-handleClaim public handle after Slack
SPA sign-out(dashboard)Clears session cookie; daemon keys stay until revoked
Bearerst_... API keyDaemon batch / sync

Signing out of the dashboard does not stop a running daemon. Revoke or regenerate the API key to cut machine access.

Accounts and profiles

RouteWhat
POST /v1/users {handle, is_public?}Create account (legacy/test); prefer Slack claim
GET /v1/usersPublic builders with totals, streaks, GitHub links
GET /v1/users/{handle}Public profile (403 if private and not you)
POST /v1/users/{handle}/github {github_login}Link GitHub (automation)
POST /v1/users/{handle}/slack {slack_user_id}Link Slack (automation)

Projects and time

RouteWhat
POST /v1/projects {id, name, repo_url?}Register a project
GET /v1/projectsProjects with weighted/raw stats and flags
POST /v1/projects/{id}/git {repo_url, head_from, head_to}Link repo + anchor range
POST /v1/buckets/batch {user_id?, buckets:[...]}Ingest sealed buckets
GET /v1/projects/{id}/statsBuckets, raw vs weighted, per-state counts, streak
GET /v1/projects/{id}/bucketsStored metadata buckets + evidence size
GET /v1/projects/{id}/frictionFriction timeline + commit anchors
GET /v1/projects/{id}/stream?once=1SSE stats snapshot (omit once for live)
GET /v1/projects/{id}/githubRepo link + webhook anchors (?fetch=1 live)
GET /v1/overviewInstance-wide totals

Bucket batch ingestion

POST /v1/buckets/batch
Authorization: Bearer st_...
Content-Type: application/json

Allowlisted schema only (schemas/heartbeat.schema.json). Typical sealed unit stays in the ~25-50 KB metadata budget.

StatusMeaning
200Accepted; chain advances
400Schema / allowlist violation
409Identical replay
422Tamper or broken prev_hash chain
401/403Auth
5xxRetry from offline queue

Prompt text, commands, code, and raw paths are rejected before chain verification.

Chain and offline sync

  1. Seal locally and append .aitime-ledger.json with prev_hash.
  2. Enqueue offline if the server is unreachable.
  3. Flush ordered batches to /v1/buckets/batch.
  4. Adopt the server chain head after success.

Broken links surface as CHAIN_BROKEN in review. See Privacy.

Submissions and review

RouteWhat
POST /v1/submissions {project_id, from_bucket, to_bucket, ai_declaration}Freeze an evidence pack
GET /v1/submissions / GET /v1/submissions/{id}List / fetch
POST /v1/submissions/{id}/reviewApprove, deflate, or reject
{
  "approved_weighted_secs": 1200,
  "reason_code": "IDLE_INFLATION",
  "reviewer_id": "..."
}

reason_code must be one of: NONE, UNATTENDED_AGENT_DUMP, IDLE_INFLATION, NO_TEST_ITERATION, BOILERPLATE_HEAVY, CHAIN_BROKEN, GIT_MISMATCH, UNSIGNED_INSTALL.

Staff-only. See Review.

Integrations

RouteWhat
POST /v1/integrations/github/webhookSigned push events
POST /v1/integrations/slack/commandSigned /struggletime stats
GET /v1/integrations/eventsQueued Slack notifications

Details: Integrations.

Docs and static

PathContent
/SPA shell
/docs/Fumadocs static export
/_next/...Docs assets from export

Errors

Errors are { "error": "..." } with 400 (malformed / allowlist), 401 (bad integration signature), 403 (private profile), 404, 409 (duplicate), 422 (chain broken / tampered). Do not retry 401/403 without rotating credentials. Retry 502/503 with backoff from the offline queue.

Also: Privacy, Troubleshooting.

On this page