api

GoatFlow API Reference

Overview

GoatFlow has three API layers:

1. v1 API (/api/v1/*) - JSON REST API for scripts and integrations.
2. MCP server (/api/mcp) - JSON-RPC for AI assistants. See MCP.md.
3. Internal API (/api/*) - used by the web interface (HTMX). Not covered here.

This page lists the main endpoints. The full, generated list is in api.md (built from routes/*.yaml by make generate-route-docs).

Quick Start

Base URL

http://localhost:8080

Authentication

You can use a JWT from the login endpoint or an API token (gf_..., see API tokens).

# Log in and get an access token and a refresh token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"login":"admin","password":"your-password"}'

# Use the token
curl http://localhost:8080/api/v1/tickets \
  -H "Authorization: Bearer $TOKEN"

Response format

List endpoints such as GET /api/v1/tickets answer like this:

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

Errors from handlers:

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

Authentication and API-token scope checks answer with a code instead:

{
  "error": { "code": "core:unauthorized", "message": "Authentication required" }
}

API Documentation

• OpenAPI 3 spec of the v1 REST API: api/openapi.yaml. Request and response shapes, auth and status codes, checked against the router by go test ./internal/api -run TestOpenAPISpecMatchesRoutes and linted by make openapi-lint.
• Interactive docs: http://localhost:8080/swagger (on by default; GOATFLOW_SWAGGER_ENABLED), served from the swag annotations (swagger.yaml, make openapi-generate).
• All routes: api.md, openapi.json (route map) and index.html, generated from routes/*.yaml by make generate-route-docs.

Who can call what

Each route group in routes/*.yaml names its middleware:

Core Endpoints

Authentication

Tickets

Customers (customer JWT or customer API token) can call the GET ticket and article routes. They only see their own tickets and customer-visible articles. All other ticket routes are for agents.

GET /api/v1/tickets query parameters:

Articles

Queues

Users and groups

Lookups

Search

Statistics

All need read access to at least one queue (queue_ro). Results only cover queues the caller can read.

Custom fields and organisations

Webhooks

Admin only (routes/api-webhooks.yaml). The same settings are in the UI at Admin -> Webhooks (/admin/webhooks).

Create body: name, url, events (required); secret, headers, retry_count, timeout_seconds, is_active (optional).

Events:

Each delivery is an HTTP POST with a JSON body:

{ "event": "ticket.created", "occurred_at": "2026-10-01T12:00:00Z", "data": { ... } }

Headers on each delivery:

Events are found and delivered by the runner process (goats -mode runner). With no runner running, no webhooks are sent.

API tokens

Send a token as Authorization: Bearer gf_.... The admin:* scope is needed for admin routes, and only works when the token owner is an admin.

Canned responses

Agents only. Prefix /api/canned-responses (routes/api-canned-responses.yaml).

Self-service (password reset and sign-up)

These are public HTML form pages, not JSON APIs (routes/selfservice.yaml). They answer 404 while their feature switch is off.

Reset links last 1 hour. Sign-up links last 24 hours. Emails need BASE_URL to be set.

Translations (i18n)

Public, registered in Go (internal/platform/api/i18n_handlers.go).

Plugins

Registered in Go (internal/api/plugin_handlers.go).

Admin

Admin user management is under Users and groups and API tokens.

MCP Server (AI Integration)

See MCP.md for full documentation.

• Each tool call runs with the caller's own permissions.
• Tools are made from every /api/v1 endpoint and enabled plugin route.
• Admin tools (for example create_admin_sql) need admin group membership. API tokens also need the admin:* scope.

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

To scrape metrics without a login, set METRICS_ENABLED=true. GoatFlow then serves Prometheus metrics on a separate port, METRICS_PORT (default 9090).

Rate Limiting

Requests authenticated with a JWT or session cookie have no general rate limit.

See Also

• Developer Guide
• Security Documentation
• LDAP Integration
• Plugin Host API