name: endpoints
description: "Endpoints document management API toolkit. Scan documents with AI extraction and organize structured data into categorized endpoints. Use when the user asks to: scan a document, upload a file, list endpoints, inspect endpoint data, check usage stats, create or delete endpoints, get file URLs, or manage document metadata. Requires ENDPOINTSAPIKEY from endpoints.work dashboard."

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