api

GoatFlow API Reference

Overview

GoatFlow provides three API layers:

1. v1 API (/api/v1/*) - RESTful JSON API for programmatic access
2. MCP Server (/api/mcp) - AI assistant integration via JSON-RPC
3. Internal API (/api/*) - Used by the HTMX web interface

Quick Start

Base URL

http://localhost:8080

Authentication

# Login and get JWT token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

# Use token in subsequent requests
curl -X GET http://localhost:8080/api/v1/tickets \
  -H "Authorization: Bearer $JWT_TOKEN"

Response Format

All API responses follow this structure:

{
  "success": true,
  "data": { ... },
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5,
    "has_next": true,
    "has_prev": false
  }
}

Error Format

{
  "success": false,
  "error": "Error message description"
}

API Documentation

OpenAPI/Swagger Specification

• YAML: openapi.yaml
• JSON: openapi.json
• Interactive Docs: http://localhost:8080/api/docs (when running)

Route Documentation

• Generated Routes: api.md - Auto-generated from YAML route definitions

Core Endpoints

Authentication

Tickets

Articles

Queues

Users

Search

Dashboard

Admin (Requires Admin Role)

LDAP Integration (Admin Only)

MCP Server (AI Integration)

The MCP (Model Context Protocol) server enables AI assistants to interact with GoatFlow. See MCP.md for full documentation.

Key Features:

• Multi-user proxy: token owner's RBAC permissions apply to all operations
• 10 tools: list_tickets, get_ticket, search_tickets, list_queues, list_users, get_statistics, execute_sql, etc.
• Admin-only tools: execute_sql requires admin group membership
• Bearer token authentication via API tokens

curl -X POST https://your-goatflow/api/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Health Checks

Rate Limiting

Rate limits vary by endpoint:

Pagination

List endpoints support pagination:

GET /api/v1/tickets?page=1&limit=20

Response includes pagination metadata:

{
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 157,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

Filtering

Many endpoints support filtering via query parameters:

GET /api/v1/tickets?status=open&priority=high&queue_id=5

See Also

• Developer Guide
• Security Documentation
• LDAP Integration

For the complete API specification, see openapi.yaml