API Reference

Dewey is a document backend for AI applications. Upload your documents; Dewey handles conversion, chunking, embedding, and retrieval. Your application can focus on what to do with the answers, not on building the infrastructure to find them.

What you can build

The API is organized around four core capabilities:

Design philosophy

Base URL

https://api.meetdewey.com/v1

Client libraries

Official SDKs wrap the REST API and handle authentication, retries, and SSE streaming for you.

Data model

Every document produces three queryable layers that are first-class API primitives:

Quickstart#

Create a collection, upload a document, and run your first query. Pick your preferred language below.

# 1. Create a collection
curl -X POST https://api.meetdewey.com/v1/collections \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My docs", "projectId": "YOUR_PROJECT_ID"}'

# 2. Upload a document
curl -X POST https://api.meetdewey.com/v1/collections/YOUR_COLLECTION_ID/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@report.pdf"

# 3. Query
curl -X POST https://api.meetdewey.com/v1/collections/YOUR_COLLECTION_ID/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "What are the key findings?"}'

Step-by-step walkthrough

The same five steps in detail, with full error handling:

1. Create a collection

A collection is an isolated corpus. All documents and retrieval are scoped to it.

import { DeweyClient } from '@meetdewey/typescript-sdk'

const client = new DeweyClient({ apiKey: process.env.DEWEY_API_KEY! })

const collection = await client.collections.create({
  name: 'My Docs',
  projectId: process.env.DEWEY_PROJECT_ID!,
})
console.log(collection.id) // 3f7a1b2c-...

2. Upload a document

const doc = await client.documents.upload(
  collection.id,
  new Blob([require('fs').readFileSync('report.pdf')], { type: 'application/pdf' }),
)
console.log(doc.status) // "uploading"

3. Wait for ready

Processing is async. Poll the document or subscribe to SSE events (see Real-time Events).

let ready = false
while (!ready) {
  await new Promise(r => setTimeout(r, 2000))
  const d = await client.documents.get(collection.id, doc.id)
  if (d.status === 'ready') ready = true
  if (d.status === 'error') throw new Error(d.errorMessage ?? 'Processing failed')
}

4. Query

const results = await client.retrieval.query(
  collection.id,
  'What are the key findings?',
  { limit: 5 },
)
for (const r of results) {
  console.log(r.chunk.content, '-', r.document.filename)
}

5. Research (optional)

For grounded, cited answers from an agentic loop:

for await (const event of client.research.stream(
  collection.id,
  'Summarize the key findings and their implications',
  { depth: 'balanced' },
)) {
  if (event.type === 'chunk') process.stdout.write(event.content)
  if (event.type === 'done') console.log('\nSources:', event.sources)
}

Authentication#

Dewey has two auth planes. Most operations use a project API key. A small number of management operations (creating webhooks, managing org membership) require a JWT issued at sign-in.

API keys: data plane

Two keys are provisioned per project: a live key and a test key. Use them for all collection, document, retrieval, research, and provider-key endpoints. Pass the key in the Authorization header:

Authorization: Bearer dwy_live_...   # production
Authorization: Bearer dwy_test_...   # sandbox - same pipeline, isolated data

import { DeweyClient } from '@meetdewey/typescript-sdk'

const client = new DeweyClient({ apiKey: 'dwy_live_...' })

JWTs: management plane

Webhook endpoints and org/project management routes require a short-lived JWT. Obtain one by calling the login endpoint:

// POST /auth/login
{ "email": "you@example.com", "password": "..." }

// Response
{ "token": "eyJ...", "user": { "id": "...", "email": "..." } }

Then pass the token as a Bearer header alongside requests:

Authorization: Bearer eyJ...

Org and project IDs

Management-plane routes include :orgId and :projectId in their paths. These are UUIDs visible in the dashboard under Settings → General, or returned by GET /orgs and GET /orgs/:orgId/projects. One account can belong to multiple orgs; each org can have multiple projects; each project has its own API keys and collections.

Security

All data is encrypted at rest. PostgreSQL, object storage, and Redis are encrypted at the infrastructure level. Sensitive credentials — project API keys, provider API keys, and webhook signing secrets — are additionally encrypted at the application layer using AES-256-GCM before being written to the database.

Public collections

Collections with visibility: "public" allow unauthenticated reads on /query, /v1/collections/:id/sections/scan, and document reads.

Collections#

A collection is an isolated corpus of documents with its own chunking and embedding settings. All retrieval operations are scoped to a collection.

The Collection object

// Request
{
  "projectId": "proj_...",              // required - from Dashboard → Project Settings
  "name": "Engineering Docs",
  "visibility": "private",              // optional - "private" | "public", default "private"
  "description": "...",                 // optional
  "chunkSize": 512,                     // optional - 64-4096, default 512
  "chunkOverlap": 64,                   // optional - 0-512, default 64
  "embeddingModel": "text-embedding-3-small"  // optional, fixed for the lifetime of the collection
}

const collection = await client.collections.create({
  projectId: 'proj_...',
  name: 'Engineering Docs',
  visibility: 'private',
  chunkSize: 512,
  chunkOverlap: 64,
})
// => { id: '3f7a1b2c-...', name: 'Engineering Docs', ... }

const collections = await client.collections.list()
// => [{ id: '3f7a1b2c-...', name: 'Engineering Docs', ... }, ...]

const collection = await client.collections.get('3f7a1b2c-...')
// => { id: '3f7a1b2c-...', name: 'Engineering Docs', ... }

The CollectionStats object

// Request - all fields optional
{
  "name": "Renamed Docs",
  "visibility": "public",
  "description": "...",
  "chunkSize": 1024,              // 64–4096, affects new documents only
  "chunkOverlap": 128,            // 0–512, affects new documents only
  "enableSummarization": false,   // set to false during bulk ingestion to skip summarization
  "enableCaptioning": false,      // set to false to disable AI image and table captioning
  "enableReranking": false,       // set to false to skip cross-encoder reranking on queries (lower latency)
  "enableDeduplication": true,    // set to true to detect near-duplicate documents (off by default)
  "llmModel": "gpt-4o",          // optional — override default model for summarization and captioning
  "instructions": "All figures are in USD unless stated otherwise."  // optional — injected into research system prompt; set to null to clear
}

const updated = await client.collections.update('3f7a1b2c-...', {
  name: 'Renamed Docs',
  visibility: 'public',
})
// => { id: '3f7a1b2c-...', name: 'Renamed Docs', visibility: 'public', ... }

await client.collections.delete('3f7a1b2c-...')
// => 204 No Content

Recompute

When you change a collection's llmModel, existing summaries and captions were generated with the previous model. Use these endpoints to regenerate them with the new model.

// Response  200 OK  (summaries / captions)
{ "enqueued": 42 }

// Response  204 No Content  (claims)

await client.collections.recomputeSummaries('3f7a1b2c-...')
await client.collections.recomputeCaptions('3f7a1b2c-...')
await client.collections.recomputeClaims('3f7a1b2c-...')

Documents#

Documents are ingested through a pipeline: convert → section → chunk → embed → ready. Status updates are emitted in real time (see Events).

Status lifecycle

pending → uploading → processing → sectioned → embedded → ready
                                                         ↓
                                                       error  (retryable)

The Document object

Upload flow (recommended)

For large files, get a presigned URL and upload directly from the client, then confirm.

// Request
{
  "filename": "q4-report.pdf",
  "contentType": "application/pdf",
  "fileSizeBytes": 2097152,
  "contentHash": "sha256:abc123...",  // optional - enables deduplication
  "tags": ["annual", "finance"],      // optional
  "metadata": { "region": "us" }      // optional
}

const { documentId, uploadUrl } = await client.documents.requestUploadUrl(
  '3f7a1b2c-...',
  { filename: 'q4-report.pdf', contentType: 'application/pdf' }
)

// PUT the file to uploadUrl, then confirm:
await fetch(uploadUrl, { method: 'PUT', body: fileBlob })
await client.documents.confirmUpload('3f7a1b2c-...', documentId)

The UploadUrlResponse object

// Request body (all fields optional)
{
  "tags": ["annual", "finance"],
  "metadata": { "region": "us" }
}

Returns the document object (200 OK). Status transitions to "uploading".

Direct upload

curl https://api.meetdewey.com/v1/collections/:id/documents \
  -H "Authorization: Bearer dwy_live_..." \
  -F "file=@report.pdf" \
  -F 'tags=["annual","finance"]' \   # optional JSON-encoded array
  -F 'metadata={"region":"us"}'       # optional JSON-encoded object

// Response  202 Accepted
{ ...document }

import { readFileSync } from 'node:fs'

const file = new Blob([readFileSync('report.pdf')], { type: 'application/pdf' })
const doc = await client.documents.upload('3f7a1b2c-...', file, {
  tags: ['annual', 'finance'],
  metadata: { region: 'us' },
})
// => { id: '9a2c4e6f-...', status: 'uploading', tags: ['annual', 'finance'], ... }

const { documents, total } = await client.documents.list('3f7a1b2c-...')
// paginate: client.documents.list('3f7a1b2c-...', { limit: 50, offset: 50 })
// filter:   client.documents.list('3f7a1b2c-...', { status: 'error' })

const doc = await client.documents.get('3f7a1b2c-...', '9a2c4e6f-...')
// => { id: '9a2c4e6f-...', filename: 'report.pdf', status: 'ready', ... }

// Response  200 OK — document finished processing
{ "id": "9a2c4e6f-...", "status": "ready", "sectionCount": 12, ... }

// Response  200 OK — document failed
{ "id": "9a2c4e6f-...", "status": "error", "errorMessage": "...", ... }

// Response  408 Request Timeout — did not finish within 5 minutes
{ "error": "Document did not finish processing within 5 minutes" }

const markdown = await client.documents.getMarkdown('3f7a1b2c-...', '9a2c4e6f-...')
// => "# Q4 Report

## Executive Summary

..."

const sections = await client.sections.list('3f7a1b2c-...', '9a2c4e6f-...')
// => [{ id: 'b1c2d3e4-...', title: 'Executive Summary', level: 2, ... }]

The Section object

await client.documents.delete('3f7a1b2c-...', '9a2c4e6f-...')
// => 204 No Content

const doc = await client.documents.retry('3f7a1b2c-...', '9a2c4e6f-...')
// => { id: '9a2c4e6f-...', status: 'processing', ... }

// Response  200 OK - array of re-queued documents (may be empty)
[{ "id": "9a2c4e6f-...", "status": "uploading", ... }, ...]

// Request
{ "documentIds": ["9a2c4e6f-...", "b3d4e5f6-..."] }   // 1–500 IDs

// Response  200 OK - array of updated document objects
[{ "id": "9a2c4e6f-...", "status": "uploading", ... }, ...]

// Request
{ "ids": ["9a2c4e6f-...", "b3d4e5f6-..."] }   // at least 1 ID

Manage tab (dashboard UI)

Every collection page in the dashboard has a Manage tab — a document table that ties the endpoints below into a single auditing-and-editing surface. Use it to triage, tag, and edit large corpora without writing code; the same operations are available programmatically if you'd rather script them. The Manage and Overview tabs share the same search bar and filters, so switching between them preserves your context.

Capabilities

• Omnisearch — one bar for filename, tags, and metadata. The tag dropdown injects tag:<name> tokens into the query. Filename matching is fuzzy via POST /documents/search.
• Bulk operations — add or remove tags and edit metadata across every selected document at once. Up to 500 documents per request via PATCH /documents/bulk.
• Sticky selection across pagination — paginate without losing your selection. Navigate to any page, refine the filter, multi-select, then act on the union.
• Single-doc edit panel — click any row to open a side panel for editing that document's tags and metadata. Backed by PATCH /documents/:docId.
• Tag chips — every row shows its tags as colored chips so you can scan a list visually before drilling in.

Search bar DSL

The search bar accepts a small DSL that compiles into the same query parameters you'd send to POST /documents/search. Tokens AND together; the free-text portion fuzzy-matches filenames. Wrap values that contain spaces in double quotes.

tag:annual meta.region:us 2024-q1

Keyboard shortcuts

Update tags and metadata

// Request
{
  "tags": ["q1", "finance"],          // replaces existing tags entirely
  "metadata": { "region": "emea" },   // merged into existing metadata by default
  "replaceMetadata": true             // optional — replace instead of merge
}

// Response  200 OK
{ ...document }

const doc = await client.documents.update(
  '3f7a1b2c-...',
  '9a2c4e6f-...',
  { tags: ['q1', 'finance'], metadata: { region: 'emea' } },
)

Bulk update tags & metadata

// Request
{
  "documents": [
    {
      "id": "9a2c4e6f-...",
      "tags": ["q1", "finance"],
      "metadata": { "region": "emea" }
    },
    {
      "id": "b3d4e5f6-...",
      "tags": ["hr"],
      "replaceMetadata": true,    // optional — replace instead of merge
      "metadata": { "year": 2024 }
    }
  ]
}

// Response  200 OK
[ ...documents ]

const docs = await client.documents.bulkUpdate(
  '3f7a1b2c-...',
  [
    { id: '9a2c4e6f-...', tags: ['q1', 'finance'], metadata: { region: 'emea' } },
    { id: 'b3d4e5f6-...', tags: ['hr'], replaceMetadata: true, metadata: { year: 2024 } },
  ],
)

List tags

// Response  200 OK
{
  "tags": [
    { "name": "annual",  "count": 12 },
    { "name": "finance", "count":  8 }
  ]
}

const { tags } = await client.documents.listTags('3f7a1b2c-...')
// tags[0].name, tags[0].count

Search by filename

// Request
{
  "q": "annual-report",                  // required — search string
  "limit": 20,                           // optional, 1–100, default 20
  "tags": ["finance"],                   // optional — docs must have ALL these tags
  "anyTags": ["internal", "external"],   // optional — docs must have ANY of these tags
  "metadata": { "region": "us" }         // optional — docs must contain all these key-value pairs
}

// Response  200 OK
[
  {
    "score": 0.82,
    "document": {
      "id": "9a2c4e6f-...",
      "filename": "annual-report-2024.pdf",
      "status": "ready",
      ...
    }
  }
]

const results = await client.documents.searchDocuments(
  '3f7a1b2c-...',
  'annual-report',
  { limit: 10, tags: ['finance'] },
)
// results[0].score, results[0].document.filename

Images#

Images and figures extracted from documents are stored with stable, auth-gated URLs and embedded in the document Markdown as standard ![alt](url) references. Access requires the same collection-level auth as all other document routes.

The DocumentImage object

// Response  200 OK
[
  {
    "id": "5a9f1892-...",
    "sectionId": "e3d7c1a0-...",
    "placeholder": "dewey://img-0",
    "mimeType": "image/png",
    "caption": "A bar chart showing accuracy vs. model size.",
    "position": 0
  }
]

Table Captions#

After a document is ingested, Dewey runs an async job that generates a one-to-two sentence AI caption for each table chunk, describing its subject, key columns, and notable values. Captions are stored alongside the chunk and rendered as italicised figcaptions beneath tables in the document viewer.

GET /v1/documents/:id/chunks/captions

Returns all chunks that have a caption, ordered by section position then chunk position within the document. Use this to build a content-keyed lookup for rendering captions in your own viewer.

// Response  200 OK
[
  {
    "content": "| Quarter | Revenue |\n|---------|---------|\n| Q1 | $2.4M |",
    "caption": "Quarterly revenue table showing Q1 results of $2.4M."
  }
]

Retrieval#

Two retrieval primitives: hybrid chunk search for direct content retrieval, and section scan for lightweight exploration of large corpora without loading chunk content.

// Request
{
  "q": "what are the side effects of the treatment?",
  "limit": 10,                          // optional, 1–50, default 10
  "tags": ["annual", "finance"],        // optional — docs must have ALL these tags
  "anyTags": ["internal", "external"],  // optional — docs must have ANY of these tags
  "metadata": { "region": "us" }        // optional — docs must contain all these key-value pairs
}

// Response  200 OK
[
  {
    "score": 0.97,
    "chunk": {
      "id": "c1d2e3f4-...",
      "content": "The most common side effects reported were...",
      "position": 3,
      "tokenCount": 128
    },
    "section": {
      "id": "b1c2d3e4-...",
      "title": "Adverse Events",
      "level": 2
    },
    "document": {
      "id": "9a2c4e6f-...",
      "filename": "clinical-trial-2024.pdf"
    }
  }
]

const results = await client.retrieval.query(
  '3f7a1b2c-...',
  'what are the side effects of the treatment?',
  { limit: 10, tags: ['annual'], metadata: { region: 'us' } },
)
// results[0].score, results[0].chunk.content, results[0].document.filename

// Request
{
  "query": "adverse events and safety profile",
  "top_k": 20,                           // optional, 1–100, default 20
  "tags": ["annual", "finance"],         // optional — docs must have ALL these tags
  "anyTags": ["internal", "external"],   // optional — docs must have ANY of these tags
  "metadata": { "region": "us" }         // optional — docs must contain all these key-value pairs
}

// Response  200 OK
{
  "results": [
    {
      "score": 0.91,
      "section": {
        "id": "b1c2d3e4-...",
        "title": "Adverse Events",
        "level": 2,
        "summary": "This section describes reported adverse events..."
      },
      "document": {
        "id": "9a2c4e6f-...",
        "filename": "clinical-trial-2024.pdf"
      }
    }
  ]
}

const { results } = await client.sections.scan(
  '3f7a1b2c-...',
  'adverse events and safety profile',
  { topK: 20, tags: ['annual'], metadata: { region: 'us' } },
)
// results[0].score, results[0].section.title, results[0].document.filename

Section content and chunks

// Response  200 OK
{
  ...section,
  "content": "## Adverse Events

The most common side effects..."
}

const chunks = await client.sections.getChunks('b1c2d3e4-...')
// => [{ id: 'c1d2e3f4-...', content: '...', position: 0, tokenCount: 128 }, ...]

Research#

The research endpoint runs a multi-step agentic loop, searching, scanning, and reading sections, then produces a grounded, cited answer. Two variants are available: a streaming endpoint that returns Server-Sent Events, and a buffered /sync endpoint that returns a single JSON response when the answer is complete.

// Request
{
  "q": "What role does silent adult-to-child transmission play in major polio outbreaks?",
  "depth": "exhaustive",              // optional - "quick" | "balanced" | "deep" | "exhaustive", default "balanced"
  "model": "gpt-5.4",                 // optional - defaults to "gpt-5.4" for deep/exhaustive, "gpt-4o-mini" otherwise
  "tags": ["annual", "finance"],      // optional — restrict search to docs with ALL these tags
  "anyTags": ["internal", "public"],  // optional — restrict search to docs with ANY of these tags
  "metadata": { "region": "us" }      // optional — restrict search to docs matching this metadata
}

// Headers required for SSE
Accept: text/event-stream

for await (const event of client.research.stream(
  '3f7a1b2c-...',
  'What role does silent adult-to-child transmission play in major polio outbreaks?',
  { depth: 'balanced', tags: ['annual'], metadata: { region: 'us' } },
)) {
  if (event.type === 'chunk') process.stdout.write(event.content)
  if (event.type === 'done') console.log(event.sources)
}

// Request — same body as the streaming endpoint
{
  "q": "What role does silent adult-to-child transmission play in major polio outbreaks?",
  "depth": "balanced",             // optional
  "tags": ["annual"],              // optional
  "anyTags": ["internal"],         // optional
  "metadata": { "region": "us" }   // optional
}

// Response
{
  "answer": "...",       // full markdown answer with inline citations
  "sessionId": "uuid",
  "sources": [ /* ResearchSource objects */ ]
}

Depth levels

Supported models

OpenAI, Anthropic, and Google Gemini models are supported. The model field is routed to the appropriate provider based on the model ID prefix (gpt- / o → OpenAI, claude- → Anthropic, gemini- → Google Gemini). Common choices:

SSE events

Each event is a data: {...}\n\n line. Parse with JSON.parse(event.data).

// Example SSE stream
data: {"type":"tool_call","query":"silent transmission polio"}

data: {"type":"tool_call","query":"Blake2014-PNAS.pdf › Results","tool":"get_section_chunks"}

data: {"type":"chunk","content":"In Congo 2010"}
data: {"type":"chunk","content":", adults had an estimated R of 1.85"}

data: {"type":"done","sessionId":"e4f5...","sources":[
  {"chunkId":"...","filename":"Blake2014-PNAS.pdf","sectionTitle":"Results"},
  {"chunkId":"...","filename":"PatriarcaPA1997.pdf","sectionTitle":"Outbreak Analysis"}
]}

The DoneEvent object

The ResearchSource object

Research history

The ResearchSession object

Hosted Agents#

Hosted agents are saved configurations that wrap the same agentic loop as /research, but with a fixed identity, prompt, model, and allow-list of collections. You define the agent once via the dashboard or the CRUD API, then invoke it by slug. Each invocation runs the executor against the agent's configured tools and collections, streams events, persists a run record, and enforces credit and concurrency limits.

Agents vs. /research

Both endpoints run the same executor — multi-step tool use, hybrid search, section scanning, and grounded answers with citations. The difference is how the run's configuration gets specified.

Agent

Create an agent

// Request
{
  "slug": "compliance-helper",
  "name": "Compliance Helper",
  "description": "Answers questions about our compliance docs.",
  "systemPrompt": "You are a compliance specialist. Cite specific clauses.",
  "model": "claude-sonnet-4-6",
  "timeoutMs": 300000,                // optional
  "toolset": {                        // optional - all true by default
    "search_collection": true,
    "scan_sections": true,
    "get_section_chunks": true,
    "list_documents": false,
    "get_document": false
  },
  "allowedCollectionIds": ["3f7a1b2c-..."]   // null = all collections
}

// 409 if slug collides; 400 if allowedCollectionIds is an empty array.

List, read, update, delete

Invoke (streaming)

// Request
{
  "query": "What does our policy say about data residency?"
}

// Headers required for SSE
Accept: text/event-stream

for await (const event of client.agents.stream(
  orgId,
  projectId,
  'compliance-helper',
  { query: 'What does our policy say about data residency?' },
)) {
  if (event.type === 'chunk') process.stdout.write(event.content)
  if (event.type === 'done') console.log(event.runId)
}

Invoke (buffered)

// Request — same body as /invoke
{
  "query": "What does our policy say about data residency?"
}

// Response
{
  "runId": "uuid",
  "response": "...",       // full markdown with inline citations
  "status": "succeeded",   // or "failed" | "cancelled" | "timeout"
  "sources": [ /* AgentRunSource objects */ ],
  "warnings": []           // populated for timeout / context-budget cases
}

const result = await client.agents.invokeSync(
  orgId,
  projectId,
  'compliance-helper',
  { query: 'What does our policy say about data residency?' },
)
console.log(result.response)
for (const s of result.sources) {
  console.log(`- ${s.filename} § ${s.sectionTitle}`)
}

Preview (no persistence)

// Request
{
  "query": "Draft a release-notes blurb",
  "draft": {
    "systemPrompt": "You write concise release notes.",
    "model": "claude-sonnet-4-6",
    "timeoutMs": 60000,
    "toolset": { "search_collection": true, "scan_sections": false, ... },
    "allowedCollectionIds": ["3f7a1b2c-..."]
  }
}

SSE events

Both /invoke and /preview emit the same event shapes. /invoke/sync waits for done internally and returns its payload as the response body.

Run history

Supported models

Same provider matrix as /research — OpenAI, Anthropic, and Google Gemini, routed by model-ID prefix. Hosted agents always require a project provider key (BYOK) regardless of model — the Dewey-managed key is never used for agent invocations because each agent's model and prompt belong to the project that owns it.

Claims Beta#

When claim extraction is enabled on a collection, Dewey automatically extracts factual claims from each document as it is processed. Claims are scored by importance (1 = low, 5 = critical). The claim map endpoint uses UMAP to project all claims into a 2-D space for visualization.

The Claim object

Query parameters: minImportance (1–5, default 1).

// Response  200 OK
{
  "documentId": "9a2c4e6f-...",
  "claims": [
    {
      "id": "c1b2a3d4-...",
      "text": "Revenue grew 42% year-over-year in Q3.",
      "sourceText": "Revenue grew 42% year-over-year in Q3, driven by...",
      "sectionTitle": "Financial Results",
      "sectionId": "s1a2b3c4-...",
      "documentId": "9a2c4e6f-...",
      "importance": 4,
      "position": 7
    }
  ]
}

const { claims } = await client.claims.listByDocument('9a2c4e6f-...', {
  minImportance: 3,
})

This endpoint streams SSE events. Set the Accept: text/event-stream header. Progress events are emitted as claims are embedded and projected; the final done event contains the full claim list with x/y coordinates.

SSE events

The ClaimMapItem object

for await (const event of client.claims.mapStream('3f7a1b2c-...')) {
  if (event.type === 'progress') console.log(`${event.pct}%`)
  if (event.type === 'done') console.log(`${event.total} claims`, event.claims)
}

Contradictions Beta#

Contradiction detection analyzes all extracted claims in a collection for conflicts, groups them into clusters, and generates a resolution suggestion for each cluster. Detection runs are asynchronous — trigger a run and poll its status, then fetch results once complete.

The Contradiction object

Query parameters: status (active | dismissed | applied, default active), severity (low | medium | high), limit (1–100, default 20).

const { total, items } = await client.contradictions.list('3f7a1b2c-...', {
  status: 'active',
  severity: 'high',
})

// Response  200 OK
{
  "runId": "r1a2b3c4-...",
  "status": "enqueued",
  "enqueuedAt": "2024-09-01T12:00:00Z"
}

const run = await client.contradictions.detect('3f7a1b2c-...')
console.log(run.runId, run.status)

The ContradictionRun object

const run = await client.contradictions.getLatestRun('3f7a1b2c-...')
console.log(run.status, run.contradictionsFound)

// Request
{ "status": "dismissed" }

const updated = await client.contradictions.dismiss('3f7a1b2c-...', 'c1b2a3d4-...')

Pass a custom instruction in the request body to override the suggested instruction. If omitted, the contradiction's suggestedInstruction is used.

// Request (optional)
{ "instruction": "Use the 2024 annual report as the authoritative source." }

// Response  204 No Content

// Use suggested instruction
await client.contradictions.applyInstruction('3f7a1b2c-...', 'c1b2a3d4-...')

// Override with custom instruction
await client.contradictions.applyInstruction(
  '3f7a1b2c-...', 'c1b2a3d4-...',
  'Use the 2024 annual report as the authoritative source.',
)

Duplicates Beta#

Fuzzy deduplication identifies near-duplicate documents within a collection by measuring how much content they share. Each cluster has one canonical member; the rest are marked near_duplicate and excluded from retrieval and contradiction detection. Detection is off by default — enable it per-collection with enableDeduplication: true.

The DuplicateGroup object

Each member has relationship (canonical | near_duplicate), coverageToCanonical (fraction 0–1), and coverageFromCanonical.

// Response  202 Accepted
{
  "runId": "r1a2b3c4-...",
  "status": "pending",
  "jobsEnqueued": 142,
  "enqueuedAt": "2026-04-16T12:00:00Z"
}

const run = await client.duplicates.detect('3f7a1b2c-...')
console.log(run.runId, run.jobsEnqueued)

The DuplicateRun object

const run = await client.duplicates.getLatestRun('3f7a1b2c-...')
console.log(run.status, run.duplicateGroupsCreated)

Query parameters: limit (1–100, default 50), offset (default 0).

const { total, items } = await client.duplicates.list('3f7a1b2c-...', { limit: 20 })
for (const group of items) {
  for (const m of group.members) {
    if (m.relationship === 'near_duplicate') {
      console.log(m.filename, Math.round((m.coverageToCanonical ?? 0) * 100) + '%')
    }
  }
}

// Request
{ "canonicalDocumentId": "d2e4f6a8-..." }

// Response
{ "success": true, "changed": true }

await client.duplicates.promoteCanonical('3f7a1b2c-...', 'g1h2i3j4-...', 'd2e4f6a8-...')

await client.duplicates.disband('3f7a1b2c-...', 'g1h2i3j4-...')

Provider Keys#

Store your own OpenAI, Anthropic, or Google Gemini key per project. When configured, Dewey uses your key for research, bypassing the shared managed key. Keys are encrypted at rest with AES-256-GCM.

// Request
{
  "provider": "openai",  // "openai" | "anthropic" | "gemini"
  "key": "sk-...",
  "name": "Production key"
}

const key = await client.providerKeys.create('proj_abc123', {
  provider: 'openai',
  key: 'sk-...',
  name: 'Production key',
})
// => { id: 'k1a2b3c4-...', provider: 'openai', keyPreview: 'sk-t...cdef', ... }

The ProviderKey object

const keys = await client.providerKeys.list('proj_abc123')
// => [{ id: 'k1a2b3c4-...', provider: 'openai', keyPreview: 'sk-t...cdef', ... }]

await client.providerKeys.delete('proj_abc123', 'k1a2b3c4-...')
// => 204 No Content

Real-time Events#

Subscribe to document status changes as they happen using Server-Sent Events.

const es = new EventSource(
  `https://api.meetdewey.com/v1/collections/${collectionId}/documents/events` +
  `?key=${apiKey}`
)

es.onmessage = (e) => {
  const event = JSON.parse(e.data)
  // event.documentId, event.collectionId, event.status, event.sectionCount?
  if (event.status === 'ready') {
    console.log(`${event.documentId} is queryable`)
  }
}

// Ping sent every 20 seconds to keep the connection alive.

The DocumentEvent object

Webhooks#

Webhooks let your server receive push notifications when documents finish processing, no polling required. Configure one or more endpoints per project; Dewey will POST a signed JSON payload to each endpoint whenever a subscribed event fires.

const res = await fetch(
  `https://api.meetdewey.com/v1/orgs/${orgId}/projects/${projectId}/webhooks`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://yourapp.com/hooks/dewey',
      events: ['document.ready', 'document.error'], // omit for all events
      description: 'Production handler',
    }),
  }
)
const { id, secret } = await res.json()
// Save secret - it will not be returned again

The WebhookEndpoint object

Event types

Payload shape

Every webhook POST has Content-Type: application/json and the following top-level shape:

{
  "id": "wh_3f7a1b2c4d5e6f...",   // unique delivery ID
  "type": "document.ready",        // event type
  "created": 1712345678,           // Unix timestamp (seconds)
  "data": {
    "documentId":   "9a2c4e6f-...",
    "collectionId": "3f7a1b2c-...",
    "projectId":    "1a2b3c4d-...",
    // document.error only:
    "error": "Conversion failed: unsupported file format"
  }
}

Signature verification

Every delivery includes an X-Dewey-Signature header containing an HMAC-SHA256 of the raw request body, computed with the endpoint's signing secret:

X-Dewey-Signature: sha256=<hex digest>
X-Dewey-Event-Id:   <delivery UUID>
X-Dewey-Event-Type: document.ready

Verify the signature before processing the event:

import { createHmac, timingSafeEqual } from 'node:crypto'

function verifyWebhook(
  rawBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = 'sha256=' +
    createHmac('sha256', secret).update(rawBody).digest('hex')
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

// Express / Next.js example
app.post('/hooks/dewey', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['x-dewey-signature'] as string
  if (!verifyWebhook(req.body.toString(), sig, process.env.DEWEY_WEBHOOK_SECRET!)) {
    return res.sendStatus(401)
  }
  const event = JSON.parse(req.body.toString())
  // handle event.type === 'document.ready' etc.
  res.sendStatus(200)
})

The WebhookDelivery object

MCP Server#

Dewey ships a native Model Context Protocol server. Any MCP-compatible client (Claude, Cursor, custom agents) can search, research, manage collections and documents, extract claims, and detect contradictions directly, with no API integration required. Two ways to connect: a hosted endpoint with OAuth (recommended), or a local install with an API key.

Hosted MCP

Add Dewey as a custom MCP server in your client with this URL:

https://mcp.meetdewey.com/mcp

On first connect, your client redirects you through an OAuth consent screen on app.meetdewey.com. Sign in to your Dewey account, pick the org the client should access, and approve. The client receives a scoped access token — no API key in your client config, no shared secrets.

Scopes

Manage and revoke connected MCP clients from Connected apps in your dashboard.

Local install

Prefer to run the MCP server locally? Add Dewey to your claude_desktop_config.json:

{
  "mcpServers": {
    "dewey": {
      "command": "npx",
      "args": ["-y", "@meetdewey/mcp"],
      "env": {
        "DEWEY_API_KEY": "dwy_live_...",
        "DEWEY_COLLECTION_ID": "3f7a1b2c-..."  // optional - scope to one collection
      }
    }
  }
}

Available tools

Search

Claims

Quality

Management

CLI#

dewey is a single binary that gives developers terminal-native access to every Dewey capability — upload, retrieval, research, and operations — without writing any code. It is the fastest way to go from an API key to a grounded answer over your own documents.

Install

Download the latest release for your platform from GitHub Releases and move the binary to a directory in your PATH:

curl -fsSL https://raw.githubusercontent.com/meetdewey/dewey-cli/main/install.sh | sh

The script detects your OS and architecture, downloads the correct binary, verifies the SHA-256 checksum, and installs to ~/.local/bin (no sudo required). Override with INSTALL_DIR=/usr/local/bin sh install.sh.

Or download a specific release directly — GoReleaser names archives as dewey_<version>_<os>_<arch>.tar.gz:

# Example: v0.1.0 on macOS arm64
curl -Lo dewey.tar.gz \
  https://github.com/meetdewey/dewey-cli/releases/download/v0.1.0/dewey_0.1.0_darwin_arm64.tar.gz
tar -xzf dewey.tar.gz && mv dewey /usr/local/bin/

Windows users can download the .zip from the Releases page.

Authentication

Set your project API key in the environment. Every data-plane command reads it from there — you never need to pass it on the command line.

export DEWEY_API_KEY=dwy_live_…

The --api-key flag is also accepted (prefer the env var). Commands that require auth exit with code 77 and a hint if the key is missing.

Commands

Every command accepts a -c / --collection flag. The last-used collection is cached in ~/.dewey/state.toml so you can omit -c on subsequent commands.

dewey upload

The most-used command. Accepts file paths, glob patterns, or - to read from stdin. Pass --watch to stream live processing events until every document reaches a terminal state, or --wait to block silently (useful in CI).

dewey upload ./papers/*.pdf -c research-papers --watch

Uploading 3 files to research-papers
  [ok] attention.pdf   uploaded  doc_a1
  [ok] bert.pdf        uploaded  doc_a2
  [ok] gpt4.pdf        uploaded  doc_a3
Watching processing events (Ctrl-C to detach):
  [ok] doc_a1  attention.pdf   ready
  [ok] doc_a2  bert.pdf        ready
  [ok] doc_a3  gpt4.pdf        ready
[ok] 3/3 ready in 31s.

dewey research

Streams the agentic answer token-by-token when stdout is a TTY, then prints a citation block. Pass --no-stream to return a single response, or pipe the output to get NDJSON automatically.

dewey research research-papers "how does multi-head attention work?" --depth deep

→ search: multi-head attention mechanism
→ search: scaled dot-product attention
Multi-head attention runs H parallel attention functions...
[continues streaming]

— Citations ——————————————————————————————————
[1] attention.pdf § 3. Multi-Head Attention
[2] attention.pdf § 3.2 Scaled Dot-Product Attention

dewey doctor

Validates the full environment in one command: API key presence, base URL, DNS resolution, TLS certificate, a live GET /collections check, and telemetry status.

dewey doctor

Checking environment...
  [ok] DEWEY_API_KEY is set (dwy_live_…vJ3K)
  [ok] Base URL → https://api.meetdewey.com/v1 (default)
  [ok] DNS resolves
  [ok] TLS handshake (issued by R12, valid 73 days)
  [ok] GET /collections returned 200 in 142ms (3 collections)
  [ok] Anonymous telemetry: on (DEWEY_TELEMETRY=0 to opt out)
All systems go.

Exits 0 if all checks pass. Exits 1 on any failure with a per-check remediation hint. Point DEWEY_BASE_URL at http://localhost:3000/v1 to run doctor against a local server.

Configuration

The CLI reads ~/.dewey/config.toml on startup. Edit it directly or use dewey config set:

# ~/.dewey/config.toml
default_collection = "research-papers"
output = "human"   # "human" | "json"
color  = "auto"    # "auto" | "always" | "never"
# base_url = "http://localhost:3000/v1"  # uncomment for local dev

--json mode

Every command supports --json for machine-readable output. The contract is stable across minor CLI versions; breaking changes bump the major version. Streamed commands (research --stream --json) emit NDJSON — one object per event — so they pipe cleanly to jq.

# Stream a research answer and capture only the final done event
dewey research my-collection "question" --stream --json | jq -s 'last'

# List collections as JSON and filter by name
dewey --json collections list | jq '.[] | select(.name == "research-papers")'

# Wait for a document and assert it's ready
dewey --json docs wait doc_abc123 | jq -e '.status == "ready"'

Diagnostic output (progress, status lines) always goes to stderr, so redirecting stdout captures only the data you asked for.

Usage & Quotas#

Fetch current usage and plan limits for a project. Useful for building quota warnings into your own UI or automation.

// Response  200 OK
{
  "meters": {
    "documents": { "used": 23,   "limit": 500   },
    "queries":   { "used": 1840, "limit": 2000  },
    "credits":   { "used": 4.5,  "limit": 25    },
    "storage":   { "usedMb": 312, "limitMb": 500 }
  }
}

Errors#

All errors return a JSON body with an error field:

{
  "error": "Collection not found"
}