HTTP API

Use the HTTP API to manage campaign resources, launch campaigns, read results, and configure integrations. Requests go to the administrative listener, not the participant-facing listener.

Three interfaces, three purposes

Ruphish splits its HTTP interfaces into /api/, /auth/, and /internal/. This separation is part of the application architecture and matters when choosing an endpoint.

Prefix	Purpose	Intended consumer
/api/	Public resource and workflow API, including compatible Gophish endpoints and Ruphish additions	External integrations and the admin UI
/auth/	Browser authentication and session lifecycle	The admin UI and its sign-in flow
/internal/	Browser-specific account and application operations	The admin UI; not a supported external automation contract

Use an API key with /api/ for scripts. Do not automate the browser login flow or depend on /internal/ routes just because they appear in browser network requests. Browser sessions have their own cookie and CSRF requirements. See authentication.

Operational monitoring uses separate unauthenticated /health/live and /health/ready probes on every enabled listener. They are outside these administrator API namespaces.

Make your first request

After creating an account and completing its password setup, obtain its API key from account settings. The examples use curl and POSIX shell syntax. Replace the dummy values below with your administrative HTTPS origin, without a trailing slash, and your API key. Keep real keys out of saved scripts, shared examples, and shell history.

export RUPHISH_URL='https://ruphish.example.com'
export RUPHISH_API_KEY='replace-with-your-api-key'

curl --header "Authorization: Bearer $RUPHISH_API_KEY" \
  "$RUPHISH_URL/api/groups/"

A successful request returns a JSON array of your groups; a new account receives [].

If your installation uses a private CA, supply its certificate file explicitly:

export RUPHISH_CA_FILE='/path/to/your/ca.pem'

curl --cacert "$RUPHISH_CA_FILE" \
  --header "Authorization: Bearer $RUPHISH_API_KEY" \
  "$RUPHISH_URL/api/groups/"

Include --cacert "$RUPHISH_CA_FILE" in subsequent curl requests when using that private CA. Publicly trusted certificates normally need no custom CA file. Keep certificate validation enabled.

These variables are conventions for the example commands, not automatic Ruphish configuration overrides. In PowerShell, set variables with $env:RUPHISH_URL = 'https://ruphish.example.com' and read them as $env:RUPHISH_URL; use curl.exe and put the request on one line instead of using POSIX backslash continuations.

Choose a resource

Task	Reference
Understand requests, revisions, and failures	Conventions, errors
Manage reusable campaign content	Groups, templates, landing pages, sending profiles
Import or preview content	Imports and previews
Manage static explanations and campaign destinations	Learning pages
Select bundled campaign content	Starter templates
Prepare and launch a campaign	Campaigns, campaign drafts
Control installation policy or close active campaigns	Company settings
Verify a campaign origin	Domains
Read outcomes or download reports	Analysis and exports, overview
Manage application access	Users and API keys
Receive events or process reported mail	Webhooks, reporting mailboxes
Integrate with participant reporting or understand tracking requests	Participant endpoints

Ruphish adds draft persistence, campaign preparation and delivery controls, domain verification, analysis and exports, dashboard aggregates, and multiple reporting mailboxes. These are distinct from the compatible legacy resource endpoints. The compatibility guide explains that boundary.

These references describe the current source checkout. They are maintained from handlers, wire types, and tests; they are not a generated OpenAPI specification. Examples are illustrative unless their page explicitly records execution.