declassdb 0.5.2

Python client for DeclassDB.com — search declassified CIA, FBI, NSA, NARA, State Dept, and DoD documents.

declassdb

Python client for DeclassDB.com — search declassified government documents from CIA, FBI, NSA, NARA, State Department, DoD, and NSArchive.

Install

pip install declassdb

For faster HTTP (optional):

pip install declassdb[httpx]

Quick Start

from declassdb import DeclassDB

db = DeclassDB(api_key="dk_live_...")

# Search across all sources
results = db.search("MKUltra")
for doc in results:
    print(doc.title, doc.date)

API Key

Get your API key at declassdb.com/account#api-access.

You can pass it directly or set it as an environment variable:

export DECLASSDB_API_KEY=dk_live_...

# Reads from DECLASSDB_API_KEY automatically
db = DeclassDB()

Usage

Search All Sources

results = db.search("Star Gate", limit=10)
print(f"Found {results.total} documents")

for doc in results:
    print(f"[{doc.source}] {doc.title} ({doc.date})")
    print(f"  {doc.url}")

Search Specific Sources

# Single source
results = db.search("uranium", source="cia")

# Multiple sources
results = db.search("uranium", source="cia,nsa")

# Convenience methods
results = db.search_cia("OXCART A-12")
results = db.search_fbi("Hoover")
results = db.search_nsa("SIGINT")
results = db.search_nara("Manhattan Project")
results = db.search_state("Cuba missile crisis")

Pagination

# Page through results
page1 = db.search("Vietnam", limit=20, page=1)
page2 = db.search("Vietnam", limit=20, page=2)

Get Counts Only

counts = db.counts("nuclear testing")
print(counts)
# {'cia': 342, 'fbi': 12, 'state': 89, 'nsa': 7, 'nara': 4521, ...}

Export to PDF

# Save search results as PDF
db.export_pdf("OXCART", source="cia", limit=10, output_path="oxcart_results.pdf")

# Or get raw bytes
pdf_bytes = db.export_pdf("OXCART", source="cia")

Check API Key Status

info = db.key_info()
print(f"Tier: {info.tier}")
print(f"Monthly quota: {info.quota}")

Work with Results

results = db.search("Bay of Pigs", source="cia", limit=5)

# Iterate
for doc in results:
    print(doc.title)

# Index
first = results[0]

# Length
print(f"{len(results)} results returned")

# Raw dict
raw = results.to_dict()

Document Properties

Each Document object has:

doc.doc_id      # Unique document identifier
doc.title       # Document title
doc.url         # URL to view the document
doc.pdf_url     # Direct PDF URL (when available)
doc.date        # Document date (YYYY-MM-DD)
doc.collection  # Collection name
doc.snippet     # Text snippet / description
doc.pages       # Page count (when available)
doc.source      # Source agency (cia, fbi, etc.)

Command-Line Interface

The package installs a declassdb command (also python -m declassdb). It works both as a scriptable one-shot tool and as an interactive research REPL.

For the richest REPL (tab completion + persistent history), install the extra:

pip install declassdb[cli]     # adds prompt_toolkit
pip install declassdb[all]     # httpx + prompt_toolkit

One-shot commands

declassdb search "MKUltra" --source cia --limit 5
declassdb search "MKUltra" --json | jq '.results[].title'
declassdb info
declassdb export "OXCART" --format pdf -o results.pdf
declassdb export "OXCART" --format bibtex -o oxcart.bib
declassdb login                # save your API key to ~/.declassdb/config.toml
declassdb upgrade              # Paddle checkout to upgrade your tier

Output is colorized for a terminal and automatically stripped of ANSI codes when piped. NO_COLOR is honored.

Interactive REPL

Run declassdb with no arguments to drop into the session:

declassdb> cia Star Gate
declassdb> next
declassdb> open 1
declassdb> cite 2 --format ris
declassdb> save 3 cold-war
declassdb> foia 1
declassdb> counts "uranium enrichment"
declassdb> collections

After a search you reference results by number — no re-querying or copy-pasting IDs. Collections persist to ~/.declassdb/collections.json across sessions.

REPL commands

Group	Commands
Search & browse	search, cia/fbi/nsa/nara/state, next, prev, counts
Document actions	open, analyze, text, entities, foia, cite
Collections	save, collections, collection, export-collection
Session	info, history, upgrade, config, help, quit

cite (BibTeX/RIS), foia (request letter), and collections are built fully client-side from document metadata. analyze, entities, and full OCR text are powered by the DeclassDB web app and are not exposed through the public API yet — those commands say so and link to the document.

Config

Stored at ~/.declassdb/config.toml:

[auth]
api_key = "dk_live_..."

[defaults]
limit = 20
source = ""
format = "text"

[display]
color = true
page_size = 20

Change values from the REPL: config set defaults.limit 50.

Error Handling

from declassdb import DeclassDB, AuthenticationError, RateLimitError, DeclassDBError

db = DeclassDB(api_key="dk_live_...")

try:
    results = db.search("test query")
except AuthenticationError:
    print("Bad API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except DeclassDBError as e:
    print(f"API error ({e.status_code}): {e}")

Tiers

Feature	Pro	Researcher
API calls	1,000/month	10,000/month + webhooks
Sources	CIA, FBI, State, NSA, NARA	All + full-text CREST PDF search
Export	JSON, text, PDF	+ BibTeX, RIS citation export
Price	$50/yr (founder rate)	$100/yr (founder rate)

Get your key: declassdb.com

Requirements

• Python 3.8+
• No required dependencies (uses stdlib urllib)
• Optional: httpx for faster HTTP

License

MIT

Links

• Website: declassdb.com
• API Docs: declassdb.com/docs/api
• Published by: ResilientMind AI LLC (SDVOSB)