Detris documentation

Getting Started

Give your AI a task, use its virtual computer, or schedule repeat work. Connect your own agent through MCP or the API.

Building with the API or MCP?
  • GET /people?q=Dana%20Okafor&companies=Acme
  • GET /companies?industries=Software/SaaS
  • POST /agent/run

API reference → · Connect Claude Code →

Quick Start Guide

1

Sign up

Sign up with email or Google. Choose a plan or accept a Team invitation.

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

Teams

Work in a Team without buying a Personal plan. Switch workspaces from the account menu.

  1. Create: choose Set up a team, name it, choose seats, and pay in Stripe. Include a seat for yourself.
  2. Invite: verify your email, then use Settings → Teams. Pending invitations reserve seats.
  3. Join: sign in with the invited email, verify it, and accept from Team invitations or the invitation link.
  4. Share: share a list or template with a colleague. Team membership alone does not share your lists.
Seats and billing · owners
  • Open Settings → Billing in your Team.
  • Added seats start now with a prorated charge. Reductions start at renewal, with no refund or credit; paid seats stay usable until then. Review before confirming.
  • Use Update card to open Stripe. Personal billing stays separate.
  • Cancel subscription → Continue in Stripe. Confirm there, then return to Detris. Access lasts until the paid period ends; resume before then to keep it.
Privacy, schedules and access
  • Personal data stays separate. Each Team seat has its own VM, private chats and memory.
  • Loops run in the workspace where you created them and use that seat’s allowance. Losing access stops Team runs.
  • Removing a member ends their Team access and revokes Team-bound API keys. Re-inviting does not restore old shares, keys or the old seat VM.
  • A public list link can be opened without membership. Disable it to stop public access. Removing its publisher also turns it off.
Delete a Team · owners

Settings → Teams → Delete Team. Confirm the Team name and your password if asked. Access ends immediately; cleanup may take time. No refund. Team data is permanently deleted; required billing records remain. Personal accounts are unchanged.

If deletion is unconfirmed, check its status before trying again. Deleting your account is a separate action; owners must delete their Teams first.

Use a Team with API or MCP →

Virtual computer

Your AI works in a browser and with files on a persistent virtual computer.

  1. Select the Personal or Team workspace you want to use, then open VM.
  2. Sign in to the websites you need. Enter passwords and verification codes on the website, never in chat.
  3. Ask the AI for a task: “Open this website and save a summary to a file.” Watch its work in VM.
  4. Review generated files before using or sharing them. Files and browser logins are kept across ordinary restarts.
If the browser gets stuck

Check the VM before retrying: a timed-out action may have completed. Reload a crashed page. If it stays stuck, use Restart → Restart browser. Open tabs close; files and logins are kept.

Restart VM also closes running apps. Finish active work first. If a restart is unconfirmed, check its status before requesting another.

A Team seat has its own VM. Switching workspaces changes the computer you use; sharing a list does not share your browser or logins.

Gmail

  1. Open Settings → Integrations → Google.
  2. For sending only, choose Send emails → Connect Gmail. Reading mail and Calendar use the Gmail & Calendar assistant setup.
  3. Confirm the Google account and permissions. Return to Detris and check that it is connected.
  4. Ask the AI to draft your message. Review recipients and content before approving a send.

Google setup, permissions and troubleshooting →

Reconnect or remove access

Use the Google card’s menu to reconnect, change permissions or disconnect. If a send times out, check Sent mail before retrying.

Disconnecting the integration does not sign out of Google in your VM. Sign out there separately when needed.

Scheduled work

A loop repeats a task on a schedule, even when your Detris tab is closed. Loops use Sonnet 5.5 or GPT-6.1 Sol.

  1. Open Chat in the right workspace. Describe the task, timing, time zone and stopping point. For example: “Every weekday at 9am Europe/London, draft five follow-ups for this list. Stop after five runs. Do not send.”
  2. Review the proposed task, schedule and run limit, then choose Create loop. A proposal alone does not start it.
  3. Open Manage loops in that chat to check the next run, status and past results.
  4. Use Pause to prevent future runs, or Resume when ready. Review the confirmation before removing a loop.
Limits, approvals and missed runs

The shield beside the model selects Ask before actions or Bypass approvals for this chat. Bypass allows requested sends, schedules and deletions without confirmation. Existing pending actions still need your decision.

Switching back to Ask does not stop running actions or change existing loops’ permissions. Pause a loop separately when needed.

Loops share your weekly AI allowance with chat and agent tasks. Research tools have a separate allowance. A scheduled time is not a guarantee of immediate completion.

Check the loop’s status and latest result if work stops. Resolve quota, access or connection problems before resuming. Resuming starts a new run-count cycle.

Only approve unattended actions you intend to allow. Scheduling a draft does not authorize sending it. A Team loop uses its creator’s seat and pauses when that access ends.

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. 2Leave the model on Auto, or pick one from the model menu in the message box
  3. 3Describe the result you want
  4. 4Follow the tool activity and review the results

AI Tools

The agent uses these tools as it works:

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
  • In AI templates, web search needs a Claude model

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 models anytime from the model menu in the message box:

Auto (default)

Detris picks the model for you. A good choice for most work.

Claude Opus and Sonnet

Opus for complex, multi-step work. Sonnet for faster everyday tasks.

GPT models

OpenAI models, including GPT-6, if you prefer them.

🎤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.

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.

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 allowance (see Pricing)

API Integration

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

Your key is kept in this tab, sent only with requests you run, and not stored or logged on our servers. Plan limits apply. Searches don't use export allowance; exports do.

Production examples. Use a key from https://detris.ai. DEV keys and data are separate from production.

Personal or Team keys

Select your workspace, then create a key in Settings → API Keys. A Team key uses that Team automatically; no Personal subscription is required.

The key keeps your access and the selected seat’s limits. It does not unlock other members’ private data.

Workspace headers and revoked keys
  • A Team key needs no workspace header. A different X-Detris-Organization is refused.
  • Personal and older keys default to Personal. They can select a Team with X-Detris-Organization, subject to your active membership and paid seat.
  • Member removal or Team deletion revokes that Team’s bound keys. Rejoining needs a new key. An unpaid seat cannot use Team resources.

REST uses X-API-Key. Hosted MCP uses Authorization: Bearer. Treat either key like a password.

GET /people

People, filtered, without waiting for an exact total. No model; total:null means not counted.

The request
curl "https://api.detris.ai/people?industries=Software%2FSaaS&page_size=2&count_mode=deferred" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "people": [
    {
      "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": null,
  "page": 1,
  "page_size": 2,
  "has_more": true
}

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

GET /people?seniority=c_level

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

The request
curl "https://api.detris.ai/people?seniority=c_level&industries=Software%2FSaaS&page_size=2&count_mode=deferred" \
  -H "X-API-Key: $DETRIS_KEY"
Example response
{
  "people": [
    {
      "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": null,
  "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 /people?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/people?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.

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

Research a company with your API key. Uses your AI allowance and keeps run history. Requests an answer, not a saved list.

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