Snowman API

This page contains everything you need to connect Snowman to your products, backends, and no‑code workflows. Below you’ll find a detailed explanation of key types, real request examples, and practical security guidance.

In short: create an API key in the “API access” section, pick the right type (Tenant/Scenario/Read‑only), copy one of the examples below, replace your domain and key — and you’re integrated.

1. Mental model

The API is intentionally simple: instead of complex REST objects, you work with clear, natural-language tasks. Snowman receives an instruction and decides how to execute it using the configured LLM and/or your Scheduler scenario.

One‑off run from a text prompt — POST /api/v1/run with a Tenant key. Great when you don’t have a formal Scheduler scenario yet, but you already know what you want done.
Run a saved Scheduler scenario — POST /api/v1/scenarios/{id}/run with a Scenario key. This is your production workflow you can trigger from external systems.

Authentication is the same everywhere: Authorization: Bearer <API_KEY>. No cookies or session tokens required — the API is fully stateless.

2. API key types

Manage keys

Snowman has three base key types. They’re not just different labels — each type has a different role and access scope. Switch tabs below to see explanations and request examples.

Tenant key: full technical API access

A Tenant key is your primary technical key for Snowman API. It is tied to a specific account (tenantId) and grants access to API capabilities within that tenant. Typically this key lives on the server side: in backend services, CRM/ERP integrations, enterprise buses, background jobs, etc.

With a Tenant key you can call the universal /api/v1/run endpoint. This is the fastest way to connect Snowman to an existing system: you send a plain-text instruction (Russian and English are supported) and receive a ready-to-use result.

Where to use: backend microservices, scheduled reporting, integrations with 1C / Bitrix24 / amoCRM / internal CRMs.
Auth: Authorization: Bearer <TENANT_API_KEY>.Authorization: Bearer <TENANT_API_KEY>.
Main endpoint: POST /api/v1/run — one‑off run from a prompt.
Limits: monthly call quota depends on your subscription plan.

curl example (single line)

You can copy/paste this into a terminal — just replace your domain and key.

curl -X POST "$BASE_URL/api/v1/run" \
  -H "Authorization: Bearer YOUR_TENANT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-raw '{"prompt":"Create a short summary of the latest orders from the last 24 hours"}'

What to replace:
$BASE_URL — the base URL of your Snowman web app (e.g., https://app.snegikom.ru or http://localhost:3000 in dev).
YOUR_TENANT_API_KEY — the Tenant key from the “API access” section. API access.

3. Endpoints and response formats

The table below is a quick cheat sheet of the main HTTP endpoints. Keep it nearby while integrating so you don’t have to remember which key type works where.

Method	Path	Key	Purpose
POST	/api/v1/run	Tenant	One‑off execution from a prompt. Returns a short text response from Snowman without linking to a specific Scheduler scenario.
POST	/api/v1/scenarios/{id}/run	Scenario	Run a preconfigured Scheduler scenario. All settings (LLM, schedule, connectors) are already defined in the task.
GET	/api/v1/scenarios/{id}/history	Scenario / Read‑only	Scenario run history: start/finish timestamps, status, and a short result summary.

4. Integration examples

Below are common integration patterns. All of them use the same base requests that you can adapt to your stack.

Node.js backend / CRM integration

Imagine an internal service that compiles daily lead stats from Bitrix24 or amoCRM and wants Snowman to turn the numbers into a manager-friendly summary.

// pseudo-code
const resp = await fetch("$BASE_URL/api/v1/scenarios/SCENARIO_ID/run", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SCENARIO_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: { date: "2025-01-01" } }),
});
const data = await resp.json();

n8n / Make / no‑code workflows

In any no‑code platform (n8n, Make, Zapier, Integromat, etc.), create an HTTP request and copy the settings from the example. You can trigger scenarios via webhook, on schedule, or from events in other systems.

METHOD: POST
URL:    $BASE_URL/api/v1/run
HEADERS:
  Authorization: Bearer YOUR_TENANT_API_KEY
  Content-Type: application/json
BODY (JSON):
  { "prompt": "Make a short summary of new amoCRM leads" }

Read‑only for BI and dashboards

If you’re building a unified data layer (Data Warehouse, Power BI, Metabase, Superset), you can poll scenario history and store results in your own database. That’s exactly what the read‑only key is for.

curl -s "$BASE_URL/api/v1/scenarios/SCENARIO_ID/history" \
  -H "Authorization: Bearer YOUR_READONLY_API_KEY" | jq '.history'

5. Pre‑production checklist

Confirm that your plan includes API keys and that your monthly API call limit is above zero. If the limit is zero, all requests will return plan_limit_reached.
Make sure a default LLM key is configured in your profile. Without it, /api/v1/run and scenarios can’t call the model and will return llm_not_configured.
For Scenario keys: first configure the task in the Scheduler, manually verify it works, and only then issue a Scenario key for it.
For BI/reporting access, always use a dedicated Read‑only key. It significantly reduces risk — even if someone sees the key, they can’t trigger actions.
Never hardcode secret keys in frontend code or public Git repositories. Store keys in environment variables, CI/CD secret stores, or a dedicated secret manager.