Send an HTTP request
miktingHttp uses Node.js’s global fetch implementation. It supports GET,
POST, PUT, PATCH, DELETE, and HEAD. A body is optional. When you send one,
choose json, form (URL-encoded), or text. Headers and query parameters
support templating. Use auth for bearer or basic authentication stored in
secrets.
Requests time out after 10 seconds by default. retries defaults to one retry
for idempotent methods, not POST. The response size limit defaults to 1 MiB.
GET and HEAD responses can be cached with cacheTtlSec; the cache key includes
the method, URL, body, and a hash of Authorization. Responses with
Set-Cookie or Cache-Control: no-store or private are not cached. The
client sends User-Agent: Mikting/1.0 by default.
Rate limiting is disabled by default. Configure rateLimit.enabled,
maxPerMinPerGuild (default 60), and maxParallel (default 5) to limit event
traffic. Requests rejected by the local limit set mikting_ok to false and
mikting_error to rate_limited.
Responses and errors
mikting_ok means the server returned a 2xx status. It does not validate JSON
or an API-specific schema. Ordinary text responses are supported. Use an
optional responseCheck when an API response must satisfy a known contract.
Supported checks cover OpenAI moderation, OpenAI or Groq policy responses, and
TypeSafe Jev Noul responses. Debug checks can format a private report for the
same providers; see Debug checks.
A non-2xx response sets error variables and preserves its status, body, and
available headers. Missing secrets, local rate limits, timeouts, and network
failures set ok to false and use status zero when no HTTP response arrived.
Follow-up actions still run after a request fails.
Each request clears the current output namespace before it runs, including old
JSON fields, headers, validation values, and key-slot labels. It preserves
other storeAs namespaces. Request templates can read earlier response
values. The generic mikting_error remains available across the action chain;
the current namespaced error is cleared before its new request.
Bearer auth.tokenSecret keys can rotate through numbered slots. Rotation is
shared by provider origin and base name. Unauthorized keys are excluded, and
429 responses pause the pool according to Retry-After. Requests are not
replayed across keys. This helps distribute credentials but does not raise a
provider’s organization quota. See Secrets.
Check a JSON response
This example branches on a JSON boolean. For a strict API contract, add aresponseCheck and also require its valid output before acting:
Receive a webhook
Mikting runs onenode:http listener. GET /health returns a small health
response. A POST to {hookPrefix}/:hookId (default
/mikting/hooks/:hookId) emits miktingWebhook:<hookId> with hook_id,
hook_body, and flattened hook_body_<path> variables. Payloads default to a
256 KiB limit; larger requests receive 413.
Set MIKTING_HOOK_<ID> to require HMAC signatures for a hook. Use the hook ID
in uppercase and replace hyphens with underscores. Without a configured
secret, the hook remains open for compatibility and logs a warning. The legacy
signature is HMAC-SHA256 of the raw body in x-mikting-sig. The timestamped
format also sends x-mikting-ts and signs <timestamp>.<raw_body>; timestamps
must be within five minutes. Invalid signatures receive 401.
A webhook trigger can use the payload like this:
server.autoDetect enabled, Mikting reads SERVER_PORT, ALLOC_PORT,
or PORT, and SERVER_IP. The public URL prefers PUBLIC_DOMAIN, then
baseUrl, then the configured host and port. /mikting-status shows the URL.
Use hard-to-guess hook IDs and configure a secret when a hook can trigger
moderation or role changes.
Documentation home · Source Markdown