Build with PyroSync

Generated from renderBuildWithPyroSyncGuide(). Regenerate this page from that function. Do not edit it by hand.

PyroSync exposes one platform through several surfaces. All of them call the same /api/v1 API with the same API keys, errors, pagination and rate limits. Choosing a surface is about where your code runs and who is driving it, not about what data you can reach.

Which surface to use

You want to	Use	Why
Call PyroSync from a service in TypeScript, Python, Go, Rust or Java	SDKs (TypeScript, Python, Go, Rust, Java)	Retries, pagination and typed errors are already done.
Call PyroSync from another language, or reach an endpoint no SDK wraps	REST API (/api/v1)	Every surface is built on the same /api/v1 contract.
Run a one-off job, export results or tail logs	CLI (pyrosync)	No code to write, and it scripts cleanly in CI.
Keep sources, mappings and workflows in version control and review changes	Infrastructure as code (GitOps)	Pull requests show the plan, and drift flags dashboard edits.
Let Claude, Cursor or VS Code work with your PyroSync data	MCP server	Standard MCP, limited by the key’s grants and a local rate cap.
Give your own agent web search, scraping and SQL	Agent tools and framework integrations	Drop-in tool definitions, with no framework dependency forced on you.
Do something when a job finishes or data changes	Webhooks	Signed push delivery instead of polling.
Connect PyroSync to other apps without code	No-code automation (n8n, Zapier, Make)	Event triggers and actions in the tools your team already uses.
Show a dataset to your customers inside your product	Embeds	Signed, per-viewer tokens. Column and row limits are enforced on your server and by the key.
Scrape a page and store the result on a schedule	Infrastructure as code (GitOps) + Webhooks	Declare the workflow once, then react when each run lands.

What every surface shares

• Auth. An API key from the dashboard, sent as X-API-Key (or Authorization: Bearer). Key scopes and resource grants apply on the server, whichever surface sends the call.
• Base URL. Your deployment origin, for example https://app.pyrosync.com. Self-hosted deployments use their own origin.
• Contract. Errors carry a stable code and a request id. Lists use cursor pagination. Responses carry rate-limit headers. Breaking changes are announced in the changelog with a sunset date first.

• Errors
• Lists, filters, and pagination
• Request signing
• Versioning and deprecation
• API status and performance budgets

Surfaces

REST API (/api/v1)

The canonical HTTP API. Every other surface is built on it.

• Best for: Any language, or the endpoints no client wraps yet.
• Not for: Hand-writing retries, pagination and signature checks when an SDK already does them.
• First step: Create an API key in the dashboard, then call GET /api/v1 with an X-API-Key header.
• Availability: Live on every deployment. The platform OpenAPI document is also served at /api/v1/platform-openapi.json.
• Where: docs/dev/platform-openapi.json, docs/dev/api-surface.md, docs/dev/api-compatibility.md

SDKs (TypeScript, Python, Go, Rust, Java)

Typed clients with retries, cursor pagination, request ids on errors and webhook verification.

• Best for: Backend services and scripts in one of the five languages.
• Not for: Long-lived configuration you want reviewed in pull requests: use GitOps instead.
• First step: Install from source, set PYROSYNC_API_KEY, and list targets (see /developers/sdks).
• Availability: Install from this repository. No SDK is on a package registry yet.
• Where: packages/sdk, sdks/python, sdks/go, sdks/rust, sdks/java, sdks/E2E.md

CLI (pyrosync)

Terminal access to sources, datasets, mappings, workflows, queries, logs and exports.

• Best for: One-off operations, shell pipelines and CI scripts.
• Not for: Application code: call an SDK instead of shelling out.
• First step: pyrosync config set api-key "$PYROSYNC_API_KEY", then pyrosync whoami.
• Availability: Build from packages/cli. Not on npm yet.
• Where: packages/cli

Infrastructure as code (GitOps)

A versioned pyrosync.yaml that declares sources, mappings, contracts, workflows and syncs.

• Best for: Reviewed, repeatable configuration across environments, with drift detection.
• Not for: Data reads and one-time jobs.
• First step: pyrosync plan pyrosync.yaml to see the plan, then pyrosync apply pyrosync.yaml.
• Availability: Through the CLI (plan, diff, apply, drift). The CI workflow is a template you copy in. A Terraform provider is not available yet.
• Where: docs/dev/gitops.md, docs/dev/gitops-apply.yml

MCP server

A Model Context Protocol server that gives AI assistants PyroSync tools.

• Best for: Claude Desktop, Claude Code, Cursor or VS Code working with your targets, jobs and data.
• Not for: Your own agent code: agent tools fit there without a separate process.
• First step: Build @pyrosync/mcp-server, then add it to your client config with PYROSYNC_API_KEY.
• Availability: Build from packages/mcp-server. Not on npm yet. Tool calls follow the key’s grants.
• Where: packages/mcp-server

Agent tools and framework integrations

Search, scrape, crawl, extract, query and retrieval as tool definitions.

• Best for: Agents you write with the Vercel AI SDK, OpenAI, Anthropic, LangChain.js or the OpenAI Agents SDK, or LangChain and LlamaIndex in Python.
• Not for: Desktop assistants: use the MCP server.
• First step: Pass the tools to your agent with include: [...], or allowMetered: false for read-only use.
• Availability: Use from this repository. Not on a registry yet.
• Where: packages/agent-tools, sdks/python/pyrosync/langchain.py, sdks/python/pyrosync/llama_index.py

Webhooks

Signed HTTP callbacks when jobs, crawls, syncs and other events happen.

• Best for: Reacting to events instead of polling.
• Not for: Reading data in bulk: call the API or query once the event arrives.
• First step: Register an endpoint, then verify each delivery with the SDK helper before trusting it.
• Availability: Live. Every SDK ships a signature verifier and a local tunnel helper.
• Where: docs/user/webhook-events.md, docs/user/webhook-verification.md

No-code automation (n8n, Zapier, Make)

Triggers on PyroSync events, plus scrape, crawl, extract, ingest, query and workflow actions.

• Best for: Teams that wire tools together without writing code.
• Not for: High-volume or latency-sensitive pipelines.
• First step: Install the n8n node from its directory, or follow the Zapier or Make README.
• Availability: The n8n node is ready to publish but is not in the community registry. Zapier and Make are drafts, not submitted for review.
• Where: packages/n8n-nodes-pyrosync, packages/zapier-pyrosync, packages/make-pyrosync

Embeds

A dataset grid or saved-query result inside your own app, scoped by a signed token per viewer.

• Best for: Showing PyroSync data to your customers without building a UI.
• Not for: Internal dashboards: use the PyroSync dashboard.
• First step: Mint a token on your backend, serve createEmbedHandler with a restricted query:read key, and render <pyrosync-embed>.
• Availability: Use from this repository. Not on npm yet.
• Where: packages/embed