Endpoints

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 ENDPOINTS_API_KEY from endpoints.work dashboard.

Security Scan

The skill largely implements a coherent document-scanning client for endpoints.work, but its declared metadata omits the required ENDPOINTS_API_KEY and there are small mismatches between the README/workflow and the shipped code that you should review before installing or running it with real data or credentials.

Purpose & Capability

The skill's code and SKILL.md match the described purpose (upload/scan documents, list/create/delete endpoints, fetch presigned file URLs, get billing stats). However the registry metadata claims no required environment variables or primary credential, while both SKILL.md and scripts/src/index.ts require ENDPOINTS_API_KEY (with ENDPOINTS_API_URL optional). This metadata mismatch is an incoherence that could mislead users about what secrets are needed.

Instruction Scope

Instructions tell the agent/user to create a .env with ENDPOINTS_API_KEY and to run npm install; the runtime code will read arbitrary local files (scanFile uses readFileSync on any supplied path) and will save output JSON into results/{category}/ and billing data into results/billing/. This file I/O and automatic saving is consistent with scanning functionality, but SKILL.md also describes a 'Summarize' phase that reads saved JSON and writes markdown summaries — that summarization is not implemented in the provided code, a discrepancy. Also scanning uploads content to the endpoints.work service and uses returned presigned S3 URLs: users should be aware that uploaded content is sent to an external service.

Install Mechanism

No formal install spec is provided in the registry; SKILL.md instructs running npm install in scripts/, and package.json lists only dotenv as a runtime dependency (dev deps include tsx/typescript). There is no download-from-arbitrary-URL behavior. Installing will fetch packages from the public npm registry (normal but requires trusting dependencies), and the code will be executed locally.

Credentials

The code legitimately requires a single service credential (ENDPOINTS_API_KEY) and optionally ENDPOINTS_API_URL; that is proportionate to a client for endpoints.work. The problem is the skill manifest/registry metadata declares no required env or primary credential, which is misleading. No other unrelated credentials are requested. The skill reads the .env file from the project root and will exit if ENDPOINTS_API_KEY is not set.

Persistence & Privilege

always is false and the skill does not request persistent platform-wide privileges. It writes files only under the repository/project results/ directory and does not alter other skills or system configuration. Autonomous invocation is allowed (default) but that alone is not flagged.

What to consider before installing

What to consider before installing or running this skill: - The runtime code requires an ENDPOINTS_API_KEY (and optionally ENDPOINTS_API_URL), but the registry metadata did not declare that — treat the metadata as inaccurate until corrected. - The skill will upload text and file contents you pass to https://endpoints.work (via /api/scan) and may result in presigned S3 URLs being returned; do not upload sensitive or regulated data unless you fully trust the service and its policies. - The skill reads arbitrary local file paths you provide (scanFile uses readFileSync). Only give paths for files you intend to send; consider running in a sandboxed environment if you are unsure. - The package uses public npm packages; run npm install in an isolated/dev environment first, and inspect node_modules if you want to audit dependencies before executing. - There's a mismatch between the SKILL.md workflow (mentions automatic summarization) and the provided code (which saves results but does not produce summaries); expect some missing functionality or stale documentation. Recommended actions: - Ask the skill publisher or registry maintainer to update the skill manifest to declare ENDPOINTS_API_KEY as a required environment credential and to provide a homepage/source for vetting. - If you will use it, test with non-sensitive sample data and in an isolated environment (container/VM) first. - Review the code and verify the network endpoints and returned URLs (ensure endpoints.work is the expected service) and check the service's privacy/storage policy before uploading real documents. - Do not insert production secrets until you're confident about the code and service.

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