Archives API Client

A minimal TypeScript/JavaScript client for querying the JFK files on Archives API. This package lets you:

• Query the JFK files using:
  • Full-text search (text)
  • Semantic vector search (vector)
  • Metadata-only filtering (metadata)
• Retrieve page text or presigned page PNG URLs for specific page IDs

This project was developed with love by Wes Convery <3.

---

Installation

npm install archives-api-client
# or
yarn add archives-api-client

---

Quick Start

import { ArchivesApiClient } from "archives-api-client";

// Initialize the client with your provided API key from archives-api.com
const { jfk } = new ArchivesApiClient({
  apiKey: "your-api-key",
});

---

Searching Documents

The client supports three main search methods:

1. Text Search

Search for documents by matching your query string within the full text:

const results = await jfk.search.text({
  query: "Lee Harvey Oswald",
});

2. Vector (Semantic) Search

Search using vector embeddings for semantic similarity. Note: Filtering by comments is not allowed in this method.

const results = await jfk.search.vector({
  query: "multiple shooters",
  metadata: {
    document_type: { operator: "eq", value: "MEMORANDUM" },
  },
  limit: 20,
});

3. Metadata-Only Search

Search using metadata filters only, without matching any text or vectors:

const results = await jfk.search.metadata({
  metadata: {
    nara_release_date: { operator: "between", value: [new Date("1963-01-01"), new Date("1970-01-01")] },
    file_number: { operator: "eq", value: "124-10001-10110" },
  },
});

Each search returns an object with the following structure:

{
  hits: Array<JFKDocumentResult>;
  limit: number;
  total: number; // not available for vector searches
}

Here, hits is an array of matching documents along with their metadata.

---

Retrieving Pages

Get Page Text

Retrieve the full text for one or more pages using their IDs:

const pageTextMap = await jfk.pages.getText({
  page_ids: ["page-id-1", "page-id-2"],
});

The response maps page IDs to their text:

{
  "page-id-1": { "text": "Full page text..." },
  "page-id-2": { "text": "Full page text..." }
}

Get Page PNG

Retrieve presigned URLs for PNG images of pages:

const pagePngMap = await jfk.pages.getPng({
  page_ids: ["page-id-1", "page-id-3"],
});

The response maps page IDs to URLs:

{
  "page-id-1": { "url": "https://..." },
  "page-id-3": { "url": "https://..." }
}

---

Metadata Filters & Keys

When constructing metadata filters, you can use one or more of these filter types:

• TextFilter

  { operator: "contains", value: "search string" }
  { operator: "isNull" }

• KeywordFilter

  { operator: "eq", value: "specific keyword" }
  { operator: "isNull" }

• DateFilter

  { operator: "gte" | "lte" | "gt" | "lt" | "eq", value: new Date() }
  { operator: "between", value: [new Date(), new Date()] }
  { operator: "isNull" }

• NumberFilter

  { operator: "eq" | "gt" | "lt" | "gte" | "lte", value: 123 }
  { operator: "between", value: [100, 200] }

For example, a composite filter may look like this:

{
  document_type: { operator: "eq", value: "REPORT" },
  document_date: { operator: "between", value: [new Date("1963-01-01"), new Date("1963-12-31")] },
  pages_released: { operator: "gt", value: 10 },
}

These filters are defined in the package's type definitions and ensure that search queries are structured correctly.

---

cURL Usage

You can interact with the API using cURL. Below are detailed examples to make the usage clear:

Example 1: Text Search

Send a POST request to perform a text search:

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "search",
    "payload": {
      "query": "Lee Harvey Oswald",
      "searchType": "text"
    }
  }'

Explanation:

• POST: The request method.
• Headers: Set the content type and include your API key (x-api-key).
• Payload: JSON object specifying the search action and payload.
  • query: The text to search.
  • searchType: Specifies that it is a text search.

Example 2: Vector Search with Metadata Filter

Perform a vector search (note: do not include a filter on comments):

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "search",
    "payload": {
      "query": "multiple shooters",
      "searchType": "vector",
      "metadata": {
        "document_type": { "operator": "eq", "value": "MEMORANDUM" }
      },
      "limit": 20
    }
  }'

Key Points:

• The metadata object includes filter keys (e.g., document_type).
• The limit parameter controls the number of results returned.

Example 3: Metadata-Only Search

Perform a metadata search by supplying filters:

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "search",
    "payload": {
      "searchType": "metadata",
      "metadata": {
        "nara_release_date": { "operator": "between", "value": ["1963-01-01", "1970-01-01"] },
        "file_number": { "operator": "eq", "value": "124-10001-10110" }
      }
    }
  }'

Details:

• The value for a between date filter is an array of date strings.
• This request does not include a text query since it is a metadata-only search.

Example 4: Retrieve Page Text

Request page text for specific pages:

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "pageText",
    "payload": {
      "page_ids": ["page-id-1", "page-id-2"]
    }
  }'

Example 5: Retrieve Page PNG

Request presigned PNG URLs for specific pages:

curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "action": "pagePng",
    "payload": {
      "page_ids": ["page-id-1", "page-id-3"]
    }
  }'

These examples illustrate how to use cURL to interact with the API endpoints directly. Adjust the endpoint URL, payload, and headers as required for your environment.

---

Types & Interfaces

Key Interfaces

• Search Input Types:

  • TextSearchInput
  • VectorSearchInput
  • MetadataSearchInput

• Page Input:

  • PageInput for retrieving page text or PNG images.

• Document Result:

  • JFKDocumentResult
    This interface represents the structure of documents returned from the JFK file group search. For example:

    export interface JFKDocumentResult extends BaseDocumentResult {
      metadata: {
        comments?: string;
        document_date?: Date;
        document_type?: string;
        file_name?: string;
        file_number?: string;
        formerly_withheld?: string;
        from_name?: string;
        nara_release_date?: Date;
        originator?: string;
        pages_released?: number;
        page_count?: number;
        record_number?: string;
        review_date?: Date;
        to_name?: string;
      };
    }

    This type ensures that every search hit includes both basic document links and a detailed metadata object with key fields like document_date and file_number.

• Filter Types:
  The package defines several filter types used in metadata queries:

  • TextFilter
  • KeywordFilter
  • DateFilter
  • NumberFilter

Helper functions in the package convert date filters and format payloads consistently for all requests.

---

License

This project is open source and available for use, modification, and distribution. See the LICENSE file for details.