External APIs

miktingHttp can call any HTTP API. These examples cover request bodies, authentication, response handling, pagination, and webhooks. See Actions for every argument and Secrets for credential setup.

Make a request

This example sends a message as a query parameter and replies with a field from the JSON response:

- id: miktingHttp
  triggers: messageCreate
  args:
    method: GET                       # GET|POST|PUT|PATCH|DELETE|HEAD
    url: 'https://postman-echo.com/get'
    query: { hello: '%message_content%' }   # ?hello=...
    headers: { Accept: application/json }
    storeAs: echo
    follow-up-actions:
      - id: miktingReply
        args: { content: 'echo says: [[echo_json_args_hello]]' }

Put follow-up-actions under args. The follow-ups run after success or failure. A request sets status, success, body, JSON and response-header variables. storeAs creates namespaced copies. JSON fields are flattened into variable names, replacing dots with underscores. Use miktingJson { op: query, path: ... } for nested fields that are not available as flattened variables. Branch on the HTTP status or mikting_ok:

- id: miktingBranch
  args:
    when: '[[echo_status]] == 200'
    then: [{ id: miktingReply, args: { content: 'ok: [[echo_json_url]]' } }]
    else: [{ id: miktingReply, args: { content: 'API error: [[mikting_error]]' } }]

A condition can also handle a non-2xx status:

conditions:
  - id: miktingHttpOk
    args: { storeAs: echo }
    not-met-actions:
      - id: miktingReply
        args: { content: 'Backend is down, try later.' }

Send a body

A body is optional. When present, choose one form: json for a templated JSON object, form for URL-encoded fields, or text for a raw string.

- id: miktingHttp
  args:
    method: POST
    url: 'https://api.example.com/v1/notes'
    headers: { Authorization: 'Bearer {{secret.API_TOKEN}}' }
    json: { title: '[[note_title]]', body: '%message_content%' }
    storeAs: note

- id: miktingHttp
  args:
    method: PUT
    url: 'https://api.example.com/v1/notes/[[note_id]]'
    form: { title: '[[note_title]]', body: 'hello' }

Authenticate

Keep credentials in environment variables and refer to them by name. With the default MIKTING_ prefix, {{secret.API_TOKEN}} reads MIKTING_API_TOKEN. You can set the Authorization header directly or use the bearer/basic shortcuts:

headers: { Authorization: 'Bearer {{secret.API_TOKEN}}' }
# or:
auth: { type: bearer, tokenSecret: API_TOKEN }
auth: { type: basic, userSecret: API_USER, passSecret: API_PASS }

A missing secret sets mikting_error to missing_secret:NAME. The action’s follow-ups still run.

Set limits

Timeout defaults to 10 seconds, retries to one for idempotent methods, and the maximum response body to 1 MiB. POST requests are not retried. Cache only GET and HEAD responses using cacheTtlSec. Optional local rate limiting is off by default; when enabled, rejected requests set mikting_error to rate_limited. Webhook payloads default to 256 KiB.

timeoutMs: 10000   # abort + fail into mikting_error (default 10s)
retries: 2         # backoff retries (default 1)

Follow pagination

miktingHttpPaginate reads a next URL from a dot path or an RFC 5988 Link header and follows up to maxPages. It combines response items in the named array and reports the page count:

- id: miktingHttpPaginate
  args:
    url: 'https://api.example.com/v1/items'
    headers: { Authorization: 'Bearer {{secret.API_TOKEN}}' }
    nextPath: 'paging.next'
    maxPages: 5
    storeAs: items
    follow-up-actions:
      - id: miktingArray
        args: { op: len, input: '[[items]]', storeAs: total }
      - id: miktingReply
        args: { content: 'Fetched [[total]] items.' }

Send to a Discord webhook

miktingWebhookSend sends a Discord webhook request. Store the URL in an environment secret:

- id: miktingWebhookSend
  args:
    url: '{{secret.ALERTS_WEBHOOK}}'
    content: 'Deploy finished: [[hook_body_repo]]'

Complete examples

The examples/ directory contains a GET request, a JSON API flag gate, and a webhook relay. Those files show the full script configuration. Documentation home · Source Markdown

Getting Started

Scripting

Make a request

Send a body

Authenticate

Set limits

Send to a Discord webhook

Complete examples

​Make a request

​Send a body

​Authenticate

​Set limits

​Follow pagination

​Send to a Discord webhook

​Complete examples

Make a request

Send a body

Authenticate

Set limits

Follow pagination

Send to a Discord webhook

Complete examples