> ## Documentation Index
> Fetch the complete documentation index at: https://mikting.docs.komo.moe/llms.txt
> Use this file to discover all available pages before exploring further.

# External APIs

> Request and response examples for real HTTP APIs.

`miktingHttp` can call any HTTP API. These examples cover request bodies,
authentication, response handling, pagination, and webhooks. See
[Actions](https://mikting.docs.komo.moe/actions.md) for every argument and [Secrets](https://mikting.docs.komo.moe/secrets.md)
for credential setup.

## Make a request

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

```yaml theme={null}
- 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`:

```yaml theme={null}
- 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:

```yaml theme={null}
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.

```yaml theme={null}
- 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
```

```yaml theme={null}
- 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:

```yaml theme={null}
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.

```yaml theme={null}
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:

```yaml theme={null}
- 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:

```yaml theme={null}
- 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](https://mikting.docs.komo.moe/index.md) · [Source Markdown](https://gitlab.com/komomori/mikting/-/blob/main/docs/mikting-external-apis.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.