TekTree API Contracts

Version: 1.0.0 Last Updated: 2025-12-16 Status: Foundation (Pre-Implementation) API Version: v1

Base Configuration

Production Base URL: https://api.tektree.com/v1 Staging Base URL: https://staging-api.tektree.com/v1 Development Base URL: http://localhost:8000/v1 Protocol: HTTPS only (HTTP redirects to HTTPS) Content-Type: application/json Authentication: Bearer token (JWT)

Authentication

Headers

Authorization: Bearer <access_token>
Content-Type: application/json
X-Request-ID: <uuid> (optional, for tracing)

Access Token

Type: JWT (RS256)
Lifetime: 15 minutes
Location: Authorization header
Format: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Refresh Token

Type: Opaque token
Lifetime: 7 days (30 days with “remember me”)
Location: HTTP-only, Secure, SameSite cookie
Name: tektree_refresh_token

Rate Limiting

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702742400
Retry-After: 60

Limits by Tier

Tier	Requests/Minute	Burst Allowance
Free	100	200 (10s)
Pro	1000	2000 (10s)
Team	5000	10000 (10s)
Enterprise	Unlimited	Unlimited

Rate Limit Exceeded Response

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "status": 429,
    "retry_after": 60
  }
}

Error Responses

Standard Error Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "status": 400,
    "details": {
      "field": "email",
      "issue": "Email format is invalid"
    },
    "trace_id": "abc123xyz",
    "documentation_url": "https://docs.tektree.com/errors/ERROR_CODE"
  }
}

Common Error Codes

HTTP Status	Error Code	Description
400	`INVALID_REQUEST`	Request validation failed
401	`UNAUTHORIZED`	Missing or invalid auth token
403	`FORBIDDEN`	Insufficient permissions
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Resource conflict (duplicate)
422	`VALIDATION_ERROR`	Business logic validation failed
429	`RATE_LIMIT_EXCEEDED`	Too many requests
500	`INTERNAL_ERROR`	Server error
503	`SERVICE_UNAVAILABLE`	Service temporarily down

API Endpoints

1. Authentication

POST /auth/register

Description: Register a new user account Authentication: None Request:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "handle": "johndoe",
  "first_name": "John",
  "last_name": "Doe"
}

Response: 201 Created

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "handle": "johndoe",
    "email_verified": false,
    "created_at": "2025-12-16T14:30:00Z"
  },
  "message": "Verification email sent to user@example.com"
}

Description: Authenticate user and obtain tokens Authentication: None Request:

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "remember_me": false
}

Response: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "handle": "johndoe",
    "tier": "pro"
  }
}

Cookie Set: tektree_refresh_token (HTTP-only, Secure, SameSite)

POST /auth/refresh

Description: Refresh access token using refresh token Authentication: Refresh token (cookie) Response: 200 OK

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

POST /auth/logout

Description: Invalidate tokens and logout Authentication: Required Response: 204 No Content

2. Users

GET /users/me

Description: Get authenticated user’s profile Authentication: Required Response: 200 OK

{
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "handle": "johndoe",
    "first_name": "John",
    "last_name": "Doe",
    "avatar": "https://cdn.tektree.com/avatars/usr_abc123.jpg",
    "bio": "Software engineer passionate about...",
    "tier": "pro",
    "level": 15,
    "total_xp": 50000,
    "streak": 42,
    "created_at": "2025-01-01T00:00:00Z"
  }
}

PATCH /users/me

Description: Update authenticated user’s profile Authentication: Required Request:

{
  "first_name": "Jonathan",
  "bio": "Updated bio...",
  "avatar": "https://cdn.tektree.com/avatars/new.jpg"
}

Response: 200 OK (returns updated user object)

GET /users/:handle

Description: Get public user profile by handle Authentication: Optional Response: 200 OK

{
  "user": {
    "id": "usr_abc123",
    "handle": "johndoe",
    "first_name": "John",
    "last_name": "Doe",
    "avatar": "https://cdn.tektree.com/avatars/usr_abc123.jpg",
    "bio": "Software engineer...",
    "tier": "pro",
    "level": 15,
    "total_xp": 50000,
    "rank": 42,
    "stats": {
      "questions_posted": 120,
      "answers_submitted": 300,
      "insights_published": 25,
      "acceptance_rate": 0.65,
      "followers": 450,
      "following": 230
    },
    "top_areas": ["Programming", "Go", "Architecture"]
  }
}

3. Knowledge - Areas

POST /areas

Description: Create a new knowledge area Authentication: Required Tier Gate: Level 3+ Request:

{
  "title": "Event-Driven Architecture",
  "parent_id": "area_programming",
  "details": "Exploring event-driven patterns and systems...",
  "tags": ["architecture", "events", "microservices"],
  "visibility": "public"
}

Response: 201 Created

{
  "area": {
    "id": "area_xyz789",
    "title": "Event-Driven Architecture",
    "parent_id": "area_programming",
    "details": "Exploring event-driven patterns...",
    "tags": ["architecture", "events", "microservices"],
    "breadcrumbs": "Programming > Event-Driven Architecture",
    "visibility": "public",
    "created_by": "usr_abc123",
    "created_at": "2025-12-16T15:00:00Z"
  },
  "xp_earned": 10
}

GET /areas

Description: List all public areas Authentication: Optional Query Parameters:

parent_id (string): Filter by parent area
tags (string): Comma-separated tag filter
search (string): Search in title/details
page (int, default: 1)
limit (int, default: 20, max: 100)

Response: 200 OK

{
  "areas": [
    {
      "id": "area_xyz789",
      "title": "Event-Driven Architecture",
      "parent_id": "area_programming",
      "tags": ["architecture", "events"],
      "breadcrumbs": "Programming > Event-Driven Architecture",
      "follower_count": 234,
      "content_count": 45
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

4. Knowledge - Questions

POST /questions

Description: Post a new question Authentication: Required Quota: Free (20/month), Pro (200/month) Request:

{
  "title": "How do I implement event sourcing in Go?",
  "body": "I'm building an event-driven system and need advice...",
  "tags": ["go", "event-sourcing", "architecture"],
  "areas": ["area_programming", "area_go"],
  "visibility": "public",
  "files": ["file_abc123"]
}

Response: 201 Created

{
  "question": {
    "id": "qst_def456",
    "title": "How do I implement event sourcing in Go?",
    "body": "I'm building an event-driven system...",
    "tags": ["go", "event-sourcing", "architecture"],
    "areas": ["area_programming", "area_go"],
    "visibility": "public",
    "created_by": "usr_abc123",
    "created_at": "2025-12-16T15:30:00Z",
    "view_count": 0,
    "upvote_count": 0,
    "answer_count": 0,
    "accepted_answer_id": null
  },
  "xp_earned": 5
}

GET /questions/:id

Description: Get question details with answers Authentication: Optional Response: 200 OK

{
  "question": {
    "id": "qst_def456",
    "title": "How do I implement event sourcing in Go?",
    "body": "I'm building an event-driven system...",
    "tags": ["go", "event-sourcing"],
    "areas": [
      {
        "id": "area_go",
        "title": "Go Programming",
        "breadcrumbs": "Programming > Go"
      }
    ],
    "visibility": "public",
    "author": {
      "id": "usr_abc123",
      "handle": "johndoe",
      "avatar": "https://cdn.tektree.com/avatars/usr_abc123.jpg",
      "level": 15
    },
    "created_at": "2025-12-16T15:30:00Z",
    "updated_at": "2025-12-16T15:30:00Z",
    "view_count": 234,
    "upvote_count": 12,
    "downvote_count": 1,
    "answer_count": 3,
    "accepted_answer_id": "ans_ghi789",
    "answers": [
      {
        "id": "ans_ghi789",
        "body": "Here's how you can implement event sourcing...",
        "author": {
          "id": "usr_xyz789",
          "handle": "janedoe",
          "level": 20
        },
        "created_at": "2025-12-16T16:00:00Z",
        "upvote_count": 8,
        "is_accepted": true
      }
    ]
  }
}

POST /questions/:id/answers

Description: Submit an answer to a question Authentication: Required Request:

{
  "body": "Here's how you can implement event sourcing in Go...",
  "code_snippets": [
    {
      "language": "go",
      "code": "type Event struct {\n  ID string\n  Type string\n}"
    }
  ]
}

Response: 201 Created

{
  "answer": {
    "id": "ans_jkl012",
    "question_id": "qst_def456",
    "body": "Here's how you can implement...",
    "author": {
      "id": "usr_abc123",
      "handle": "johndoe"
    },
    "created_at": "2025-12-16T16:30:00Z",
    "upvote_count": 0
  },
  "xp_earned": 10
}

5. Knowledge - Insights

POST /insights

Description: Publish a new insight (article/tutorial) Authentication: Required Tier Gate: Level 4+ Quota: Free (5/month), Pro (50/month) Request:

{
  "title": "Event-Driven Architecture Best Practices",
  "body": "# Introduction\n\nEvent-driven architecture...",
  "insight_type": "article",
  "tags": ["architecture", "events"],
  "areas": ["area_architecture"],
  "visibility": "public",
  "co_authors": [],
  "estimated_read_time_minutes": 10
}

Response: 201 Created

{
  "insight": {
    "id": "ins_mno345",
    "title": "Event-Driven Architecture Best Practices",
    "slug": "event-driven-architecture-best-practices",
    "insight_type": "article",
    "tags": ["architecture", "events"],
    "author": {
      "id": "usr_abc123",
      "handle": "johndoe"
    },
    "created_at": "2025-12-16T17:00:00Z",
    "view_count": 0,
    "like_count": 0,
    "estimated_read_time_minutes": 10
  },
  "xp_earned": 25
}

POST /likes

Description: Like a content item Authentication: Required Request:

{
  "content_type": "question",
  "content_id": "qst_def456"
}

Response: 201 Created

{
  "like": {
    "id": "lke_pqr678",
    "content_type": "question",
    "content_id": "qst_def456",
    "user_id": "usr_abc123",
    "created_at": "2025-12-16T18:00:00Z"
  }
}

DELETE /likes/:id

Description: Unlike a content item Authentication: Required Response: 204 No Content

7. Gamification

GET /gamification/profile

Description: Get authenticated user’s gamification profile Authentication: Required Response: 200 OK

{
  "profile": {
    "user_id": "usr_abc123",
    "total_xp": 50000,
    "current_level": 15,
    "level_title": "Mighty Tree",
    "xp_to_next_level": 1500,
    "xp_progress_percent": 75,
    "daily_xp_earned": 150,
    "streak": {
      "current": 42,
      "longest": 87,
      "freezes_available": 6
    },
    "rank": {
      "global": 234,
      "weekly": 12
    },
    "achievements_unlocked": 23,
    "achievements_total": 45
  }
}

GET /gamification/achievements

Description: List all achievements with unlock status Authentication: Required Response: 200 OK

{
  "achievements": [
    {
      "id": "ach_first_steps",
      "name": "First Steps",
      "description": "Complete your profile",
      "tier": "bronze",
      "xp_bonus": 50,
      "badge_image_url": "https://cdn.tektree.com/badges/first_steps.svg",
      "unlocked": true,
      "unlocked_at": "2025-01-05T10:30:00Z",
      "progress": 1.0
    },
    {
      "id": "ach_week_warrior",
      "name": "Week Warrior",
      "description": "Maintain a 7-day activity streak",
      "tier": "silver",
      "xp_bonus": 100,
      "badge_image_url": "https://cdn.tektree.com/badges/week_warrior.svg",
      "unlocked": false,
      "progress": 0.71
    }
  ]
}

GET /gamification/leaderboard

Description: Get leaderboard rankings Authentication: Optional Query Parameters:

type (string): global | weekly | monthly | area:{area_id}
limit (int, default: 100)

Response: 200 OK

{
  "leaderboard": {
    "type": "weekly",
    "period": "2025-W50",
    "rankings": [
      {
        "rank": 1,
        "user": {
          "id": "usr_xyz789",
          "handle": "janedoe",
          "avatar": "https://cdn.tektree.com/avatars/usr_xyz789.jpg",
          "level": 20
        },
        "xp": 5000
      },
      {
        "rank": 2,
        "user": {
          "id": "usr_abc123",
          "handle": "johndoe",
          "level": 15
        },
        "xp": 4800
      }
    ],
    "current_user_rank": 12,
    "current_user_xp": 3200
  }
}

8. Subscriptions & Payments

GET /subscriptions/me

Description: Get authenticated user’s subscription details Authentication: Required Response: 200 OK

{
  "subscription": {
    "id": "sub_stu901",
    "user_id": "usr_abc123",
    "tier": "pro",
    "status": "active",
    "billing_cycle": "monthly",
    "current_period_start": "2025-12-01T00:00:00Z",
    "current_period_end": "2025-12-31T23:59:59Z",
    "next_billing_date": "2026-01-01T00:00:00Z",
    "next_billing_amount": 9.00,
    "currency": "USD",
    "trial_ends_at": null,
    "quotas": {
      "areas": "unlimited",
      "questions_per_month": 200,
      "insights_per_month": 50,
      "storage_mb": 10240
    },
    "usage": {
      "questions_this_month": 45,
      "insights_this_month": 3,
      "storage_used_mb": 1250
    }
  }
}

POST /checkout/create

Description: Create Polar checkout session for subscription upgrade Authentication: Required Request:

{
  "tier": "pro",
  "billing_cycle": "annual",
  "success_url": "https://tektree.com/checkout/success",
  "cancel_url": "https://tektree.com/checkout/cancel"
}

Response: 200 OK

{
  "checkout_session": {
    "id": "cs_vwx234",
    "checkout_url": "https://checkout.polar.sh/cs_vwx234",
    "expires_at": "2025-12-16T19:00:00Z"
  }
}

9. Real-Time WebSocket

WebSocket Endpoint

wss://api.tektree.com/v1/ws Connection:

const ws = new WebSocket('wss://api.tektree.com/v1/ws?token=<access_token>');

Message Format:

{
  "type": "subscribe",
  "channel": "notifications",
  "payload": {}
}

Channels:

notifications - User notifications
presence:{content_id} - Content presence tracking
leaderboard:{type} - Leaderboard updates
xp - Real-time XP updates

Server Messages:

{
  "type": "notification",
  "channel": "notifications",
  "payload": {
    "id": "ntf_yzabc",
    "type": "achievement_unlocked",
    "title": "Achievement Unlocked!",
    "message": "You've earned the 'Week Warrior' badge",
    "data": {
      "achievement_id": "ach_week_warrior",
      "badge_url": "https://cdn.tektree.com/badges/week_warrior.svg"
    },
    "created_at": "2025-12-16T20:00:00Z"
  }
}

Pagination

All list endpoints support pagination with consistent parameters: Query Parameters:

page (int, default: 1)
limit (int, default: 20, max: 100)
sort (string): Sort field (e.g., created_at, -upvotes)
filter (string): Filter expression (TBD)

Response Format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 250,
    "total_pages": 13,
    "has_next": true,
    "has_prev": false
  }
}

Versioning Strategy

Current Version: v1 Versioning Method: URL path (/v1/, /v2/) Deprecation Policy:

New version announced 3 months before release
Old version supported for 12 months after new version release
Deprecation warnings in response headers: X-API-Deprecated: true

Document Status: ✅ Complete Related Documents: ARCHITECTURE_OVERVIEW.md, EVENT_CATALOG.md, SECURITY_ARCHITECTURE.md

Overview

Architecture

Features

API

Tasksets

​TekTree API Contracts

​Base Configuration

​Authentication

​Headers

​Access Token

​Refresh Token

​Rate Limiting

​Rate Limit Headers

​Limits by Tier

​Rate Limit Exceeded Response

​Error Responses

​Standard Error Format

​Common Error Codes

​API Endpoints

​1. Authentication

​POST /auth/register

​POST /auth/login

​POST /auth/refresh

​POST /auth/logout

​2. Users

​GET /users/me

​PATCH /users/me

​GET /users/:handle

​3. Knowledge - Areas

​POST /areas

​GET /areas

​4. Knowledge - Questions

​POST /questions

​GET /questions/:id

​POST /questions/:id/answers

​5. Knowledge - Insights

​POST /insights

​6. Social - Likes

​POST /likes

​DELETE /likes/:id

​7. Gamification

​GET /gamification/profile

​GET /gamification/achievements

​GET /gamification/leaderboard

​8. Subscriptions & Payments

​GET /subscriptions/me

​POST /checkout/create

​9. Real-Time WebSocket

​WebSocket Endpoint

​Pagination

​Versioning Strategy

TekTree API Contracts

Base Configuration

Authentication

Headers

Access Token

Refresh Token

Rate Limiting

Rate Limit Headers

Limits by Tier

Rate Limit Exceeded Response

Error Responses

Standard Error Format

Common Error Codes

API Endpoints

1. Authentication

POST /auth/register

POST /auth/login

POST /auth/refresh

POST /auth/logout

2. Users

GET /users/me

PATCH /users/me

GET /users/:handle

3. Knowledge - Areas

POST /areas

GET /areas

4. Knowledge - Questions

POST /questions

GET /questions/:id

POST /questions/:id/answers

5. Knowledge - Insights

POST /insights

6. Social - Likes

POST /likes

DELETE /likes/:id

7. Gamification

GET /gamification/profile

GET /gamification/achievements

GET /gamification/leaderboard

8. Subscriptions & Payments

GET /subscriptions/me

POST /checkout/create

9. Real-Time WebSocket

WebSocket Endpoint

Pagination

Versioning Strategy