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

# API Overview

> Complete reference for the 8Space Unified API

The 8Space API provides a unified interface across the landing page, app, and Supabase backend. All endpoints are documented from the production monorepo.

## Base URLs

8Space uses different base URLs depending on the service:

<ParamField path="Production" type="string" default="https://8space.app">
  Landing page and API gateway endpoints
</ParamField>

<ParamField path="Local Landing" type="string" default="http://localhost:3000">
  Local Next.js development server
</ParamField>

<ParamField path="Local Supabase" type="string" default="http://127.0.0.1:54321">
  Local Supabase instance from `packages/app/supabase/config.toml`
</ParamField>

## API Groups

The 8Space API is organized into six functional groups:

### Landing

Next.js API routes for lead collection and authentication callbacks.

**Endpoints:**

* `POST /api/lead` - Store lead email from landing page (triggered by `ButtonLead` component)
* `GET /auth/callback` - Exchange OAuth code and redirect user

### Billing

Stripe checkout and customer portal routes.

**Endpoints:**

* `POST /api/stripe/create-checkout` - Create Stripe Checkout session (triggered by `ButtonCheckout` component)
* `POST /api/stripe/create-portal` - Create Stripe billing portal session (triggered by `ButtonAccount` component, requires auth)

### Webhooks

Stripe webhook receiver for billing lifecycle events.

**Endpoints:**

* `POST /api/webhook/stripe` - Receive and verify Stripe webhook events

### Supabase Auth

Authentication endpoints used by landing and app clients.

**Endpoints:**

* `POST /auth/v1/signup` - Sign up with email/password
* `POST /auth/v1/token?grant_type=password` - Sign in with password grant
* `GET /auth/v1/authorize?provider=google` - Start Google OAuth flow
* `GET /auth/v1/user` - Get authenticated user (requires auth)
* `POST /auth/v1/logout` - Log out user session (requires auth)

### Supabase Data

PostgREST table endpoints used by the 8Space app. Response shape depends on the `select` query parameter.

**Endpoints:**

* `GET /rest/v1/profiles` - Query user profiles
* `GET /rest/v1/project_members` - Query project membership and member lists
* `GET /rest/v1/workflow_columns` - List project workflow columns
* `PATCH /rest/v1/projects` - Update project settings
* `GET /rest/v1/tasks` - List tasks by project
* `POST /rest/v1/tasks` - Create task
* `PATCH /rest/v1/tasks` - Update task by id
* `DELETE /rest/v1/tasks` - Delete task by id
* `GET /rest/v1/task_assignees` - Query task assignees
* `POST /rest/v1/task_assignees` - Assign users to tasks
* `DELETE /rest/v1/task_assignees` - Remove task assignees
* `GET /rest/v1/task_label_links` - Query task labels linked to tasks
* `GET /rest/v1/task_checklist_items` - Query task checklist items
* `GET /rest/v1/task_attachments` - Query task attachments
* `GET /rest/v1/task_dependencies` - List task dependencies by project
* `POST /rest/v1/task_dependencies` - Create task dependencies
* `DELETE /rest/v1/task_dependencies` - Delete dependencies by project/successor filter

### Supabase RPC

PostgreSQL RPC functions used by the 8Space app.

**Endpoints:**

* `POST /rest/v1/rpc/create_project_with_defaults` - Create new project with default columns
* `POST /rest/v1/rpc/current_project_role` - Get caller's role in a project
* `POST /rest/v1/rpc/move_task` - Move task between columns and set rank
* `POST /rest/v1/rpc/dashboard_metrics` - Calculate dashboard metrics

## PostgREST Query Parameters

Supabase Data endpoints support PostgREST query parameters:

<ParamField query="select" type="string">
  Controls response shape. Example: `id,display_name,avatar_url` or `*,project(*)` for joins
</ParamField>

<ParamField query="{field}" type="string">
  Filter operators. Examples:

  * `id=eq.9b7f...` (equals)
  * `user_id=eq.<uuid>` (equals UUID)
  * `task_id=in.(uuid1,uuid2)` (in array)
</ParamField>

<ParamField query="order" type="string">
  Sort results. Example: `position.asc` or `order_rank.asc`
</ParamField>

<Note>
  PostgREST responses depend on the `select` query string. Schemas document the fields actually used by 8Space, not every field Supabase provides.
</Note>

## Common Response Types

### Error Responses

**Landing API Error:**

```json theme={null}
{
  "error": "Validation error message"
}
```

**Supabase Error:**

```json theme={null}
{
  "message": "Error message",
  "details": "Detailed error information",
  "hint": "Suggestion for fixing the error",
  "code": "ERROR_CODE"
}
```

### Status Codes

<ResponseField name="200" type="Success">
  Request successful
</ResponseField>

<ResponseField name="201" type="Created">
  Resource created successfully
</ResponseField>

<ResponseField name="204" type="No Content">
  Request successful, no response body
</ResponseField>

<ResponseField name="302" type="Redirect">
  Redirect response with `Location` header
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Validation error or invalid request
</ResponseField>

<ResponseField name="401" type="Unauthorized">
  Authentication required or invalid credentials
</ResponseField>

<ResponseField name="403" type="Forbidden">
  Forbidden by Row Level Security policies
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error occurred
</ResponseField>

## Data Types

### Enums

**ProjectRole:**

* `owner` - Full project access
* `editor` - Can edit project data
* `viewer` - Read-only access

**TaskPriority:**

* `p0` - Critical priority
* `p1` - High priority
* `p2` - Normal priority

**WorkflowColumnKind:**

* `backlog` - Backlog column
* `todo` - To-do column
* `in_progress` - In progress column
* `done` - Done column
* `custom` - Custom workflow column

**DependencyType:**

* `FS` - Finish-to-start dependency

<Note>
  This specification focuses on endpoints actually called in the 8Space codebase, not every endpoint Supabase provides.
</Note>

## Rate Limits

Supabase enforces rate limits on API requests. Consult your Supabase project settings for current limits.

<Warning>
  The Stripe customer portal endpoint (`/api/stripe/create-portal`) requires an authenticated Supabase user session.
</Warning>

## Next Steps

<Card title="Authentication" icon="lock" href="/api/authentication">
  Learn how authentication works with Supabase Auth
</Card>