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