> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auction-rise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Endpoints

> Auction Rise REST API endpoint reference.

Auction Rise exposes a small number of REST endpoints. Most data mutations (creating workspaces, managing members, updating settings, etc.) are handled through **Next.js Server Actions** rather than REST endpoints, keeping data access secure and type-safe on the server.

<Note>
  For querying and mutating workspace data, use the [Supabase client libraries](https://supabase.com/docs/reference) with the `apikey` and `Authorization` headers described in the [Authentication](/docs/api/authentication) guide.
</Note>

***

## Billing

### Stripe webhook

```bash theme={null}
POST /api/billing/webhook
```

Receives and processes Stripe webhook events. This endpoint is called by Stripe — configure the URL in your Stripe dashboard under **Developers → Webhooks**.

Requests are verified using the `STRIPE_WEBHOOK_SECRET` environment variable. Do not call this endpoint directly from your application.

**Handled event types** (extend in `app/api/billing/webhook/route.ts`):

| Event                           | Description                               |
| ------------------------------- | ----------------------------------------- |
| `checkout.session.completed`    | User completed checkout; provision access |
| `customer.subscription.updated` | Subscription plan or status changed       |
| `customer.subscription.deleted` | Subscription cancelled                    |
| `invoice.payment_succeeded`     | Recurring payment collected               |
| `invoice.payment_failed`        | Payment failed; notify or restrict access |

**Responses:**

| Status | Description                                 |
| ------ | ------------------------------------------- |
| `200`  | Webhook received and processed successfully |
| `400`  | Invalid payload or missing Stripe signature |
| `401`  | Webhook signature verification failed       |

**Authentication:** Stripe-signed webhook (verified via `STRIPE_WEBHOOK_SECRET`)

***

## Notifications

### Trigger digest emails

```bash theme={null}
POST /api/notifications/digest?frequency=daily
```

Sends activity digest emails to eligible users. This endpoint is protected by `CRON_SECRET` and is intended to be called by Vercel Cron, not by end users.

**Query parameters:**

| Parameter   | Type     | Required | Values              |
| ----------- | -------- | -------- | ------------------- |
| `frequency` | `string` | Yes      | `daily` or `weekly` |

**Responses:**

| Status | Description                                                |
| ------ | ---------------------------------------------------------- |
| `200`  | Digests processed. Returns `{ ok: true, frequency, sent }` |
| `400`  | Invalid or missing frequency parameter                     |
| `401`  | Missing or invalid `CRON_SECRET`                           |

**Authentication:** `Authorization: Bearer <CRON_SECRET>`

**Cron schedule** (configured in `vercel.json`):

```json theme={null}
{
  "crons": [
    { "path": "/api/notifications/digest?frequency=daily", "schedule": "0 8 * * *" },
    { "path": "/api/notifications/digest?frequency=weekly", "schedule": "0 8 * * 1" }
  ]
}
```

***

## Server Actions

Most mutations in Auction Rise use Next.js Server Actions rather than REST endpoints. Server Actions run on the server, have access to the authenticated session, and automatically enforce RLS policies.

Examples of operations handled via Server Actions:

* Creating and updating workspaces
* Managing workspace members and roles
* Sending invitations
* Updating user profile and notification preferences
* Workspace-scoped data mutations

See the [Supabase Data API](https://supabase.com/docs/guides/api) documentation for direct database access patterns.