S-SHOT Templates API

Public /v1 API для шаблонов, запусков и датасетов

Canonical base URL: https://www.s-shot.ru/v1. Авторизация использует существующие пользовательские ключи ws_: Authorization: Bearer $S_SHOT_API_KEY. Контракт страницы синхронизирован с OpenAPI source: 13 public paths.

Endpoint inventory

Python SDK quickstart

Stable release gate: public package installation instructions are published only after the exact CI-built package artifact passes production-sandbox smoke and the production PyPI protected-token gate passes. The SDK workflow shape is fixed below for implementation and compatibility tests.

from sshot import SShot

client = SShot(api_key="ws_your_api_key")

run = client.template_runs.create(
    template_id="ozon-search-listings",
    parameters={"url": "https://www.ozon.ru/search/?text=coffee"},
    max_pages=5,
    dataset_name="Ozon coffee search",
)

run = client.template_runs.wait(run.id, timeout=300)

for row in client.template_runs.iter_rows(run.id, limit=100):
    print(row["title"], row.get("price"))

export = client.datasets.export_csv(run.dataset_id)
client.datasets.download_export(export, path="ozon-coffee-search.csv")

Run workflow

Creation endpoints require Idempotency-Key: POST /v1/template-runs and POST /v1/datasets/{dataset_id}/exports. Poll status, then page rows with limit and cursor.

curl -X POST "https://www.s-shot.ru/v1/template-runs" \
  -H "Authorization: Bearer $S_SHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "template_id": "ozon-search-listings",
    "parameters": { "url": "https://www.ozon.ru/search/?text=coffee" },
    "max_pages": 5,
    "dataset_name": "Ozon coffee search"
  }'

curl "https://www.s-shot.ru/v1/template-runs/trun_01HY.../rows?limit=100" \
  -H "Authorization: Bearer $S_SHOT_API_KEY"

Controls and diagnostics

cancel and resume are server-side safe and do not require client idempotency headers. Diagnostics are safe public data and use the same owner-scoped fail-closed access model.

• POST /v1/template-runs/{run_id}/cancel is repeat-safe.
• POST /v1/template-runs/{run_id}/resume returns an existing continuation run or creates one once.
• GET /v1/template-runs/{run_id}/diagnostics returns safe diagnostics only.

Dataset CSV export

V1 export is a dataset action for owned/private datasets. The response contains format, a relative download_url, and expires_at. The download endpoint streams CSV bytes and requires the same API key. public_utility datasets remain rows-paging-only and return dataset_export_unavailable for export/download.

curl -X POST "https://www.s-shot.ru/v1/datasets/ds_01HY.../exports" \
  -H "Authorization: Bearer $S_SHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "format": "csv" }'

curl "https://www.s-shot.ru/v1/datasets/exports/dlexp_01HY..." \
  -H "Authorization: Bearer $S_SHOT_API_KEY" \
  -o dataset.csv

Errors and access model

All errors use a normalized envelope. Owner-scoped resources fail closed with resource-specific not-found style errors instead of revealing ownership. Rate limits, quota, timeouts, invalid parameters, and export denial use public error codes from the OpenAPI enum.

{
  "error": {
    "code": "dataset_export_unavailable",
    "message": "Dataset export is unavailable.",
    "request_id": "req_01HY...",
    "details": []
  }
}