Getting Started

Work in Detris, connect Claude Code through MCP, or use the API in your app.

Connect Claude Code → · API quick start →

Quick Start Guide

1

Sign up

Sign up with email or Google. Choose a monthly plan.

2

Create or import a list

Choose New List, or import a CSV.

3

Use the AI Assistant

Open Chat to research, enrich, or analyze your list.

4

Try your first AI command

Try: "Find 20 SaaS companies with their website and CEO."

Explore Features

Lists

Organize your data into lists with custom columns

AI Assistant

Use Claude to query, analyze, and enrich your data

AI Templates

Generate content for hundreds of rows in minutes

API Integration

Sync with your CRM and tools programmatically

Lists

Organize records in lists with custom columns.

How to create a list

  1. Click "New List" in the dashboard
  2. Give your list a name
  3. Import data from CSV or add rows manually
  4. Customize columns to track the data you need

Rows

Each row is one record.

Working with rows

  • Add rows one at a time or import in bulk from CSV
  • Edit row data directly in the table or via detail view
  • Use bulk operations to update multiple rows at once
  • Delete rows individually or in batches

Columns

Columns define the fields in each record.

Basic column types

  • Text: Names, titles, notes
  • Email: Email addresses with validation
  • URL: Website links
  • Number: Scores, revenue, counts
  • Date: Important dates and timestamps

See Column Types below for advanced types like Single Select and Checkbox.

Column Types

Beyond basic text columns, Detris supports structured column types that make data entry faster and more consistent.

Single Select

Choose from a predefined list of options. Great for status fields, categories, or any field with a fixed set of values.

QualifiedNegotiationWon
  • • Click column header → Column Type → Single Select
  • • Add options with custom colors
  • • Drag to reorder options
  • • Auto-generate options from existing values

Checkbox

True/false toggle for binary data. Perfect for tracking completion, approval status, or any yes/no field.

  • • Click column header → Column Type → Checkbox
  • • Click to toggle on/off
  • • Choose from 8 color options
  • • Filter by checked/unchecked state

Cell Formatting

Style your cells with text formatting, alignment, and colors to highlight important data.

Text Formatting

  • Bold — ⌘B
  • Italic — ⌘I
  • Underline — ⌘U
  • Clear Formatting — ⌘\

Number Formatting

  • Number: 1,234.56
  • Currency: $1,234.56
  • Percentage: 12.34%
  • Date: Jan 15, 2025

Adjust decimal places with the toolbar spinner.

Alignment

  • Left align (default for text)
  • Center align
  • Right align (default for numbers)

Colors

  • Background color: Highlight cells
  • Text color: Emphasize text

Use the color picker buttons in the toolbar.

AI Assistant

Ask the Detris agent to research, analyze, and update your data in Chat.

What the agent can do

Query & Search - Find rows, filter data, run complex queries
Create & Update - Add rows, modify data, create templates
Generate Content - Write emails, summaries, scores for bulk data
Analyze Data - Statistics, trends, aggregations
Web Search - Research companies, find current info
Code Execution - Run Python for complex transformations

How to Use

  1. 1Open the AI pane on the right side of the dashboard
  2. 2Make sure you're in Agent mode to access tools (default)
  3. 3Describe the result you want
  4. 4Follow the tool activity and review the results

Agent vs Chat Mode

Toggle between two modes depending on what you need:

Agent Mode

Recommended

Uses enabled tools to work with your data.

  • ✓ Search and query lists
  • ✓ Create and modify rows
  • ✓ Run AI templates
  • ✓ Web search & analysis

Chat Mode

Conversation only - no tools or data access.

  • ✓ General questions
  • ✓ Brainstorming ideas
  • ✓ Writing help
  • — Tools and data access stay off

AI Tools

In Agent mode, Claude has access to these powerful tools:

Database Tool

Query and modify your data directly

  • Search, filter, and sort with natural language
  • Update multiple rows at once with smart matching
  • Add, duplicate, or delete rows in bulk
  • Run analytics and aggregations
  • Batch multiple operations together

Apply AI Template

Run AI templates on multiple rows at once

  • Generate content for 100+ rows in 2-3 minutes
  • Apply any AI template you've created
  • Track progress with real-time updates
  • Automatic cost and token tracking

Web Search

Search the web for current information

  • Find company information and news
  • Research people and organizations
  • Get current stock prices and data
  • Available with Claude Haiku 4.5 in templates

Code Execution

Run Python code for complex data transformations

  • Pandas and NumPy for data analysis
  • Pattern matching and text processing
  • Statistical calculations
  • Custom data transformations

Deduplication

Find duplicate records by one or more fields. Try:

"Find duplicate rows based on email"

"Find duplicates where name AND company match"

"Remove duplicates, keeping the first occurrence"

Claude groups matches and asks for confirmation before deleting. Deletions are permanent.

Data Augmentation

Automatically research and enrich your data via web search. Add company size, industry, LinkedIn profiles, recent funding, and more.

How It Works

  1. Create an AI template with web search enabled
  2. Claude researches each contact's company
  3. Results populate a new column

Example Prompts

"Research each company and add industry + employee count"

"Find LinkedIn URLs for each contact"

Web search costs $0.01 per lookup ($10 per 1,000 searches).

AI Templates

Generate content for hundreds of rows at once. Create a template, apply to any list.

How It Works

  1. Create a template with {column} placeholders
  2. Apply to a list - Claude processes each row
  3. Results populate a new column automatically

Example: Lead Scoring

Rate this lead 1-10: {name}, {title} at {company} Return only a number.

Pro tip: Enable Web Search to research each contact's company in real-time.

Tips & Best Practices

Choose Your Model

Switch between models anytime using the dropdown in the chat header:

Sonnet 4 (Default)

Best value. Great balance of intelligence and speed for most tasks.

Opus 4.5

Most intelligent. Best for complex reasoning, multi-step tasks, and nuanced analysis.

Haiku 4.5

Fastest & cheapest. Ideal for simple queries and quick data lookups.

🎤Voice Input

Click the microphone icon next to the send button to dictate your message. Voice recognition uses Deepgram for accurate transcription.

Tip: Voice input is great for describing complex queries naturally without typing.

✓

Use @mentions for context

Type @ to mention lists, folders, or templates. Claude instantly knows which data to use.

✓

Start small with bulk ops

Test AI templates on 5-10 rows first before running on your entire list.

✓

Inspect tool execution

Click tool steps to see exactly what queries Claude is running.

✓

Chat mode for brainstorming

Switch to Chat mode when you want to discuss ideas without modifying data.

Pricing

Monthly plans. Weekly AI allowances.

Plans and API access

  • • Paid plans include API key access.
  • • Your plan sets AI allowances, data limits, and request rates.
  • • The same API works across plans.
See plans and pricesCreate an account

AI usage

  • • Your AI allowance resets weekly. Usage depends on the model and task.
  • • At the limit, add a boost or wait for the reset. No automatic overage charges.
  • • Track usage and remaining allowance in Settings.

Formulas

Create calculated columns with formulas. Detris supports both structured formulas (like Excel) and AI-powered formulas.

Structured Formulas

Reference cells using [ColumnName]RowNumber syntax.

=[Revenue]1 - [Costs]1

Calculate profit by subtracting Costs from Revenue for row 1

  • • Math: +, -, *, /
  • • Functions: SUM(), AVG(), COUNT()
  • • Cell references are color-coded for easy reading

AI Formulas

Use natural language to create AI-powered formulas. Start with = and write your prompt.

=summarize [Description]1 in 2 sentences

AI will summarize the Description column value for row 1

=what industry is [Company]1 in?

AI will analyze the company name and return its industry

Tips

  • • Drag to fill: Drag the formula handle to apply to multiple rows
  • • Recalculate: Click the calculator icon in the toolbar to refresh formulas
  • • AI costs: AI formulas use your AI credits (see Pricing)

API Integration

Add Detris data and list workflows to your agent or app.

Sent with the requests you run on this page and nothing else — not stored on our servers, not logged, and kept in this browser tab only. Without one you still see a worked example for every endpoint. Requests are subject to your plan limits; revealing new contacts may consume contact allowance.

GET /api/published-leads/search

The corpus, filtered. Names, job titles, seniority, email status. About a second, no model.

The request
curl "https://api.detris.ai/api/published-leads/search?industries=Software%2FSaaS&page_size=2" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "leads": [
    {
      "id": "6a1f2c9e4b7d8e0a12340001",
      "full_name": "Dana Okafor",
      "job_title": "Chief Technology Officer",
      "seniority": "c_level",
      "company_name": "Acme Robotics",
      "public_linkedin_url": "https://linkedin.com/in/example-dana-okafor",
      "inferred_email": "[email protected]",
      "email_validation_status": "mx_valid"
    },
    {
      "id": "6a1f2c9e4b7d8e0a12340002",
      "full_name": "Sam Whitfield",
      "job_title": "VP Engineering",
      "seniority": "vp",
      "company_name": "Acme Robotics",
      "public_linkedin_url": "https://linkedin.com/in/example-sam-whitfield",
      "inferred_email": "[email protected]",
      "email_validation_status": "not_provided"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 2,
  "has_more": false
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET …/search?seniority=c_level

The thing a bought list cannot do: filter on how senior someone is.

The request
curl "https://api.detris.ai/api/published-leads/search?seniority=c_level&industries=Software%2FSaaS&page_size=2" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "leads": [
    {
      "id": "6a1f2c9e4b7d8e0a12340001",
      "full_name": "Dana Okafor",
      "job_title": "Chief Technology Officer",
      "seniority": "c_level",
      "company_name": "Acme Robotics",
      "public_linkedin_url": "https://linkedin.com/in/example-dana-okafor",
      "inferred_email": "[email protected]",
      "email_validation_status": "mx_valid"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 2,
  "has_more": false
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET …/search?seniorities=… (wrong on purpose)

A wrong filter is REFUSED, not ignored. An ignored filter returns the whole corpus with a 200 and looks like a search that worked.

The request
curl "https://api.detris.ai/api/published-leads/search?seniorities=c_level&page_size=2" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "detail": {
    "error": "unknown_query_parameter",
    "message": "Unknown query parameter(s): seniorities (did you mean 'seniority'?). Rejected rather than ignored, because an ignored filter returns the whole corpus with a 200 and looks like a successful search.",
    "unknown": [
      "seniorities"
    ],
    "did_you_mean": {
      "seniorities": "seniority"
    }
  }
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET /api/published-leads/usage

Export quota left on your plan.

The request
curl "https://api.detris.ai/api/published-leads/usage" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "exported_this_month": 412,
  "monthly_limit": 25000,
  "remaining": 24588,
  "reset_date": "2026-10-01T00:00:00",
  "plan_tier": "pro",
  "eligible": true,
  "can_export": true
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET /lists

Your lists, including anything the agent just built.

The request
curl "https://api.detris.ai/lists" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
[
  {
    "_id": "6a1f2c9e4b7d8e0a12345678",
    "name": "Acme Robotics — senior people",
    "stats": {
      "rowCount": 6
    },
    "created_at": "2026-09-14T18:04:11Z"
  }
]

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET /aitemplates/

AI columns you can run across every row in a list.

The request
curl "https://api.detris.ai/aitemplates/" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
[
  {
    "_id": "6a1f2c9e4b7d8e0a87654321",
    "name": "Find the work email",
    "custom_user_message": "Find a work email for {firstName} at {company}."
  }
]

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET /users/me

The account behind your key, its plan, and what it has spent.

The request
curl "https://api.detris.ai/users/me" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "email": "[email protected]",
  "plan_tier": "pro",
  "subscription_status": "active",
  "monthly_ai_allowance": 300,
  "agent_spend": 12.4,
  "agent_spend_cap": 500,
  "agent_usage_percentage": 2.48
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

Get Started

On a paid plan, create a key in Settings → API Keys. Keep it on your server.

View API ReferenceGet API Key

Webhooks

Get notified instantly when AI generation completes or data is imported. Webhooks push data to your server automatically, so you don't need to poll the API.

Setting Up Webhooks

  1. Open your profile menu and go to Settings → Webhooks
  2. Click Add Webhook
  3. Enter your HTTPS endpoint URL
  4. Select which events you want to receive
  5. Optionally scope the webhook to a specific list
Configure Webhooks

Available Events

bulk_import.completedWhen a CSV/data import finishes
ai_generation.completedWhen AI column generation finishes
ai_generation.failedWhen AI generation fails

Example Payload

{
  "event": "ai_generation.completed",
  "timestamp": "2025-11-30T20:00:00Z",
  "webhook_id": "abc123",
  "data": {
    "listId": "list_456",
    "columnName": "Lead Score",
    "rowsProcessed": 50,
    "apiUrl": "/lists/list_456/rows"
  }
}

After receiving a webhook, call the API with your API key to fetch the generated data.

Per-List Webhooks

You can scope webhooks to specific lists. When set to a specific list, the webhook only fires for events on that list. Global webhooks (no list selected) fire for all lists.

Agent API

Send a prompt to the Detris agent to research companies, enrich records, and build a list.

POST /agent/runExample only — this one creates data. Run it live below.

Send any prompt. Detris searches its own records, reads the web when it has to, and builds a list.

The request
curl -X POST "https://api.detris.ai/agent/run" \
  -H "X-API-Key: $DETRIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Find up to 6 senior people at Acme Robotics, with LinkedIn and work email. Put them in a list.","max_iterations":18}'
Example response
{
  "id": "6a1f2c9e4b7d8e0a11112222",
  "status": "queued"
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

GET /agent/run/{id}Example only — this one creates data. Run it live below.

Poll it. Comes back with the answer AND the rows — no second call to fetch the data.

The request
curl "https://api.detris.ai/agent/run/{id}?rows=10" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "status": "complete",
  "answer": "Created \"Acme Robotics — senior people\" with 2 rows. Both emails are pattern-inferred, not SMTP-verified.",
  "lists": [
    {
      "name": "Acme Robotics — senior people",
      "total_rows": 2,
      "link": "https://detris.ai/shared/6a1f2c9e4b7d8e0a12345678",
      "rows": [
        {
          "Full Name": "Dana Okafor",
          "Job Title": "Chief Technology Officer",
          "Work Email": "[email protected]",
          "Email Status": "Inferred"
        },
        {
          "Full Name": "Sam Whitfield",
          "Job Title": "VP Engineering",
          "Work Email": "[email protected]",
          "Email Status": "Inferred"
        }
      ]
    }
  ]
}

Invented data on example.com, not a recorded response — the shape is real, the people are not.

POST /agent/run — liveruns on your key · 6 per hour

Name a company. We write the prompt, your key runs it, and the agent searches the corpus and reads the web where it has to. Completion time varies. This consumes your account's AI usage. It asks for an answer rather than a saved list; run history and usage records still remain. Ask for a list in your own prompt when you want one.

Start a run

POST /agent/run { "prompt": "Find up to 10 senior execs at Advantelec with email and LinkedIn" } 202 Accepted { "id": "6a1f2c9e...", "status": "queued" }

Returns 202 with a run ID. Poll that ID for results.

Read the result

GET /agent/run/{id} { "status": "complete", "answer": "Created 'Acme Robotics — senior people', 5 rows...", "iterations": 4, "spend_usd": 0.23, "lists": [{ "name": "Acme Robotics — senior people", "total_rows": 5, "rows": [{ "Full Name": "Dana Okafor", "Title": "Chief Technology Officer", "LinkedIn URL": "https://linkedin.com/in/example-dana-okafor", "Email": "[email protected]" }], "api": "/lists/{id}/rows", "link": "https://detris.ai/shared/{id}" }] }

Includes up to 100 rows per list. Use api for more rows or link to open the list.

Response handling

  • Columns vary by run. Derive column names from the union of keys across all rows, not just rows[0].
  • Poll while active. queued and running are active; all other statuses are terminal.
  • Optional fields on the request. max_iterations defaults to 24, range 1–60. model is optional. Use a supported model ID; an unknown ID can halt an accepted run.

From MCP

Requires detris-mcp 0.3.3+. MCP setup →

run_agent starts one, agent_run_status retrieves results.

Usage and data quality

  • • Run costs depend on model usage and metered lookups.
  • • Check agent_spend in GET /users/quota. Agent runs, loops and chat share one weekly AI budget; AI columns and research tools don't count toward it. An exhausted budget returns 403.
  • • Verify mailboxes before outreach. Domain-checked and inferred emails are not mailbox-verified; retain their quality labels.
  • • Retrieve run completion by polling; agent runs do not send webhooks.

Rate Limits

API rate limits vary by plan. These limits help ensure fair usage and platform stability.

Rate Limit Responses

When you exceed rate limits, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle these gracefully. The number in the message is your plan's limit — the table above reads it live.

{ "detail": "Rate limit exceeded. Maximum 200 requests per minute. Please wait 43 seconds.", "retry_after": 43 }

Need help?

Ask us about your account or integration.

Contact Support