Endpoints API Toolkit
Setup
Install dependencies:
cd scripts && npm install
Configure credentials by creating a .env file in the project root:
ENDPOINTS_API_URL=https://endpoints.work
ENDPOINTS_API_KEY=ep_your_api_key_here
Prerequisites: An Endpoints account with an API key. Generate your API key from the API Keys page.
Quick Start
| User says | Function to call |
|---|---|
| "List my endpoints" | listEndpoints() |
| "Show endpoint details for /job-tracker/january" | getEndpoint('/job-tracker/january') |
| "Scan this document" | scanFile('/path/to/file.pdf', 'job tracker') |
| "Scan this text" | scanText('Meeting notes...', 'meeting tracker') |
| "Create an endpoint for receipts" | createEndpoint('/receipts/2026') |
| "Delete the old endpoint" | deleteEndpoint('/category/slug') |
| "Remove that item" | deleteItem('abc12345') |
| "Get the file URL" | getFileUrl('userid/path/file.pdf') |
| "Check my usage" | getStats() |
Execute functions by importing from scripts/src/index.ts:
import { listEndpoints, scanText, getStats } from './scripts/src/index.js';
const categories = await listEndpoints();
const result = await scanText('Meeting with John about Q1 goals', 'meeting tracker');
const stats = await getStats();
Or run directly with tsx:
npx tsx scripts/src/index.ts
Workflow Pattern
Every analysis follows three phases:
1. Analyze
Run API functions. Each call hits the Endpoints API and returns structured data.
2. Auto-Save
All results automatically save as JSON files to results/{category}/. File naming patterns:
- Named results:
{sanitized_name}.json - Auto-generated:
YYYYMMDD_HHMMSS__{operation}.json
3. Summarize
After analysis, read the saved JSON files and create a markdown summary in results/summaries/ with data tables, insights, and extracted entities.
High-Level Functions
| Function | Purpose | What it returns |
|---|---|---|
listEndpoints() | Get all endpoints by category | Tree structure with categories and endpoints |
getEndpoint(path) | Get endpoint details | Full metadata (old + new items) |
scanText(text, prompt) | Scan text with AI | Extracted entities and endpoint path |
scanFile(filePath, prompt) | Scan file with AI | Extracted entities and endpoint path |
getStats() | Get usage statistics | Parses used, limits, storage |
Individual API Functions
For granular control, import specific functions. See references/api-reference.md for the complete list with parameters, types, and examples.
Endpoint Functions
| Function | Purpose |
|---|---|
listEndpoints() | List all endpoints organized by category |
getEndpoint(path) | Get full endpoint details with metadata |
createEndpoint(path) | Create a new empty endpoint |
deleteEndpoint(path) | Delete endpoint and all associated files |
Scanning Functions
| Function | Purpose |
|---|---|
scanText(text, prompt) | Scan text content with AI extraction |
scanFile(filePath, prompt) | Scan file (PDF, images, docs) with AI |
Item Functions
| Function | Purpose |
|---|---|
deleteItem(itemId) | Delete a single item by its 8-char ID |
File Functions
| Function | Purpose |
|---|---|
getFileUrl(key) | Get presigned S3 URL for a file |
Billing Functions
| Function | Purpose |
|---|---|
getStats() | Get usage stats (parses, storage, tier) |
Data Structures
Living JSON Pattern
Endpoints use the Living JSON pattern for document history:
{
endpoint: { path, category, slug },
metadata: {
oldMetadata: { ... }, // Historical items
newMetadata: { ... } // Recent items
}
}
Metadata Item
Each item has:
- 8-character ID - Unique identifier (e.g.,
abc12345) - summary - AI-generated description
- entities - Extracted entities (people, companies, dates)
- filePath - S3 URL if file was uploaded
- fileType - MIME type
- originalText - Source text
Error Handling
| Status | Meaning |
|---|---|
| 401 | Invalid or missing API key |
| 404 | Endpoint or item not found |
| 409 | Endpoint already exists |
| 429 | Usage limit exceeded |
Examples
List and Inspect
// Get all endpoints
const { categories } = await listEndpoints();
console.log(`Found ${categories.length} categories`);
// Inspect specific endpoint
const details = await getEndpoint('/job-tracker/january');
console.log(`Total items: ${details.totalItems}`);
Scan Documents
// Scan text content
const result = await scanText(
'Email from John Smith at Acme Corp about the Q1 contract renewal',
'business contacts'
);
console.log(`Created endpoint: ${result.endpoint.path}`);
// Scan a PDF file
const fileResult = await scanFile('./invoice.pdf', 'invoice tracker');
console.log(`Extracted ${fileResult.entriesAdded} items`);
Check Usage
const stats = await getStats();
console.log(`Parses: ${stats.parsesUsed}/${stats.parsesLimit}`);
console.log(`Storage: ${stats.storageUsed} bytes`);