# Swell Customer API

Base URL: `https://api.growonswell.com/v1`

The customer API is the stable REST surface for agents and customer integrations. Internal browser-session routes stay under `/api/v1`; customer integrations should use `/v1` plus the OpenAPI contract at `/v1/openapi.json`.

For browser analytics installation, server-side capture helpers, custom events, identity, conversions, tracked links, session replay, bot tracking, and revenue attribution, start with [`tracking.md`](https://docs.growonswell.com/tracking.md).

## Start Here

1. Create or open your Swell workspace.
2. Install `swell.js` from **Connect > Web analytics** on your public site.
3. Add server-side capture for backend-only milestones that browser JavaScript cannot see.
4. Create tracked links in **Create > Links** or `POST /v1/links`.
5. Connect social accounts, paid ad accounts, and revenue providers from **Connect**.
6. Use the REST API or hosted MCP endpoint to preview and schedule content.
7. Verify traffic, conversions, revenue, and audit history before automating writes.

## Authentication

Send a workspace-scoped API key on every request:

```http
Authorization: Bearer swl_sk_...
```

API keys can be scoped to read/write groups including `workspace:read`, `profile:read`, `profile:write`, `accounts:read`, `media:read`, `media:write`, `posts:read`, `posts:write`, `links:read`, `links:write`, `analytics:read`, `audit:read`, `webhooks:read`, and `webhooks:write`.

## IDs

Responses include the existing numeric `id` for compatibility plus a typed `object_id` such as `post_42`, `media_301`, or `webhook_endpoint_7`. New agent integrations should store `object_id` in logs and tool state.

## Idempotency

For mutating `/v1` requests, send an `Idempotency-Key` header:

```http
Idempotency-Key: import-run-2026-06-28-001
```

Swell replays the original response when the same key is reused with the same method, path, and request body. Multipart media uploads are fingerprinted by file hash and metadata. Reusing a key with a different request, or retrying while the first request is still in progress, returns `409`. Completed idempotency records are retained for 72 hours by default.

## Dry Runs

Use `POST /posts/preview` before creating or scheduling content. It validates captions, accounts, media, schedule timing, and provider constraints without writing data.

## Company Profile

`GET /v1/company-profile` returns the generated workspace profile used to ground Swell agents and automated workflows. It includes source URLs, audience, positioning, value props, feature set, messaging, tone, visual identity, social posture, evidence, confidence, associated image/video references, and compact context text.

Use `PATCH /v1/company-profile/sources` with `profile:write` to replace source URLs and regenerate the profile. Use `POST /v1/company-profile/media` to associate an existing image or video media asset with a role such as `logo`, `product_image`, `brand_reference`, `screenshot`, or `demo_video`; use `DELETE /v1/company-profile/media/{media_id}` to remove that association. Use `POST /v1/company-profile/refresh` to regenerate from current sources, social accounts, posts, media, links, and analytics signals.

## Tracking And Analytics

The public browser tracker is installed with a workspace public key:

```html
<script async src="https://api.growonswell.com/swell.js?key=swl_pk_live_..."></script>
```

It exposes `Swell.page`, `Swell.track`, `Swell.identify`, `Swell.conversion`, `Swell.webVital`, `Swell.consent`, and journey helpers. Browser tracking and the documented server-side capture helpers post to public growth collection endpoints under `/api/v1/growth`; durable customer automation should still use the `/v1` REST API contract.

Use server-side capture for backend-only events such as activation, invite acceptance, lead processing, or non-revenue conversion milestones. Send the public `swl_pk_` tracking key to `/api/v1/growth/track`, include `client_event_id` for retry deduplication, and do not send trusted revenue or `value_cents` through the public capture endpoint.

Use `GET /v1/analytics/overview` with an API key scoped to `analytics:read` to read visitors, pageviews, conversions, revenue, sources, pages, performance, recent events, and the current install snippet.

Use `GET /v1/people` with the same `analytics:read` scope to read the lightweight CRM assembled from first-party tracking. Rows include known contacts and anonymous visitors, source and campaign fields, session and event counts, conversion counts, and `total_revenue_cents`. Add `q` to search contact email, name, company, source, or campaign, and `limit` up to 250.

Use `GET /v1/people/journey?email=jane@example.com`, `GET /v1/people/journey?contact_id=314`, or `GET /v1/people/journey?anonymous_id=visitor_abc` to retrieve one person's event journey. The response includes merged anonymous IDs, event history, session count, and attributed revenue totals.

Use `POST /v1/links` to create shortened campaign URLs. The short URL redirects to the destination with UTMs and `swell_link_id`; when `swell.js` is installed on the destination site, those query values become first-touch and last-touch attribution context.

For trusted revenue, connect a revenue provider or send signed provider webhooks. Browser conversions can mark product milestones, but they do not create trusted revenue rows. When a trusted revenue payload carries a workspace user ID, Swell stores that association and still rolls the revenue into the matching People contact journey when identity or email can be resolved.

## Webhooks And Audit

`GET /audit-log` returns immutable audit events for API-key changes, public API mutations, and webhook configuration. `POST /webhooks` registers an HTTPS endpoint and returns a signing secret once. Delivery records are available at `GET /webhooks/deliveries`.

## OpenAPI

The OpenAPI 3.1 document is generated from the real `/v1` FastAPI routes and filtered to exclude internal `/api/v1` routes:

```text
https://api.growonswell.com/v1/openapi.json
```