API: integrate Phacet into your systems

The Phacet API lets you programmatically interact with your Tables: create rows, upload files, retrieve results, and trigger AI processing. Use it to integrate Phacet into your existing systems, build custom workflows, or connect tools that aren't supported by Zapier or n8n.

Why use the API?

• Automate data ingestion: push data from internal systems, databases, or scripts directly into Phacet Tables.
• Retrieve processed results: pull AI-extracted data back into your systems for downstream use.
• Upload documents at scale: send PDF files to Phacet programmatically for batch processing.
• Build custom integrations: connect Phacet to any system that can make HTTP requests.
• React to events in real time: use webhooks to get notified when rows are created or calculations complete.

API overview

Authentication

All API requests require a Bearer token passed in the Authorization header.

Step 1: Generate an API key

1. Go to Settings > API Keys in your Phacet workspace.
2. Click Create API Key.
3. Copy the key — it will only be shown once.

⚙️

Only Admin users can create and manage API keys.

Step 2: Use the key in your requests

Include the API key in the Authorization header of every request:

curl -X GET "https://api.phacetlabs.com/api/v2/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Key endpoints

Projects

Tables

Sessions

Rows

Cells

Files

Webhooks

Common workflows

Create a row and trigger AI processing

curl -X POST "https://api.phacetlabs.com/api/v2/tables/{tableId}/rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_ID",
    "cells": [
      {
        "columnId": "COLUMN_ID",
        "value": "Acme Corporation - Annual Report 2024"
      }
    ],
    "triggerTasks": true
  }'

Setting triggerTasks to true automatically launches all configured AI and Python tools on the new row.

Retrieve rows with pagination

The API uses cursor-based pagination. Each response includes a nextCursor value when more results are available.

# First page (up to 200 rows)
curl -X GET "https://api.phacetlabs.com/api/v2/tables/{tableId}/rows?take=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Next page
curl -X GET "https://api.phacetlabs.com/api/v2/tables/{tableId}/rows?take=50&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response format:

{
  "rows": [ ... ],
  "hasMore": true,
  "nextCursor": "encoded-row-id"
}

Upload a PDF file and attach it to a row

Step 1: Upload the file

curl -X POST "https://api.phacetlabs.com/api/v2/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf"

Step 2: Create a row referencing the uploaded file

curl -X POST "https://api.phacetlabs.com/api/v2/tables/{tableId}/rows" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cells": [
      {
        "columnId": "FILE_COLUMN_ID",
        "value": { "id": "UPLOADED_FILE_ID", "name": "document.pdf" }
      }
    ],
    "triggerTasks": true
  }'

Set up a webhook

Subscribe to events to get notified when something happens in your Tables:

curl -X POST "https://api.phacetlabs.com/api/v2/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks",
    "eventTypes": ["row.created", "row.updated"]
  }'

Available webhook events:

Cell value formats

When creating or updating rows, the value field depends on the column data type:

Cell statuses

When retrieving rows, each cell includes a status field indicating its processing state:

Error handling

The API returns standard HTTP status codes:

Error responses include a message and error key:

{
  "message": "Table not found",
  "errorKey": "NotFoundError"
}

Best practices

• Store your API key securely: use environment variables or a secret manager — never hardcode keys in your source code.
• Use triggerTasks: true wisely: only enable it when you want AI tools to process the row immediately. Disable it if you're bulk-importing data and plan to trigger processing later.
• Handle pagination: always check the hasMore field and follow nextCursor to retrieve complete datasets.
• Monitor cell statuses: after creating a row with triggerTasks: true, poll the row endpoint to check when all cells reach resolved status.
• Use webhooks for real-time flows: instead of polling, subscribe to row.updated events to get notified when processing completes.

📖

For the complete API reference with detailed request/response schemas, visit the API Reference section.