# API Reference

### Authentication Endpoints

| Method | Endpoint                       | Description               | Auth Required |
| ------ | ------------------------------ | ------------------------- | ------------- |
| POST   | `/auth/register`               | Register new user         | No            |
| POST   | `/auth/login`                  | Login with email/password | No            |
| POST   | `/auth/google-login`           | Login with Google         | No            |
| GET    | `/auth/verify-email`           | Verify email address      | No            |
| POST   | `/auth/reset-password/request` | Request password reset    | No            |
| POST   | `/auth/reset-password/confirm` | Confirm password reset    | No            |
| POST   | `/auth/refresh`                | Refresh access token      | Refresh Token |

### Tenant Endpoints

| Method | Endpoint   | Description         | Auth Required |
| ------ | ---------- | ------------------- | ------------- |
| POST   | `/tenants` | Create new tenant   | Yes           |
| GET    | `/tenants` | List user's tenants | Yes           |
| GET    | `/tenant`  | Get tenant details  | Yes           |
| PUT    | `/tenant`  | Update tenant       | Yes (Admin)   |
| DELETE | `/tenant`  | Delete tenant       | Yes (Admin)   |

### Member Endpoints

| Method | Endpoint        | Description         | Auth Required |
| ------ | --------------- | ------------------- | ------------- |
| GET    | `/members`      | List tenant members | Yes           |
| PATCH  | `/members/role` | Change member role  | Yes (Admin)   |
| DELETE | `/members`      | Remove member       | Yes (Admin)   |

### Invitation Endpoints

| Method | Endpoint                            | Description                 | Auth Required |
| ------ | ----------------------------------- | --------------------------- | ------------- |
| POST   | `/invite`                           | Invite user to tenant       | Yes (Admin)   |
| GET    | `/invitations/{token}/accept`       | Accept invitation           | No            |
| POST   | `/invitations/{token}/set-password` | Set password for invitation | No            |

### Payment Endpoints

| Method | Endpoint                                     | Description                                                 | Auth Required |
| ------ | -------------------------------------------- | ----------------------------------------------------------- | ------------- |
| GET    | `/payments/plans`                            | Get available plans (with monthly & annual prices)          | Yes           |
| GET    | `/payments/subscription`                     | Get tenant subscription                                     | Yes           |
| POST   | `/payments/checkout`                         | Create Stripe Checkout session (includes billing\_interval) | Yes (Admin)   |
| POST   | `/payments/subscription`                     | Create subscription                                         | Yes (Admin)   |
| PATCH  | `/payments/subscription`                     | Update subscription                                         | Yes (Admin)   |
| DELETE | `/payments/subscription`                     | Cancel subscription                                         | Yes (Admin)   |
| POST   | `/payments/subscription/uncancel`            | Uncancel subscription                                       | Yes (Admin)   |
| GET    | `/payments/payment-methods`                  | List payment methods                                        | Yes           |
| POST   | `/payments/payment-methods`                  | Add payment method                                          | Yes (Admin)   |
| DELETE | `/payments/payment-methods/{id}`             | Delete payment method                                       | Yes (Admin)   |
| PATCH  | `/payments/payment-methods/{id}/set-default` | Set default payment method                                  | Yes (Admin)   |
| POST   | `/payments/setup-intent`                     | Create setup intent                                         | Yes (Admin)   |
| GET    | `/payments/invoices`                         | List invoices                                               | Yes           |
| GET    | `/payments/invoices/{id}/download`           | Download invoice PDF                                        | Yes           |

### Item Endpoints

| Method | Endpoint        | Description | Auth Required |
| ------ | --------------- | ----------- | ------------- |
| POST   | `/items`        | Create item | Yes           |
| GET    | `/items`        | List items  | Yes           |
| GET    | `/items/{uuid}` | Get item    | Yes           |
| PATCH  | `/items/{uuid}` | Update item | Yes           |
| DELETE | `/items/{uuid}` | Delete item | Yes           |

### Super Admin Endpoints

| Method | Endpoint                      | Description        | Auth Required     |
| ------ | ----------------------------- | ------------------ | ----------------- |
| GET    | `/super-admin/tenants`        | List all tenants   | Yes (Super Admin) |
| GET    | `/super-admin/tenants/{uuid}` | Get tenant details | Yes (Super Admin) |

### Webhook Endpoints

| Method | Endpoint                    | Description            | Auth Required    |
| ------ | --------------------------- | ---------------------- | ---------------- |
| POST   | `/payments/webhooks/stripe` | Stripe webhook handler | Stripe Signature |

### Utility Endpoints

| Method | Endpoint        | Description                 | Auth Required |
| ------ | --------------- | --------------------------- | ------------- |
| GET    | `/health`       | Health check                | No            |
| GET    | `/docs`         | API documentation (Swagger) | No            |
| GET    | `/sentry-debug` | Test Sentry integration     | No            |

## Common Workflows

### Adding a New User to a Tenant

{% stepper %}
{% step %}
Admin invites user: `POST /invite`
{% endstep %}

{% step %}
User receives email with invitation link
{% endstep %}

{% step %}
User clicks link: `GET /invitations/{token}/accept`
{% endstep %}

{% step %}
If new user: Set password via `POST /invitations/{token}/set-password`
{% endstep %}

{% step %}
User is added to tenant with specified role
{% endstep %}
{% endstepper %}

### Setting Up Billing

{% stepper %}
{% step %}
Create tenant: `POST /tenants`
{% endstep %}

{% step %}
Add payment method:

* Get setup intent: `POST /payments/setup-intent`
* Collect card with Stripe.js on frontend
* Attach payment method: `POST /payments/payment-methods`
  {% endstep %}

{% step %}
Create subscription: `POST /payments/subscription`
{% endstep %}

{% step %}
Subscription status updated via webhooks
{% endstep %}
{% endstepper %}

### Changing Subscription Plans

{% stepper %}
{% step %}
Get available plans: `GET /payments/plans`
{% endstep %}

{% step %}
Update subscription: \`PATCH /payments/subscription\` {%{% step %}

Stripe prorates the charges automatically
{% endstep %}

{% step %}
Webhook updates subscription status
{% endstep %}
{% endstepper %}

## Additional Resources

* **FastAPI Documentation:** <https://fastapi.tiangolo.com>
* **SQlAlchemy Documentation:** <https://www.sqlalchemy.org/>
* **Stripe API Reference:** <https://stripe.com/docs/api>
* **React Documentation:** <https://react.dev>
* **Tailwind CSS:** <https://tailwindcss.com>

## Support

For questions or issues, contact: <admin@fast-saas.com>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fast-saas.com/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.