Clear, deployable API documentation

API for mobile clients, desktop apps and automation around a Militant instance.

Installer · Docker · Quick start · Wiki · Security

Install

The easiest way is to use the dedicated installer:

mkdir -p militant-api-install
cd militant-api-install
curl -fsSLO https://gitlab.com/militant1/api-installer/-/raw/main/militant-api
chmod +x militant-api
./militant-api

The script:

• joins the correct Docker network
• connects the API to the main database
• handles uploads sharing
• generates .env.api
• generates docker-compose.api.yml

Useful commands:

• ./militant-api update
• ./militant-api uninstall

Dedicated guide: https://gitlab.com/militant1/api-installer

Requirements

• the main Militant app must already be running
• the API must be on the same Docker network
• the Militant database must be accessible
• if you want the same media, also share uploads

Fediverse (ActivityPub)

The API now exposes a complete mobile Fediverse surface through v1/fediverse.php: local profile, remote followers, remote following, @user@instance lookup, remote profile resolution, follow/unfollow actions, and a synchronized remote post feed. It also automatically triggers ActivityPub broadcasting when creating new posts using RSA HTTP Signatures.

See Endpoint documentation

Manual Docker

If you prefer to manage Compose yourself:

cp docker-compose.casaos.yml docker-compose.api.yml
docker compose -f docker-compose.api.yml up -d

Main variables:

• DB_HOST or API_DB_HOST: MySQL host of the Militant instance
• DB_NAME or API_DB_NAME: main database name
• DB_USER / DB_PASSWORD: SQL credentials
• MAIN_APP_HOST: internal web app URL on the Docker network, for example http://militant-web:80
• API_UPLOADS_PATH: internal media path, usually /var/www/uploads
• API_CORS_ORIGINS: * or allowed domain(s)
• API_REQUIRE_HTTPS: true for public HTTPS production

LiveKit (video live streams)

To issue LiveKit tokens server-side (POST /v1/lives.php?path=token), configure secrets:

• Environment variables (recommended in production): LIVEKIT_URL (wss://...), LIVEKIT_API_KEY, LIVEKIT_API_SECRET
• Or a local file ignored by git: config/livekit.local.php (generated from the web panel)
• Live details (GET /v1/lives.php?path={id}) may include background_image, which the owner can update through PUT /v1/lives.php?path={id}/background.

WebRTC / TURN (private calls, groups, 4G/5G)

For reliable mobile calling, especially on 4G/5G, configure a TURN server:

• Environment variables: WEBRTC_TURN_URLS, WEBRTC_TURN_AUTH_SECRET, WEBRTC_TURN_TTL, WEBRTC_TURN_REALM
• Or a local file ignored by git: config/turn.local.php (generated from the web panel)
• GET /v1/settings.php returns stun_servers, turn_servers, and webrtc_ice_servers
• if WEBRTC_TURN_AUTH_SECRET is set, the API generates temporary HMAC TURN credentials (recommended mode, compatible with coturn use-auth-secret)

Web panel (after signing in with a Militant user account):

• .../admin/login.php then .../admin/tokens.php
• .../admin/livekit.php: enter LiveKit credentials (account password required to save) — Militant technicians only (same as web app: users.is_admin = 1; fallback: is_technician or LIVEKIT_TECHNICIAN_USER_IDS)
• .../admin/turn.php: enter TURN / Coturn settings for the API and display the coturn snippet to copy
• On the Militant web app, technicians are managed in admin.php?tab=technicians (is_admin promotion / removal).

See also .env.example on GitLab for variable names.

Test

Once the API is running:

• index: http://localhost:9082/v1/index.php
• token admin login: http://localhost:9082/admin/login.php
• LiveKit configuration (after login): http://localhost:9082/admin/livekit.php
• TURN configuration (after login): http://localhost:9082/admin/turn.php
• healthcheck: http://localhost:9082/health-public.php

Example:

curl http://localhost:9082/v1/index.php

Quick token

curl -X POST http://localhost:9082/v1/auth.php \
  -H "Content-Type: application/json" \
  -d '{"username":"your_username","password":"your_password"}'

Use the token:

curl http://localhost:9082/v1/posts.php \
  -H "Authorization: Bearer YOUR_TOKEN"

Feature suggestions

Available endpoints:

GET /v1/feature_suggestions.php
GET /v1/feature_suggestions.php?filter=popular
GET /v1/feature_suggestions.php?id=12
GET /v1/feature_suggestions.php?action=stats
POST /v1/feature_suggestions.php
POST /v1/feature_suggestions.php?action=vote
POST /v1/feature_suggestions.php?action=comment
POST /v1/feature_suggestions.php?action=update_status
DELETE /v1/feature_suggestions.php?id=12

Example creation:

curl -X POST http://localhost:9082/v1/feature_suggestions.php \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Offline mode",
    "description": "Allow local consultation of suggestions and status when the network is unavailable."
  }'

Replies and reactions in messaging

Private messaging and message groups now support:

• replying to a message with parent_id
• user reactions on messages
• returning the parent message and reaction summary in message lists

Available endpoints:

GET /v1/messages.php?user_id=34
POST /v1/messages.php
POST /v1/messages.php?action=react
DELETE /v1/messages.php?action=react&message_id=56

GET /v1/message_groups.php?path=12/messages
POST /v1/message_groups.php?path=12/messages
POST /v1/message_groups.php?path=messages/78/reactions
DELETE /v1/message_groups.php?path=messages/78/reactions

Additional fields returned for private messages:

• parent_id
• parent_content
• parent_sender_username
• reactions_summary
• user_reaction

Additional fields returned for group messages:

• parent_id
• parent_content
• parent_username
• reactions_summary
• user_reaction

Example reply to a private message:

curl -X POST http://localhost:9082/v1/messages.php \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 34,
    "content": "Replying to your message",
    "parent_id": 56
  }'

Example reaction on a private message:

curl -X POST http://localhost:9082/v1/messages.php?action=react \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": 56,
    "reaction": "heart"
  }'

Example reply in a group:

curl -X POST http://localhost:9082/v1/message_groups.php?path=12/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "I will take this one",
    "parent_id": 78
  }'

Maintenance

If you use the dedicated installer:

./militant-api update

Otherwise with manual Docker Compose:

docker compose -f docker-compose.api.yml pull
docker compose -f docker-compose.api.yml up -d

Uninstall:

./militant-api uninstall

Bots

For bot and automation integrations, start with the included example:

• Keyword Relay Bot

Read more

• DEMARRAGE_RAPIDE.md: first test and first calls
• DOCKER.md: Docker and networking details
• GUIDE_SIMPLE.md: shortest version
• WIKI.md: broader endpoint documentation
• SECURITY.md: security model and production notes

---