Introducing projects (API v2.0)

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:

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

1. Update your base URL from /api/v1/ to /api/v2/
2. Replace path segments:
   • Change phacets to tables
   • Change phacetId to tableId
3. Update list operations - Use GET /api/v2/projects to list projects with their tables (replaces listing phacets)
4. 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

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