Documentation

Learn how to set up, configure, and integrate TicketForge into your workflow.

Platform Overview

TicketForge is an AI-powered, multi-project support ticket engine built for engineering teams. It combines ITIL-aligned service management with modern developer tooling — a REST API, TypeScript SDK, embeddable widget, and real-time webhooks.

Multi-tenant AI Triage ITIL-aligned Real-time Self-service Portal Developer-first

Ticket Lifecycle

Create, triage, assign, resolve

AI-Powered

Auto-triage, categorize, prioritize

Multi-channel

API, widget, email, portal

Core Concepts

Organizations

Top-level tenant boundary. All data is scoped to an organization via Row Level Security.

Each organization has its own agents, projects, contacts, and settings. Multi-org membership is supported.

Projects

Isolated environments within an org — each with its own API key, tickets, and configuration.

Use projects to separate products, teams, or environments (e.g., "Production App", "Internal Tools").

Tickets

The core unit of work. Created via API, widget, email, or the dashboard.

Tickets have a lifecycle: open → in_progress → waiting → resolved → closed. AI auto-triages priority and category.

Contacts

End-users who submit tickets. Tracked by email, with conversation history.

Contacts are auto-created on first ticket. They can self-serve via the customer portal.

Agents

Your support team members. Assigned roles (owner, admin, agent) with granular permissions.

Agents can be assigned to tickets, receive notifications, and manage all aspects of the support workflow.

Tags

Flexible labels for organizing and filtering tickets across projects.

Tags are org-scoped. Use them for categorization, SLA tracking, or automation rule triggers.

Knowledge Base

Published articles searchable by contacts and your support team.

Articles support Markdown, categories, and full-text search. Surfaced in the widget and portal.

Services & CMDB

ITIL-aligned service catalog and configuration management database.

Track services, CIs, dependencies, and link them to incidents and changes for impact analysis.

Getting Started

  1. 1

    Create your organization

    Sign up and create an org. This is your top-level workspace — all projects, agents, and data live under it.

  2. 2

    Create a project

    Each project gets its own API key (tf_...), tickets, and settings. Navigate to Projects to create one.

  3. 3

    Choose your integration method

    Install the TypeScript SDK, call the REST API directly, or embed the widget on your site.

  4. 4

    Submit your first ticket

    Use the API, SDK, or widget to create a ticket. AI triage will automatically categorize and prioritize it.

    curl -X POST https://ticketforge.app/v1/tickets \
  -H "Authorization: Bearer tf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Test ticket", "body": "Hello from the API!", "sender_email": "test@example.com"}'
  5. 5

    Configure webhooks & automations

    Set up outbound webhooks to push events to Slack, Discord, or your own services. Configure automation rules in Settings.

Integration Methods

TypeScript SDK

Official SDK — zero dependencies, native fetch, ESM-first. Full type safety.

TypeScriptESMNode 18+

REST API

Versioned JSON API for ticket creation, retrieval, messaging, and search.

RESTJSONv1

Embeddable Widget

Drop-in support form for any website. Shadow DOM isolated, ~7KB gzipped.

Shadow DOMIIFENo deps

Webhooks

Outbound HTTP callbacks on ticket events. HMAC-SHA256 signed with automatic retries.

HMAC-SHA256RetryEvents

AI Triage

TicketForge runs an AI triage pipeline on every ticket — automatically on creation via the API, or manually from the dashboard ticket view. The pipeline analyzes ticket content and produces:

Category

Auto-classifies into categories like billing, bug_report, feature_request.

Priority

Suggests priority from p1_critical to p4_low based on urgency signals.

Sentiment

Detects customer sentiment — negative, neutral, or positive — to flag frustrated users.

Draft Response

Generates a suggested reply that agents can review, edit, and send with one click.

Risk Assessment

Flags churn risk, SLA concerns, or escalation signals to help agents prioritize.

Key Entities

Extracts product names, error codes, and other entities mentioned in the ticket.

How it works

  1. Ticket is created via POST /v1/tickets — response returns immediately (202).
  2. An async task sends the ticket to the AI model for analysis.
  3. Results are stored in the ai_triage table and written back to the ticket.
  4. If configured, automation rules fire based on the triage results.
  5. Agents can re-run triage from the ticket detail view at any time — useful after new messages arrive.

Customer Portal

Each organization gets a branded self-service portal. Choose from 2 URL options:

Auto-generated

<slug>.ticketforge.app

Custom Domain

support.yourcompany.com

All domain options are free — configure yours in Status Page settings.

Submit Tickets

File new support requests with rich text and attachments.

Track Conversations

View status and reply to existing tickets.

Browse Knowledge Base

Search published articles for self-service answers.

Custom Branding

Your logo, colors, and greeting. Configure in Settings.

Status Page

Give your customers a public status page to monitor service health, track incidents, and subscribe to updates. Manage everything from Status Page in the dashboard.

Components & Groups

Organize services into groups (e.g., "Core Platform", "Integrations") with individual status indicators.

Uptime Tracking

90-day uptime history displayed per component with daily granularity.

Incident Management

Create incidents with timeline updates — investigating, identified, monitoring, resolved.

Scheduled Maintenance

Announce planned maintenance windows with start/end times and affected components.

Subscriber Notifications

Customers subscribe via email to receive incident and maintenance updates automatically.

Custom Domains

Use your own domain (e.g., status.yourcompany.com) — free, no upsell.

Security & Authentication

API Key Authentication

All API requests use Bearer tokens (tf_...). Keys are scoped to a project and validated on every request via middleware.

Row Level Security

All database access is scoped by org_id via PostgreSQL RLS policies. Helper functions is_org_member() and has_org_role() enforce tenant isolation.

Webhook Signatures

Outbound webhooks are signed with HMAC-SHA256. Verify the X-TicketForge-Signature header to ensure payload authenticity.

Rate Limiting

100 requests per minute per API key. Exceeding the limit returns 429 Too Many Requests. The SDK handles retries automatically with exponential backoff.

Next Steps

API Reference SDK & Guides Configure Settings