Implemented API ยท OpenAPI 3.1

HeliumRises Connect API

Production reference generated from the implemented routes. Versioned automation authoring is available; enrollment and execution are not implemented. Protected legacy reconstruction is a non-production local CLI and is deliberately absent from the public API.

Authentication and errors

Agents send a GFAVIP Wallet bearer token. Never send a PowerLobster API key to Connect. Humans may use the browser session; mutating session API calls also need X-CSRF-Token. API success bodies are JSON. Current error bodies are Flask text/html; handle the HTTP status and retain X-Correlation-ID.

Safety classes

Database-only

Preview, authoring, drafts, eligibility, and synthetic rehearsal do not contact recipients.

External checks

Provider and domain verification may read Mailgun or DNS but do not send email.

Allowlisted delivery

Test sends and controlled rehearsals may contact Mailgun and one configured recipient.

Production path

Scheduling fails closed unless every global, workspace, provider, domain, sender, consent, and approval gate is open.

Role and capability matrix

Capabilityownerbrand_admineditoranalyst
viewyesyesyesyes
upsert_contactsyesyesyesno
edit_contentyesyesyesno
edit_automationsyesyesyesno
send_testyesyesyesno
schedule_campaignyesyesyesno
manage_sendersyesyesnono
pause_deliveryyesyesnono
resolve_suppressionsyesyesnono
manage_subscription_sourcesyesyesnono

manage_subscription_sources governs the console-only administration of external intake sources and their credentials. It has no JSON API: a credential that can write contacts into audiences is never mintable by an agent token. edit_automations governs database-only workflow authoring. generate_ai_content remains a forward-compatible policy name with no implemented API. Archived workspaces remove test-send, scheduling, and delivery-control capabilities.

Empty-workspace onboarding

  1. Confirm membership and role.
  2. Load contacts and an audience with provenance.
  3. Review consent and suppressions.
  4. Configure the secret-reference-only Mailgun provider.
  5. Verify the sending domain and create a sender identity.
  6. Create and preview a versioned template.
  7. Run an allowlisted test and controlled rehearsal.
  8. Run the synthetic capacity rehearsal when owner-approved.
  9. Run preflight and clear every blocking check.
  10. Create a campaign draft; do not schedule without production approval.

Implemented endpoints

Capability and safety labels are part of the OpenAPI contract.

GET /healthz

Process health

Capability
public
Safety
public health check
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/healthz'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /readyz

Database readiness

Capability
public
Safety
public health check
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/readyz'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /preferences/{token}

Apply a signed preference unsubscribe

Capability
valid signed preference token
Safety
suppression-increasing-public-action
Idempotency
Safe to repeat; unsubscribe state remains restrictive.

A validly signed token is honoured however old it is. `PREFERENCE_TOKEN_MAX_AGE_SECONDS` decides when the hosted page tells the reader the link came from an older email, not when the link stops working: refusing an aged unsubscribe leaves the reader with no way out but a spam report. Aged use is recorded on the audit event as `link_expired`. Forged, tampered, and foreign-key tokens are still refused with 400.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/preferences/{token}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /preferences/one-click/{token}

Apply an RFC 8058 one-click unsubscribe

Capability
valid signed preference token
Safety
suppression-increasing-public-action
Idempotency
Safe to repeat; unsubscribe state remains restrictive.

A validly signed token is honoured however old it is, so a mail client's own unsubscribe button keeps working on an old message. Aged use is recorded on the audit event as `link_expired`. Forged, tampered, and foreign-key tokens are still refused with 400.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/preferences/one-click/{token}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /webhooks/mailgun/{connection_id}

Receive and deduplicate a signed Mailgun event

Capability
valid Mailgun webhook signature
Safety
signed-provider-event-processing
Idempotency
Deduplicated by provider connection and Mailgun event ID.

Provider callback. Accepts JSON or Mailgun form fields whose `event-data` and `signature` values are JSON strings.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/webhooks/mailgun/{connection_id}' \
  -H 'Content-Type: application/json' \
  --data '{"event-data": {"event": "delivered", "id": "provider-event-id", "timestamp": 1784937600}, "signature": {"signature": "provider-supplied-hmac", "timestamp": "1784937600", "token": "provider-supplied-token"}}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/me

Get validated identity and local memberships

Capability
authenticated
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

The live response contains `user`, `auth_method`, `csrf_token`, and `workspaces`. There is no top-level `memberships` field.

Example request and response

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/me' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Example response

{
  "auth_method": "bearer",
  "csrf_token": null,
  "user": {
    "gfavip_user_id": "stable-wallet-user-id",
    "identity_type": "agent",
    "platform_role": null,
    "username": "pl-arthur-blaze"
  },
  "workspaces": [
    {
      "is_archived": false,
      "organization": "gfa-community",
      "role": "editor",
      "workspace": "gfa-community"
    }
  ]
}

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/workspaces

List locally assigned workspaces

Capability
authenticated
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/workspaces' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/events

Record explicit consent from an approved source

Capability
active subscription-source credential, or a grant token whose scope names this source and includes events.write
Safety
consent-ingestion-only
Idempotency
Required Idempotency-Key. Exact replay returns the original receipt as duplicate; a changed payload returns 409.

Source-only ingestion for MemoUpdate. The credential is fixed to one workspace, one source, that source's origin allowlist, and the audiences that source allows -- either its exact audience allowlist or, for a source created with `allows_all_audiences`, any live audience in its own workspace. This operation cannot schedule or send.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/events' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"captured_at": "2026-07-29T00:00:00Z", "consent": {"privacy_policy_url": "https://lifeisshortdoitnow.com/privacy", "privacy_policy_version": "2026-07-29", "wording_id": "newsletter-v1", "wording_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}, "consent_granted": true, "contact": {"email": "synthetic-phase5@example.test", "first_name": "Synthetic"}, "destination_audience_id": "22222222-2222-4222-8222-222222222222", "schema_version": "connect.subscription-source-event.v1", "source": {"evidence_schema_version": "memoupdate.newsletter-consent-capture.v1", "form_id": "synthetic-form", "form_version": "1", "page_origin": "https://my.lifeisshortdoitnow.com"}, "source_event_id": "11111111-1111-4111-8111-111111111111"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/audiences

List the audiences this source may write to

Capability
active subscription-source credential, or a grant token whose scope names this source and includes audiences.read
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

Read-only companion to the ingest route, for a caller building an audience picker. Returns exactly the audiences this source may write to, minus archived ones -- its audience allowlist, or every live audience in its own workspace when it was created with `allows_all_audiences` -- so a rendered picker cannot offer a choice ingestion would refuse. A static source credential carries no scope and reaches this route on whatever the source itself allows. A grant token must carry `audiences.read` in its scope; a grant scoped only to `events.write` is refused here, so a caller needing both lists both.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/audiences' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources

List the workspace's subscription sources

Capability
manage_subscription_sources
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

For a caller attaching to an existing source rather than creating a near-duplicate. Each entry carries the source's id, which is what a grant scope names -- never its slug, which is unique only within one workspace. No credential is ever included.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources

Create a subscription source

Capability
manage_subscription_sources
Safety
database-only
Idempotency
Not idempotent. Creating the same slug twice returns 409 rather than the existing source.

Creates the source and returns it, including its id, so the caller can build a grant scope naming it. Mints no credential and none is needed: a source created this way is expected to authenticate with a Wallet grant scoped to that id. Issuing, rotating and revoking a static credential remain console-only, because that flow shows a secret exactly once. Choose how the source allows audiences: `allowed_audience_ids` is required, naming at least one live audience in this workspace, unless `allows_all_audiences` is true; with the flag true it must be absent, null or empty, and a non-empty list beside it is a `422` rather than a resolution of the two.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"allowed_audience_ids": ["22222222-2222-4222-8222-222222222222"], "allowed_origins": ["https://my.lifeisshortdoitnow.com"], "display_name": "MemoUpdate signup form", "slug": "memoupdate-signup"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

PATCH /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/origins

Replace a source's allowed origins

Capability
manage_subscription_sources
Safety
database-only
Idempotency
Idempotent: replaces the complete origin list, so repeating the same request leaves the source in the same state.

Takes the complete list, never a delta. This set decides whether a live submission is accepted, so a partial apply would surface as signups quietly not arriving rather than as an error. The slug cannot be changed here: it is in the URL every live form posts to.

Example request

Request

curl -sS -X PATCH \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/subscription-sources/{source_slug}/origins' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"allowed_origins": ["https://my.lifeisshortdoitnow.com"]}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}

Get workspace role, capabilities, and send state

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/upsert

Create or update a contact

Capability
upsert_contacts
Safety
database-only
Idempotency
Idempotent by normalized email; source identity conflicts return 409.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/upsert' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"country_code": "US", "email": "person@example.com", "first_name": "Person", "source": "approved-form", "tags": ["newsletter"]}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv

List protected CSV imports

Capability
view
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv

Upload a protected CSV

Capability
upsert_contacts
Safety
encrypted-upload-only
Idempotency
Not idempotent. The response job ID and file checksum identify the durable upload; do not retry after receiving 201.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}

Inspect a protected CSV import

Capability
view
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

PATCH /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/mapping

Configure mapping and queue a zero-write dry run

Capability
upsert_contacts
Safety
zero-write-analysis-queue
Idempotency
Repeatable before approval. Reconfiguration invalidates any prior report and approval.
Example request

Request

curl -sS -X PATCH \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/mapping' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"consent_policy": "status_column", "mapping": {"email": "Email", "first_name": "First Name", "status": "Status"}, "policy": {"consent_basis": "Documented newsletter opt-in field.", "consent_source": "documented-event-registration", "default_status": "review_required", "evidence_reference": "approved-registration-export", "static_tags": ["event"], "status_values": {"subscribed": "subscribed", "unsubscribed": "audience_unsubscribe"}, "wording_version": "event-form-v2"}}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/approve

Approve a checksum-bound import apply

Capability
approve_imports
Safety
database-import-queue
Idempotency
Approval is checksum-bound and accepted once. Apply uses a per-row idempotency ledger.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/approve' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "APPLY CSV IMPORT job-id TO gfa-community/gfa-community"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/cancel

Cancel an import and destroy its payload

Capability
upsert_contacts
Safety
destructive-payload-cleanup
Idempotency
Terminal cleanup operation. A cancelled or purged payload cannot be restored.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/cancel' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/retry

Retry a failed import safely

Capability
upsert_contacts
Safety
idempotent-recovery-queue
Idempotency
Only failed jobs are accepted. A still-valid checksum-bound approval retries apply; otherwise the job returns to dry run.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv/{job_id}/retry' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv-mapping-profiles

List reusable CSV mapping profiles

Capability
view
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/imports/csv-mapping-profiles' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations

List non-executable automation definitions

Capability
view
Safety
read-only-authoring
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

Returns workspace-local immutable authoring state. Phase 5B has no enrollment, execution, activation, provider, or webhook path.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations

Create a validated automation draft and immutable version

Capability
edit_automations
Safety
database-only-authoring
Idempotency
Not idempotent. Automation slug uniqueness prevents duplicate workspace definitions.

Validates graph structure and workspace dependencies. Makes zero provider or webhook calls and creates no enrollment.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"change_notes": "Initial non-executable shell", "definition": {"edges": [], "nodes": [{"config": {}, "key": "finish", "type": "end"}], "start_node": "finish", "trigger": {"config": {}, "type": "manual"}}, "description": "Authoring-only synthetic workflow", "name": "Lead magnet delivery", "slug": "lead-magnet-delivery"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}

Inspect an automation and immutable version history

Capability
view
Safety
read-only-authoring
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions/{version_id}

Inspect one immutable automation version

Capability
view
Safety
read-only-authoring
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions/{version_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions

Append a validated immutable automation version

Capability
edit_automations
Safety
database-only-authoring
Idempotency
Not idempotent. Each accepted request appends a new immutable version.

Resets review-ready state to draft. Does not change or migrate historical versions.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"change_notes": "Reviewed source definition", "definition": {"edges": [], "nodes": [{"config": {}, "key": "finish", "type": "end"}], "start_node": "finish", "trigger": {"config": {}, "type": "manual"}}}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/ready-for-review

Mark the current checksum-bound version ready for review

Capability
edit_automations
Safety
database-only-review-state
Idempotency
Safe to repeat for the same current version and checksum. This is not activation or approval to execute.

Records an authoring milestone only. It cannot enroll contacts, schedule steps, send email, call a webhook, or open a gate.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/ready-for-review' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"definition_checksum": "sha256-definition-checksum", "version_id": "automation-version-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/archive

Archive an automation authoring definition

Capability
edit_automations
Safety
database-only-authoring
Idempotency
Safe to repeat; the authoring definition remains archived.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/archive' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/restore

Restore an archived definition as a draft

Capability
edit_automations
Safety
database-only-authoring
Idempotency
Accepted only while archived; a repeated request after restore returns 422.

Restores authoring only and cannot activate execution.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/restore' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/enrollments

List synthetic-only durable automation enrollments

Capability
view
Safety
read-only-runtime-observability
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

Production currently returns an empty collection.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/enrollments' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automation-enrollments/{enrollment_id}

Inspect a synthetic enrollment timeline

Capability
view
Safety
read-only-runtime-observability
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automation-enrollments/{enrollment_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions/{version_id}/synthetic-enrollments

Create an idempotent non-production synthetic enrollment

Capability
edit_automations
Safety
synthetic-only-runtime
Idempotency
Required Idempotency-Key; replay returns the original row.

Hard-blocked in production. Accepts only archived synthetic workspaces and `.invalid` contacts bound to a rehearsal ID.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automations/{automation_id}/versions/{version_id}/synthetic-enrollments' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"contact_id": "synthetic-contact-id", "synthetic_context_id": "synthetic-rehearsal-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automation-enrollments/{enrollment_id}/{action}

Pause, resume, cancel, or replay synthetic runtime state

Capability
pause_delivery
Safety
synthetic-only-runtime-control
Idempotency
State-machine constrained; invalid repeats return 409.

Hard-blocked while the Phase 5D runtime gate is closed.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/automation-enrollments/{enrollment_id}/{action}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"reason": "synthetic operator rehearsal", "step_id": "failed-synthetic-step-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contact-field-definitions

Create the next typed custom-field definition

Capability
upsert_contacts
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contact-field-definitions' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"field_key": "industry", "field_type": "single_choice", "label": "Industry", "options": ["commerce", "technology"]}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/lookup

Look up a contact by normalized email

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/lookup' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences

Create an audience

Capability
upsert_contacts
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"minimum_interval_seconds": 604800, "name": "Weekly newsletter", "purpose": "Weekly GFA community update", "slug": "weekly-newsletter"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences

List the workspace's audiences

Capability
view
Safety
read-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

Every audience in the workspace, for a caller rendering a picker. Archived audiences are included and flagged rather than omitted: a caller needs to know one exists and cannot be chosen, since its absence would otherwise read as a missing audience.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}

Inspect an audience

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/archive

Archive an audience

Capability
upsert_contacts
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/archive' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/subscribe

Record consent and activate audience membership

Capability
upsert_contacts
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Refuses with 422 when an unresolved Suppression blocks the contact -- platform-wide, scoped to this workspace, or scoped to this audience -- naming the blocking scope and reason in the error. There is no parameter to override this. Resolve the suppression first via POST /suppressions/{suppression_id}/resolve (resolve_suppressions capability), then call subscribe again.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/subscribe' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"contact_id": "contact-id", "evidence": {"captured_at": "2026-07-25T00:00:00Z"}, "source": "approved-form", "wording_version": "newsletter-v1"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/unsubscribe

Unsubscribe a contact from an audience

Capability
upsert_contacts
Safety
database-only
Idempotency
Safe to repeat; the resulting audience permission remains unsubscribed.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/audiences/{audience_id}/unsubscribe' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"contact_id": "contact-id", "source": "authorized_api"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/suppress

Create a safety suppression

Capability
resolve_suppressions
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/suppress' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"reason": "manual", "scope": "workspace", "source": "authorized_api"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/suppressions/{suppression_id}/resolve

Resolve an eligible suppression

Capability
resolve_suppressions
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Platform-scope safety suppressions also require a platform owner or administrator.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/suppressions/{suppression_id}/resolve' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"resolution_reason": "Reviewed and cleared by an authorized operator"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/eligibility/{audience_id}

Evaluate centralized send eligibility

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.

Read-only evaluation. It never contacts Mailgun or a recipient.

Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/eligibility/{audience_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/preference-token

Issue scoped preference and one-click URLs

Capability
upsert_contacts
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/contacts/{contact_id}/preference-token' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"audience_id": "audience-id", "scope": "audience"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains

Create a sender-domain readiness record

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"domain_name": "mail.example.com", "tracking_domain": "track.example.com"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/readiness

Update manually recorded domain readiness

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/readiness' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"alignment_state": "not_checked", "dkim_state": "pending", "dmarc_state": "pending", "notes": "Pending live verification", "quota_state": "not_checked", "spf_state": "pending", "verification_state": "pending"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/provider

Associate a Mailgun connection and DKIM selector

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/provider' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"dkim_selector": "smtp", "provider_connection_id": "provider-connection-id", "provider_domain_reference": "mail.example.com"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/verify

Run live DNS and Mailgun domain verification

Capability
manage_senders
Safety
external-read-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Performs DNS lookups and Mailgun status reads. It sends no email.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sending-domains/{domain_id}/verify' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sender-identities

Create a disabled sender identity

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sender-identities' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"display_name": "GFA Community", "from_address": "news@mail.example.com", "reply_to": "support@example.com", "sending_domain_id": "sending-domain-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sender-identities/{sender_id}/activate

Activate a sender behind production gates

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Requires `ACTIVATE PRODUCTION SENDING` and closed-by-default global activation gates.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/sender-identities/{sender_id}/activate' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "ACTIVATE PRODUCTION SENDING"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/activate-sending

Activate workspace production sending

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Requires `ACTIVATE PRODUCTION SENDING`, a ready sender, and all global activation gates.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/activate-sending' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "ACTIVATE PRODUCTION SENDING"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections

Create a secret-reference-only Mailgun connection

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"credential_env_key": "MAILGUN_API_KEY_GFA", "name": "Mailgun US", "region": "us", "webhook_signing_env_key": "MAILGUN_WEBHOOK_SIGNING_KEY_GFA"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections/{connection_id}/check

Test the Mailgun connection

Capability
manage_senders
Safety
external-read-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Contacts Mailgun for an account-level check but sends no email.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections/{connection_id}/check' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections/{connection_id}/activate

Enable a verified connection for test activity

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Requires the exact confirmation `ENABLE TEST CONNECTION`. This does not enable production sending.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-connections/{connection_id}/activate' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "ENABLE TEST CONNECTION"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates

Create an email-template container

Capability
edit_content
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"description": "Versioned weekly newsletter", "name": "Weekly update", "slug": "weekly-update"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates/{template_id}/archive

Archive or restore an email template

Capability
edit_content
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Shelves the template container. Send `{"archived": false}` to restore it; an empty body archives. Content versions are untouched, and a campaign already referencing one keeps working. The slug stays reserved either way, since slugs are unique per workspace whether or not the template is archived.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates/{template_id}/archive' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"archived": true}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates/{template_id}/versions

Create an immutable sanitized content version

Capability
edit_content
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Database-only authoring. It sends no email. The submitted HTML is sanitized against an allowlist before it is stored, and only the sanitized copy is ever sent. Check `validation.stripped` on the response: it lists tags, attributes, and CSS properties the sanitizer removed. Non-empty lists mean the stored email no longer looks like what was submitted. /skill.md documents the allowlist and the house email structure.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/email-templates/{template_id}/versions' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"html": "\u003cp\u003eHello {{ first_name }}\u003c/p\u003e\u003cp\u003e\u003ca href=\"{{ unsubscribe_url }}\"\u003eUnsubscribe\u003c/a\u003e\u003c/p\u003e", "personalization_defaults": {"first_name": "there"}, "plain_text": "Hello {{ first_name }}\n\nUnsubscribe: {{ unsubscribe_url }}", "preheader": "This week\u0027s GFA update", "subject": "Hello {{ first_name }}"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts

Create a campaign draft

Capability
edit_content
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Database-only draft creation. It schedules and sends nothing.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"audience_id": "audience-id", "content_version_id": "content-version-id", "name": "Weekly GFA update", "notes": "Draft only", "sender_identity_id": "sender-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts/{campaign_id}/versions

Append an immutable campaign draft version

Capability
edit_content
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts/{campaign_id}/versions' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"audience_id": "audience-id", "content_version_id": "content-version-id", "name": "Weekly GFA update", "notes": "Draft only", "sender_identity_id": "sender-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/test-sends

Queue a tightly gated allowlisted test email

Capability
send_test
Safety
may-contact-mailgun-and-one-allowlisted-recipient
Idempotency
Required `Idempotency-Key`; a replay returns the original request with 200.

Requires `SEND TEST EMAIL`, an allowlisted recipient, verified domain, active provider, and test-send configuration gate.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/test-sends' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "SEND TEST EMAIL", "content_version_id": "content-version-id", "recipient_email": "allowlisted@example.com", "sender_identity_id": "sender-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/rehearsals

Start a controlled provider-event rehearsal

Capability
send_test
Safety
may-contact-mailgun-and-one-allowlisted-recipient
Idempotency
Required `Idempotency-Key`; a replay returns the original rehearsal with 200.

Queues one gated test email and observes signed Mailgun events. It is not a marketing send.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/rehearsals' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "RUN CONTROLLED REHEARSAL", "content_version_id": "content-version-id", "recipient_email": "allowlisted@example.com", "sender_identity_id": "sender-id"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/rehearsals/{rehearsal_id}

Inspect controlled rehearsal reconciliation

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/rehearsals/{rehearsal_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts/{campaign_id}/schedule

Create an immutable scheduled campaign run

Capability
schedule_campaign
Safety
production-delivery-path
Idempotency
Required `Idempotency-Key`; a replay for the same campaign returns the original run with 200.

Fails closed unless every global, workspace, provider, domain, sender, content, and production-sending gate is open.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-drafts/{campaign_id}/schedule' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"scheduled_for": "2026-08-01T10:00:00+07:00"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}

Inspect a campaign run

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/report

Inspect per-recipient delivery outcomes and reconciled reporting

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/report' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/unschedule

Cancel a still-pending schedule

Capability
schedule_campaign
Safety
database-only
Idempotency
Not replay-safe after the run leaves `scheduled`; later calls return 422.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/unschedule' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/{action}

Pause, resume, or cancel a campaign run

Capability
pause_delivery
Safety
delivery-control
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-runs/{run_id}/{action}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-webhook

Configure where campaign lifecycle events are POSTed

Capability
manage_senders
Safety
database-only
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

Sets or clears the URL Console is notified at when a campaign is scheduled, completes, is cancelled, or fails, and the secret sent as a plaintext X-Webhook-Secret header on every delivery for the receiver to compare. A key absent from the body leaves that field unchanged. A workspace with no URL configured emits nothing. The secret is write-only and never appears in the response.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/campaign-webhook' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"campaign_webhook_secret": "whsec_example", "campaign_webhook_url": "https://console.gfavip.com/webhooks/campaign-events"}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-events/{event_id}/replay

Replay a stored verified provider event

Capability
pause_delivery
Safety
database-only-event-reprocessing
Idempotency
Provider-event processing is deduplicated by the stored provider event.
Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/provider-events/{event_id}/replay' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/preflight

Get the latest launch preflight

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/preflight' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/preflight

Run the fail-closed launch preflight

Capability
manage_senders
Safety
read-only-checks-with-retained-report
Idempotency
Not guaranteed idempotent; check operation-specific retry behavior.

May perform readiness inspection but sends no email and opens no gates.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/preflight' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

POST /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/synthetic-rehearsals

Queue an isolated synthetic capacity rehearsal

Capability
manage_senders
Safety
synthetic-database-only
Idempotency
Required body `idempotency_key`; a replay returns the original run with 200.

Uses no subscriber data, makes zero provider calls, sends no email, and rolls back synthetic operational rows.

Example request

Request

curl -sS -X POST \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/synthetic-rehearsals' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"confirmation": "RUN 10000 SYNTHETIC REHEARSAL", "idempotency_key": "synthetic-capacity-10000-0001", "recipient_count": 10000}'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.

GET /api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/synthetic-rehearsals/{run_id}

Inspect a synthetic capacity rehearsal

Capability
view
Safety
database-only
Idempotency
Safe and idempotent read-only operation; repeating it does not change server state.
Example request

Request

curl -sS -X GET \
  'https://connect.heliumrises.com/api/v1/organizations/{organization_slug}/workspaces/{workspace_slug}/operations/synthetic-rehearsals/{run_id}' \
  -H 'Authorization: Bearer $GFAVIP_TOKEN'

Replace path placeholders and example identifiers with values from your workspace. Exact schemas and errors remain authoritative in OpenAPI JSON.