Endpoints

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

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

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

Scanning Functions

Item Functions

File Functions

Billing Functions

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

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`);