API Documentation

The Traction Hub API allows you to programmatically read and write your data — scorecards, issues, quarterly goals, to-dos, headlines, and more.

Base URL: https://tractionhubapp.com/api.php

Authentication

The API uses Bearer token authentication. Generate an API key from the Admin panel, then include it in the Authorization header of every request.

Generating a Key

1. Sign in as an admin and go to Admin → API Keys
2. Click New API Key, give it a name, and optionally set an expiry
3. Copy the key immediately — it is shown once only and never stored in plaintext

Using the Key

Pass the key in the Authorization header on every request:

POST /api.php
Content-Type: application/json
Authorization: Bearer th_live_a3f1b2c4d5e6...

Key Format

Keys are prefixed with th_live_ followed by 48 hex characters. Store keys securely — treat them like passwords.

Key Scope

Each key inherits the permissions of the admin who created it and is scoped to your company's data only.

{ "error": "Not authenticated" }

Request Format

All API requests are POST to /api.php with a JSON body containing an action field.

POST /api.php
Content-Type: application/json
Authorization: Bearer th_live_a3f1b2c4d5e6...

{
  "action": "create_issue",
  "tenant_id": 42,
  "title": "Fix the revenue forecasting formula",
  "type": "obstacle",
  "priority": 2
}

Response Format

All responses are JSON. Successful responses include "success": true. Failures include "error" with a description.

// Success
{ "success": true, "id": 123 }

// Error
{ "error": "Title required" }

API Keys

Manage API keys programmatically. All endpoints require an existing valid Bearer token with admin permissions.

{ "action": "create_api_key", "tenant_id": 1, "name": "Zapier" }

{ "success": true, "id": 3, "key": "th_live_a3f1b2c4..." }

{ "success": true, "keys": [
  {
    "id": 3,
    "name": "Zapier",
    "key_prefix": "th_live_a3f1b2c4",
    "created_by_name": "Jane Smith",
    "created_at": "2026-02-28 10:00:00",
    "last_used_at": "2026-02-28 14:22:01",
    "expires_at": null
  }
]}

{ "action": "revoke_api_key", "id": 3, "tenant_id": 1 }

{ "success": true }

Scorecards

{ "action": "create_scorecard", "tenant_id": 1, "name": "Leadership Scorecard" }

{ "success": true, "id": 7 }

Metrics

{ "action": "set_value", "metric_id": 14, "week_date": "2026-02-24", "value": 47 }

Issues

Quarterly Goals

To-Dos

Headlines

People Analyzer

Error Codes

Notes & Limits

• All requests must be POST with Content-Type: application/json
• API keys only have access to your own company's data
• There are no hard rate limits currently — please be respectful of shared resources
• IDs are integers. Always store them as integers, not strings
• Dates should use YYYY-MM-DD format
• Week dates must be a Monday

Questions? Contact us through the admin panel or reply to any Traction Hub email.