We're excited to announce the release of Public API v2! This major update introduces project-level operations and updates terminology to better reflect our product architecture.

🎉 What's New

Project Management

Access and manage projects directly through the API:

GET /api/v2/projects - List all projects in your organization
GET /api/v2/projects/:projectId - Get a specific project with all its tables

Each project response includes:

Project metadata (id, name, createdAt, updatedAt)
All tables within the project
Complete table details (columns, sessions, metadata)

Terminology Updates

We've updated our API terminology to better align with the product:

v1 Term	v2 Term
Phacet	Table
`phacetId`	`tableId`

This change makes the API more intuitive and consistent with the product interface.

Architecture Changes

List endpoint removed: GET /api/v1/phacets has been removed in v2. Use GET /api/v2/projects to list all projects with their tables.

🔄 Migration Guide

Base URL

Both API versions are available:

v1: https://api.phacetlabs.com/api/v1/ (maintenance mode)
v2: https://api.phacetlabs.com/api/v2/ (recommended)

Route Changes

All v1 routes continue to work unchanged. Here's how routes map to v2:

Tables (formerly Phacets)

- GET /api/v1/phacets
+ REMOVED (use GET /api/v2/projects to list projects with their tables)

- GET /api/v1/phacets/:phacetId
+ GET /api/v2/tables/:tableId

- GET /api/v1/phacets/:phacetId/rows
+ GET /api/v2/tables/:tableId/rows

- POST /api/v1/phacets/:phacetId/rows
+ POST /api/v2/tables/:tableId/rows

- GET /api/v1/phacets/:phacetId/rows/:rowId
+ GET /api/v2/tables/:tableId/rows/:rowId

- PUT /api/v1/phacets/:phacetId/rows/:rowId
+ PUT /api/v2/tables/:tableId/rows/:rowId

- GET /api/v1/phacets/:phacetId/cells/:cellId
+ GET /api/v2/tables/:tableId/cells/:cellId

- GET /api/v1/phacets/:phacetId/cells/:cellId/file-download-url
+ GET /api/v2/tables/:tableId/cells/:cellId/download-file-url

- POST /api/v1/phacets/:phacetId/sessions
+ POST /api/v2/tables/:tableId/sessions

Files & Webhooks (No changes)

POST /api/v1/files → POST /api/v2/files
POST /api/v1/webhooks/endpoints → POST /api/v2/webhooks/endpoints

Migration Steps

Update your base URL from /api/v1/ to /api/v2/
Replace path segments:
- Change phacets to tables
- Change phacetId to tableId
Update list operations - Use GET /api/v2/projects to list projects with their tables (replaces listing phacets)
Test your integration - Response schemas remain compatible

Example Migration

Before (v1):

// List all phacets
const response = await fetch('https://api.phacetlabs.com/api/v1/phacets', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

// Get rows from a phacet
const rows = await fetch(
  `https://api.phacetlabs.com/api/v1/phacets/${phacetId}/rows`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

// Update a row
await fetch(`https://api.phacetlabs.com/api/v1/phacets/${phacetId}/rows/${rowId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ columnId: 'value' })
});

After (v2):

// List all projects (replaces listing phacets/tables)
const projects = await fetch('https://api.phacetlabs.com/api/v2/projects', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
// Each project includes its tables: projects[0].tables

// Get a specific table
const table = await fetch(`https://api.phacetlabs.com/api/v2/tables/${tableId}`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

// Get rows from a table
const rows = await fetch(
  `https://api.phacetlabs.com/api/v2/tables/${tableId}/rows`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);

// Update a row
await fetch(`https://api.phacetlabs.com/api/v2/tables/${tableId}/rows/${rowId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ columnId: 'value' })
});

📋 New Endpoints

Projects (New in v2)

GET  /api/v2/projects              List all projects in your organization
GET  /api/v2/projects/:projectId   Get a specific project with all its tables

All Other Endpoints

All table, row, cell, session, file, and webhook endpoints from v1 are available in v2 with updated paths (tables instead of phacets).

🔐 Authentication

Authentication remains unchanged across all API versions. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

⚠️ Deprecation Notice

API v1 is now in maintenance mode:

v1 endpoints will continue to work without changes
No new features will be added to v1
v1 will receive security updates only
We recommend migrating to v2 for access to new features
v1 deprecation timeline will be announced at least 3 months in advance

💡 Benefits of Migrating to v2

Project-level operations - Work with projects as first-class entities
Clearer terminology - "Tables" better reflects the product structure
Future-ready - All new features will be added to v2 first
Improved consistency - Cleaner, more intuitive API design
Better organization - Group related tables by project

Changelog

Introducing projects (API v2.0)