API Reference

TameFlare has two API surfaces: the Gateway v2 Internal API (used by the CLI, localhost only) and the Control Plane API (v1 SDK advisory mode).

Gateway v2 Internal API

The gateway exposes an internal API on localhost:9443. All endpoints are used by the CLI and dashboard — not called directly by agents.

Connectors

# Add a connector
curl -X POST http://127.0.0.1:9443/internal/connectors/add \
  -H "Content-Type: application/json" \
  -d '{ "type": "github", "token": "ghp_xxx" }'

Supported types: github, openai, anthropic, stripe, slack, generic.

For generic, also pass "domains": ["api.example.com"] and optionally "auth_type": "bearer".

# List connectors
curl http://127.0.0.1:9443/internal/connectors
 
# Remove a connector
curl -X POST http://127.0.0.1:9443/internal/connectors/remove \
  -d '{ "id": "conn_github_1" }'

Permissions

# Set a permission
curl -X POST http://127.0.0.1:9443/internal/permissions/set \
  -H "Content-Type: application/json" \
  -d '{
    "gateway_name": "Bot",
    "connector_type": "github",
    "action_pattern": "github.pr.*",
    "decision": "allow"
  }'
 
# List permissions
curl http://127.0.0.1:9443/internal/permissions

Decisions: allow, deny, require_approval.

Approvals

# List pending approvals
curl http://127.0.0.1:9443/internal/approvals
 
# List recent (all statuses)
curl http://127.0.0.1:9443/internal/approvals/recent
 
# Respond to an approval
curl -X POST http://127.0.0.1:9443/internal/approvals/respond \
  -H "Content-Type: application/json" \
  -d '{ "id": "apv_xxx", "approved": true, "by": "admin", "note": "Looks safe" }'

Kill Switch

# Activate (global)
curl -X POST http://127.0.0.1:9443/internal/kill-switch \
  -H "Content-Type: application/json" \
  -d '{ "active": true, "reason": "Security incident" }'
 
# Activate (scoped to connector or agent)
curl -X POST http://127.0.0.1:9443/internal/kill-switch \
  -d '{ "active": true, "reason": "incident", "scope": "github" }'
 
# Deactivate
curl -X POST http://127.0.0.1:9443/internal/kill-switch \
  -d '{ "active": false }'

Metrics

# Prometheus-compatible metrics
curl http://127.0.0.1:9443/internal/metrics

Returns text exposition format with counters (aaf_traffic_total), latency (aaf_traffic_latency_ms_*), and gauges (aaf_processes_active, aaf_connectors_total, aaf_gateway_uptime_seconds).

Rate Limiting

The proxy enforces 120 requests/minute per agent (sliding window). Exceeding returns:

{"error":"rate limit exceeded","retry_after":12}

With status 429 and Retry-After header.

Other Endpoints

| Method | Path | Description | |---|---|---| | POST | /internal/agents/register | Register agent, get proxy port | | POST | /internal/agents/deregister | Deregister agent | | GET | /internal/agents | List active agents | | GET | /internal/status | Gateway status + stats | | GET | /internal/traffic | Recent traffic log | | POST | /internal/enforcement | Set enforcement level |

Dashboard API

The dashboard exposes API routes at /api/dashboard/* authenticated via session cookie (login first).

Gateway Management

# List all gateways (with live status)
curl http://localhost:3000/api/dashboard/gateway \
  -H "Cookie: tf_session=<session>"

{
  "gateways": [
    {
      "id": "gw_abc123",
      "name": "default",
      "host": "127.0.0.1",
      "port": 9443,
      "status": "stopped",
      "enforcementLevel": "monitor",
      "live": null
    }
  ]
}

# Create a gateway (full wizard payload)
curl -X POST http://localhost:3000/api/dashboard/gateway \
  -H "Cookie: tf_session=<session>" \
  -H "Content-Type: application/json" \
  -d '{
    "gateway": { "name": "default", "host": "127.0.0.1", "port": 9443, "enforcementLevel": "monitor" },
    "agent": { "name": "DevOps Bot", "create": true },
    "connectors": [
      { "type": "github", "token": "ghp_xxx", "accessRule": "allow_all" },
      { "type": "openai", "token": "sk-xxx", "accessRule": "read_only" }
    ]
  }'

{ "ok": true, "gateway_id": "gw_abc123", "api_key": "aaf_test_...", "gateway_name": "DevOps Bot" }

Access rules: allow_all, read_only, require_approval, custom (with customPatterns field).

# Update a gateway
curl -X PATCH http://localhost:3000/api/dashboard/gateway \
  -H "Cookie: tf_session=<session>" \
  -H "Content-Type: application/json" \
  -d '{ "gateway_id": "gw_abc123", "enforcementLevel": "full_enforce" }'

Other Dashboard Endpoints

| Method | Path | Auth | Description | |---|---|---|---| | GET/POST/PATCH | /api/dashboard/gateway | admin | Gateway CRUD (see above) | | GET/POST/PATCH | /api/dashboard/agents | admin | Agent management | | GET/POST/PATCH | /api/dashboard/policies | admin | Policy CRUD | | POST | /api/dashboard/setup | admin | Quick setup wizard (agent + connectors + permissions) | | GET | /api/dashboard/traffic | viewer | Proxy traffic log | | GET/POST | /api/dashboard/proxy-approvals | member | Approval queue | | GET/PUT | /api/dashboard/settings | admin | Org settings | | GET | /api/dashboard/audit-export | admin | CSV audit export | | GET | /api/dashboard/export | admin | Config export (JSON) | | POST | /api/dashboard/import | owner | Config import |

Control Plane API (v1 Advisory Mode)

Authentication

User auth (dashboard)

# Register
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@company.com", "password": "securepass123", "name": "Admin" }'

{ "ok": true, "user": { "id": "usr_abc123", "email": "admin@company.com", "role": "owner" } }

# Login (sets tf_session cookie)
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{ "email": "admin@company.com", "password": "securepass123" }'

{ "ok": true }

# Logout (clears session)
curl -X POST http://localhost:3000/api/auth/logout

Agent auth (API)

All agent API endpoints below require Authorization: Bearer <agent_api_key>.

Rate limit: 60 requests per minute per agent. Exceeding returns 429 with a Retry-After header:

{ "error": "Rate limit exceeded", "retry_after": 45 }

Request an action

POST /api/v1/actions

Submit an action for policy evaluation. This is the primary endpoint your agents call.

curl -X POST http://localhost:3000/api/v1/actions \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "action_spec": {
      "type": "github.issue.create",
      "resource": {
        "provider": "github",
        "account": "my-org",
        "target": "my-org/my-repo",
        "environment": "development"
      },
      "parameters": { "title": "Bug fix", "body": "Details..." },
      "risk_hints": {
        "production_target": false,
        "irreversible": false
      }
    },
    "webhook_url": "https://your-server.com/webhook"
  }'

Response (allowed):

{
  "action_request_id": "act_7f83b165",
  "status": "allowed",
  "decision": {
    "outcome": "allow",
    "reason": "Matched rule 'Allow dev actions' in policy 'GitHub Safe Defaults'",
    "matched_policies": ["pol_github_safe_defaults"],
    "risk_score": 0.1,
    "constraints": null
  },
  "decision_token": "eyJhbGciOiJFUzI1NiIs...",
  "expires_at": "2025-02-07T12:00:00.000Z"
}

Response (requires approval):

{
  "action_request_id": "act_9a2c4e81",
  "status": "pending_approval",
  "decision": {
    "outcome": "requires_approval",
    "reason": "Production merges require engineering lead approval",
    "matched_policies": ["pol_github_safe_defaults"],
    "risk_score": 0.7,
    "constraints": null
  },
  "decision_token": null,
  "approval": {
    "id": "apr_3f7b2a91",
    "status": "pending",
    "required_approver_groups": ["engineering-leads"],
    "expires_at": "2025-02-07T12:00:00.000Z"
  }
}

Response (denied):

{
  "action_request_id": "act_b4d8f123",
  "status": "denied",
  "decision": {
    "outcome": "deny",
    "reason": "Cannot delete protected branches",
    "matched_policies": ["pol_github_safe_defaults"],
    "risk_score": 0.9,
    "constraints": null
  },
  "decision_token": null
}

Tip

The webhook_url field is optional. If provided, TameFlare will send a POST request to that URL when the decision changes (e.g., when an approval is granted).

Batch request actions

POST /api/v1/actions/batch

Submit up to 20 action requests in a single call. Each action is evaluated independently against the same policy set. Useful for agents that need to check multiple actions at once.

curl -X POST http://localhost:3000/api/v1/actions/batch \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "action_spec": {
          "type": "github.issue.create",
          "resource": { "provider": "github", "account": "my-org", "target": "my-org/repo", "environment": "development" },
          "parameters": { "title": "Fix bug" }
        }
      },
      {
        "action_spec": {
          "type": "github.branch.delete",
          "resource": { "provider": "github", "account": "my-org", "target": "my-org/repo", "environment": "production" },
          "parameters": { "branch_name": "main" },
          "risk_hints": { "irreversible": true, "production_target": true }
        }
      }
    ]
  }'

Response:

{
  "batch_id": "req_1707300000_abc123",
  "total": 2,
  "results": [
    {
      "action_request_id": "act_7f83b165",
      "status": "allowed",
      "decision": { "outcome": "allow", "reason": "Dev actions allowed", "matched_policies": ["pol_github_safe_defaults"], "risk_score": 0.1 },
      "decision_token": "eyJhbGci...",
      "expires_at": "2025-02-07T12:00:00.000Z"
    },
    {
      "action_request_id": "act_b4d8f123",
      "status": "denied",
      "decision": { "outcome": "deny", "reason": "Cannot delete protected branches", "matched_policies": ["pol_github_safe_defaults"], "risk_score": 0.9 },
      "decision_token": null,
      "expires_at": "2025-02-07T12:00:00.000Z"
    }
  ]
}

Warning

Batch requests count as a single rate-limit hit, but each action creates its own audit trail entry. Maximum batch size is 20. Approval workflows are not triggered in batch mode — use single requests for actions that may require approval.

Dry-run policy evaluation

POST /api/v1/actions/dry-run

Test what decision would be made without creating an action request or audit trail entry.

curl -X POST http://localhost:3000/api/v1/actions/dry-run \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "action_spec": {
      "type": "payment.transfer.initiate",
      "resource": {
        "provider": "stripe",
        "account": "acct_123",
        "target": "transfers",
        "environment": "production"
      },
      "parameters": { "amount": 25000, "currency": "USD" },
      "risk_hints": { "financial_impact": true, "irreversible": true }
    }
  }'

Response:

{
  "dry_run": true,
  "decision": {
    "outcome": "requires_approval",
    "reason": "Transfers over $10,000 require finance team approval",
    "matched_policies": ["pol_payment_controls"],
    "matched_rules": ["require-approval-large-transfers"],
    "risk_score": 0.8,
    "risk_factors": ["financial_impact", "irreversible"],
    "approver_groups": ["finance-team"],
    "constraints": null
  },
  "trace": [
    {
      "policy_id": "pol_payment_controls",
      "policy_name": "Payment Controls",
      "scope_matched": true,
      "rules": [
        { "rule_name": "block-sanctioned-currencies", "conditions_matched": false, "failed_condition": "parameters.currency in [\"KPW\",\"SYP\",\"IRR\"] → false", "decision": null },
        { "rule_name": "require-approval-large-transfers", "conditions_matched": true, "failed_condition": null, "decision": "requires_approval" }
      ]
    }
  ],
  "policies_evaluated": 3,
  "agent": { "id": "agent_abc123", "environment": "production" }
}

Note

The trace array shows exactly which policies and rules were evaluated, making it easy to debug why a particular decision was made.

Get action status

GET /api/v1/actions/:actionRequestId

curl http://localhost:3000/api/v1/actions/act_7f83b165 \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef"

Response:

{
  "action_request_id": "act_7f83b165",
  "status": "allowed",
  "action_spec": { "type": "github.issue.create", "..." : "..." },
  "decision": {
    "outcome": "allow",
    "reason": "Matched rule 'Allow dev actions'",
    "matched_policies": ["pol_github_safe_defaults"],
    "risk_score": 0.1,
    "constraints": null
  },
  "decision_token": "eyJhbGciOiJFUzI1NiIs...",
  "created_at": "2025-02-06T10:30:00.000Z"
}

Execute an approved action

POST /api/v1/actions/:actionRequestId/execute

Send the decision token to execute the action via the gateway. The token is verified and the nonce is consumed.

curl -X POST http://localhost:3000/api/v1/actions/act_7f83b165/execute \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "decision_token": "eyJhbGciOiJFUzI1NiIs..." }'

Response (success):

{
  "executed": true,
  "action_request_id": "act_7f83b165",
  "gateway_response": { "status": "completed", "result": { "issue_number": 42 } }
}

Response (token invalid):

{ "error": "Token verification failed: nonce already used" }

Cancel an action

POST /api/v1/actions/:actionRequestId/cancel

curl -X POST http://localhost:3000/api/v1/actions/act_7f83b165/cancel \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef"

Response:

{ "action_request_id": "act_7f83b165", "status": "cancelled" }

Register an agent

POST /api/v1/agents/register

curl -X POST http://localhost:3000/api/v1/agents/register \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "name": "deploy-bot", "runtime": "node", "environment": "production" }'

Response:

{
  "agent_id": "agent_f4669dfd",
  "api_key": "aaf_live_a1b2c3d4e5f6...",
  "api_key_prefix": "aaf_live_a1b2"
}

Warning

The api_key is only shown once. Store it securely. You cannot retrieve it again.

List policies

GET /api/v1/policies

curl http://localhost:3000/api/v1/policies \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef"

Response:

{
  "policies": [
    {
      "id": "pol_github_safe_defaults",
      "name": "GitHub Safe Defaults",
      "description": "Baseline safety rules for GitHub actions",
      "enabled": true,
      "priority": 900,
      "tags": ["github", "production"],
      "created_at": "2025-02-06T10:00:00.000Z"
    }
  ]
}

Get audit events

GET /api/v1/audit/events

curl "http://localhost:3000/api/v1/audit/events?limit=10&offset=0" \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef"

Response:

{
  "events": [
    {
      "id": "evt_abc123",
      "event_type": "action.allowed",
      "org_id": "org_demo",
      "agent_id": "agent_f4669dfd",
      "action_request_id": "act_7f83b165",
      "details": { "outcome": "allow", "reason": "Matched rule 'Allow dev actions'" },
      "created_at": "2025-02-06T10:30:00.000Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Respond to an approval

POST /api/v1/approvals/:approvalId/respond

curl -X POST http://localhost:3000/api/v1/approvals/apr_3f7b2a91/respond \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "reason": "Looks good, ship it" }'

Response:

{
  "approval_id": "apr_3f7b2a91",
  "status": "approved",
  "decision_token": "eyJhbGciOiJFUzI1NiIs..."
}

Toggle kill switch

POST /api/v1/org/kill-switch

curl -X POST http://localhost:3000/api/v1/org/kill-switch \
  -H "Authorization: Bearer aaf_test_demo1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{ "active": true, "reason": "Security incident" }'

Response:

{ "kill_switch": true }

When active, all new action requests return:

{ "status": "denied", "decision": { "outcome": "deny", "reason": "Kill switch active: Security incident" } }

Verify a decision token

POST /api/v1/tokens/verify

No auth required. Used by the gateway to verify tokens before executing. Marks the nonce as used (replay protection).

curl -X POST http://localhost:3000/api/v1/tokens/verify \
  -H "Content-Type: application/json" \
  -d '{ "decision_token": "eyJhbGciOiJFUzI1NiIs...", "action_request_id": "act_7f83b165" }'

Response (valid):

{
  "valid": true,
  "payload": {
    "sub": "agent_f4669dfd",
    "org": "org_demo",
    "act": "act_7f83b165",
    "ash": "7f83b1657ff1..."
  }
}

Response (invalid):

{ "valid": false, "error": "Nonce already used" }

Health check

GET /api/health

No authentication required. Returns the status of the database and gateway.

curl http://localhost:3000/api/health

Response (healthy):

{
  "status": "healthy",
  "timestamp": "2026-02-07T09:00:00.000Z",
  "checks": {
    "database": { "status": "ok", "latencyMs": 3 },
    "gateway": { "status": "ok", "latencyMs": 12 }
  }
}

Response (degraded):

{
  "status": "degraded",
  "timestamp": "2026-02-07T09:00:00.000Z",
  "checks": {
    "database": { "status": "ok", "latencyMs": 3 },
    "gateway": { "status": "error", "latencyMs": 3001, "error": "Timeout" }
  }
}

Returns 200 when all checks pass, 503 when any check fails.

Data cleanup

POST /api/maintenance/cleanup

Purge expired nonces, sessions, and optionally old audit events. Protected by MAINTENANCE_SECRET environment variable.

curl -X POST http://localhost:3000/api/maintenance/cleanup \
  -H "Authorization: Bearer your-maintenance-secret"

Response:

{
  "status": "completed",
  "timestamp": "2026-02-07T09:00:00.000Z",
  "cleaned": {
    "expired_nonces": 15,
    "expired_sessions": 3,
    "used_nonces_cleaned": 42,
    "old_audit_events": 0
  }
}

Set AUDIT_RETENTION_DAYS to automatically purge audit events older than that many days. A value of -1 in any result field indicates the operation failed.

Tip

Run this endpoint on a cron schedule (e.g., daily) to keep the database clean. Example: 0 3 * * * curl -X POST -H "Authorization: Bearer $SECRET" https://your-app/api/maintenance/cleanup

User management

POST /api/dashboard/users

Manage user roles and account status. Requires admin role. Only owner can promote/demote to/from owner.

Change role:

curl -X POST http://localhost:3000/api/dashboard/users \
  -H "Content-Type: application/json" \
  -H "Cookie: tf_session=your-session-token" \
  -d '{ "user_id": "usr_abc123", "action": "change_role", "role": "admin" }'

Suspend or activate:

curl -X POST http://localhost:3000/api/dashboard/users \
  -H "Content-Type: application/json" \
  -H "Cookie: tf_session=your-session-token" \
  -d '{ "user_id": "usr_abc123", "action": "suspend" }'

Response:

{ "ok": true, "role": "admin" }

Valid roles: owner, admin, member, viewer. Valid actions: change_role, suspend, activate.

Guards: cannot self-demote owner, cannot suspend owner. Creates audit events (user.role_changed, user.suspended, user.activated).

Error responses

All endpoints return errors in a consistent format:

{ "error": "Description of what went wrong" }

Validation errors (from Zod schema validation) include field-level details:

{
  "error": "Validation failed",
  "details": "action_spec.resource.provider: provider is required; action_spec.type: action type is required"
}

RBAC errors include the required and current roles:

{
  "error": "Forbidden",
  "required_role": "owner",
  "your_role": "member"
}

| Status | Meaning | |---|---| | 400 | Invalid request body, missing required fields, or Zod validation failure | | 401 | Missing or invalid API key / session | | 403 | Authenticated but insufficient role (RBAC) | | 404 | Resource not found | | 409 | Conflict (e.g., approval already resolved) | | 410 | Gone (e.g., approval expired) | | 429 | Rate limit exceeded (check Retry-After header) | | 500 | Internal server error |

Dashboard APIs

These endpoints are used by the dashboard UI and require a valid session cookie (not an agent API key).

Export audit log (CSV)

curl "http://localhost:3000/api/dashboard/audit-export?type=action.requested&q=github" \
  --cookie "tf_session=<session_token>"

Returns a CSV file with columns: timestamp, event_type, agent_id, action_type, details. Both type and q parameters are optional filters.

Run a demo action

Sends a simulated action through the policy engine. Useful for testing policies without a real agent.

curl -X POST http://localhost:3000/api/dashboard/demo-action \
  --cookie "tf_session=<session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "scenario": 0 }'

Response:

{
  "ok": true,
  "scenario": "Create GitHub Issue (safe)",
  "action_request_id": "act_demo_12baa4c1",
  "decision": {
    "outcome": "allow",
    "reason": "Matched rule 'Allow all other GitHub actions' in policy 'GitHub Safe Defaults'",
    "risk_score": 0,
    "matched_policies": ["pol_github_safe_defaults"]
  }
}

Scenarios: 0 = Create Issue (safe), 1 = Merge PR (risky), 2 = Delete Branch (destructive). Omit scenario for a random pick.

Test gateway connectivity

curl "http://localhost:3000/api/dashboard/test-gateway?url=http://localhost:8443" \
  --cookie "tf_session=<session_token>"

Response:

{ "ok": true, "status": "connected", "connectors": ["github", "webhook"] }

Save integration settings

curl -X PUT http://localhost:3000/api/dashboard/settings \
  --cookie "tf_session=<session_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "slack_bot_token": "xoxb-...",
      "slack_signing_secret": "...",
      "slack_channel_id": "C0123456",
      "github_pat": "ghp_...",
      "gateway_url": "http://localhost:8443"
    }
  }'

Response:

{ "ok": true }

Note

Settings are merged, not overwritten. You can send only the fields you want to change. Sensitive values are encrypted at rest with AES-256-GCM.

Export configuration

GET /api/dashboard/export

Download all policies, agents, and org settings as a JSON bundle. Requires admin role.

curl http://localhost:3000/api/dashboard/export \
  --cookie "tf_session=<session_token>" \
  -o TameFlare-config.json

Response (200):

{
  "version": "1.0",
  "exportedAt": "2026-02-07T10:00:00.000Z",
  "organization": { "name": "My Org", "plan": "free" },
  "agents": [
    { "name": "deploy-bot", "runtime": "node", "environment": "production", "status": "active", "capabilities": [], "metadata": {} }
  ],
  "policies": [
    { "name": "production-safety", "policyYaml": "...", "priority": 100, "enabled": true, "tags": ["github"], "version": 2 }
  ]
}

Returns Content-Disposition: attachment header for direct file download.

Import configuration

POST /api/dashboard/import

Import policies and agents from a JSON bundle. Requires owner role. Creates an audit trail entry (config.imported).

curl -X POST http://localhost:3000/api/dashboard/import \
  --cookie "tf_session=<session_token>" \
  -H "Content-Type: application/json" \
  -d @TameFlare-config.json

Response (200):

{ "policies_imported": 3, "agents_imported": 1, "errors": [] }

Note

Imported agents receive new API keys. Policies are created as new entries, not merged with existing ones. Any import errors are listed in the errors array.

Observability

Prometheus metrics

GET /api/metrics

Returns Prometheus-compatible metrics for monitoring. Protected by MAINTENANCE_SECRET bearer token.

curl http://localhost:3000/api/metrics \
  -H "Authorization: Bearer your-maintenance-secret"

Response (200, text/plain):

# HELP aaf_actions_total Total action requests
# TYPE aaf_actions_total counter
aaf_actions_total 1247

# HELP aaf_processes_active Currently active processes
# TYPE aaf_processes_active gauge
aaf_processes_active 3

# HELP aaf_actions_last_hour Actions in the last hour
# TYPE aaf_actions_last_hour gauge
aaf_actions_last_hour 42

# HELP aaf_decisions_24h Decisions by outcome in the last 24 hours
# TYPE aaf_decisions_24h gauge
aaf_decisions_24h{outcome="allow"} 180
aaf_decisions_24h{outcome="deny"} 25
aaf_decisions_24h{outcome="requires_approval"} 7

Tip

Point your Grafana or Datadog Prometheus scraper at /api/metrics to get real-time TameFlare dashboards. The endpoint is lightweight and safe to poll every 15–30 seconds.

Gateway connector actions

The Gateway executes actions on behalf of agents. Each connector supports a specific set of action types.

GitHub connector (11 actions)

| Action Type | Description | Key Parameters | |---|---|---| | github.pr.create | Create a pull request | title, body, head, base | | github.pr.merge | Merge a pull request | pr_number, branch_name, merge_method | | github.pr.comment | Comment on a pull request | pr_number, body | | github.pr.close | Close a pull request | pr_number | | github.branch.create | Create a branch | branch_name, source_branch | | github.branch.delete | Delete a branch | branch_name | | github.issue.create | Create an issue | title, body, labels | | github.issue.comment | Comment on an issue | issue_number, body | | github.issue.close | Close an issue | issue_number | | github.release.create | Create a release | tag_name, name, body, draft, prerelease | | github.file.commit | Commit a file change | path, content, message, branch |

All GitHub actions require resource.organization and resource.repository in the action spec. The Gateway authenticates using the GitHub PAT configured in Settings.

Webhook connector (5 actions)

| Action Type | HTTP Method | Description | |---|---|---| | webhook.post | POST | Send a POST request to a URL | | webhook.get | GET | Send a GET request to a URL | | webhook.put | PUT | Send a PUT request to a URL | | webhook.patch | PATCH | Send a PATCH request to a URL | | webhook.delete | DELETE | Send a DELETE request to a URL |

Webhook actions require parameters.url and optionally parameters.headers and parameters.body. The webhook connector is a generic HTTP client — use it to integrate with any API.

Response headers

All /api/* responses include standard headers:

| Header | Description | Example | |---|---|---| | X-Request-Id | Unique request identifier | req_m2abc1_x8k3f2 | | X-TameFlare-Version | Current TameFlare version | 0.6.0 |

These are injected by Next.js middleware on every API response — both public (/api/v1/*) and dashboard (/api/dashboard/*) routes. Use X-Request-Id when reporting issues or correlating logs.