API Reference

The data layer for your agent or app. Search business records, enrich data, and manage lists.

Common Workflows

Agent quick start: GET /help (no key required)
Search records: GET /api/published-leads/search
Enrich with AI: POST /augment with data + prompt
Form submission: POST /lists/{list_id}/rows
CRM sync: POST /lists/{list_id}/rows/upsert
Export data: GET /lists/{list_id}/rows

Rows and integration sync

Response shapes are endpoint-specific: GET /lists returns an array; GET rows returns a rows array plus pagination; single-row reads and writes return the row directly. A row's data object contains its custom column values.

email, firstName and company are example column names, not a fixed contact schema. Configure a field mapping for each list. Discover known keys through GET list's fields_schema and the union of row.data keys; essentialColumns describes visible/preferred columns, not every field. Preserve unmapped values as custom fields.

For sync, explicitly send use_view_state=false. Page with limit and offset until rows is empty. Offset pagination is not a snapshot: concurrent writes can move rows, so deduplicate by _id and reconcile periodically. updated_since finds changed existing rows; it does not report deletions.

Create and update rows with { "data": { "title": "CEO" } }. Batch updates use { "updates": [{ "row_id": "...", "data": { "title": "CEO" } }] }. Check failed/errors for partial batch outcomes. Do not automatically retry a create after an ambiguous network error.

Authentication

Include your API key in the X-API-Key header. Keep it on your server and enforce your clients’ permissions there.

https://api.detris.ai

Webhooks

For generation and import events, use Settings → Webhooks. Choose all lists or a specific list.

Agent instructions — no key required

curl -fsS https://api.detris.ai/help

Endpoints, limits, and setup instructions.

Connect your agent over MCP

claude mcp add --transport http detris https://detris.ai/mcp \
  --header "Authorization: Bearer sk_live_..."

Nothing to install. Any MCP client that speaks Streamable HTTP can use https://detris.ai/mcp with the same header. Create a key in Settings → API Keys.

Or run it on your machine (adds local SQLite sync)

claude mcp add detris \
  -e DETRIS_API_KEY=sk_live_... \
  -- npx -y detris-mcp

Requires Node 22.13+.

Look up one person in about a second

curl -G https://api.detris.ai/api/published-leads/search \
  -H "X-API-Key: sk_live_..." \
  --data-urlencode "q=Jane Doe" \
  --data-urlencode "companies=Acme" \
  -d page_size=5

q searches names, titles and companies; companies narrows to the employer. No model runs. If nobody matches, POST /agent/run researches the web (30-120 s).

Import + AI in one call

curl -X POST https://api.detris.ai/augment \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "data": [{"name": "John", "company": "Acme"}],
    "prompt": "Score 1-10: {name} at {company}",
    "ai_column": "lead_score",
    "list_name": "Leads"
  }'

POST/lists

Create an empty list

Create a list without running AI. Add rows separately. Normal plan and storage limits apply; this does not invoke augmentation.

Request Body

namestringrequired

List name

curl -X POST 'https://api.detris.ai/lists' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Enterprise Leads"
}'

Response

{
  "_id": "692397ea61746762ff5d587e",
  "name": "Enterprise Leads",
  "stats": {
    "rowCount": 0
  },
  "fields_schema": []
}

GET/lists/{list_id}/rows/{row_id}

Get one row

Read one row in an accessible list. Returns the row object directly, not a data/rows envelope. Missing row or wrong list returns 404.

Path Parameters

list_idstringrequired

List ID returned by GET /lists

row_idstringrequired

Row _id returned by GET rows (24-character hexadecimal ID)

curl -X GET 'https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/692397ea61746762ff5d587f' \
  -H 'X-API-Key: sk_live_your_api_key_here'

Response

{
  "_id": "692397ea61746762ff5d587f",
  "listId": "692397ea61746762ff5d587e",
  "data": {
    "email": "[email protected]",
    "firstName": "John",
    "company": "Acme Inc"
  }
}

PATCH/lists/{list_id}/rows/{row_id}

Update one row

Merge supplied data fields into one row; omitted fields are preserved. Wrap fields in data. Requires edit access. Use PATCH, not PUT; returns the updated row directly.

Path Parameters

list_idstringrequired

List ID returned by GET /lists

row_idstringrequired

Row _id returned by GET rows (24-character hexadecimal ID)

Request Body

dataobjectrequired

Only the custom fields to change

curl -X PATCH 'https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/692397ea61746762ff5d587f' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "data": {
    "title": "CEO"
  }
}'

Response

{
  "_id": "692397ea61746762ff5d587f",
  "listId": "692397ea61746762ff5d587e",
  "data": {
    "email": "[email protected]",
    "firstName": "John",
    "company": "Acme Inc",
    "title": "CEO"
  }
}

DELETE/lists/{list_id}/rows/{row_id}

Delete one row

Permanently delete one row in an editable list. No request body. Returns a confirmation object; deleting it again returns 404.

Path Parameters

list_idstringrequired

List ID returned by GET /lists

row_idstringrequired

Row _id returned by GET rows (24-character hexadecimal ID)

curl -X DELETE 'https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/692397ea61746762ff5d587f' \
  -H 'X-API-Key: sk_live_your_api_key_here'

Response

{
  "detail": "Row deleted successfully"
}

POST/lists/{list_id}/rows/bulk-delete

Delete selected rows

Permanently delete selected rows in this list. Compare deleted_count with requested_count; already missing IDs are not deleted again. Requires edit access.

Path Parameters

list_idstringrequired

List ID returned by GET /lists

Request Body

row_idsarrayrequired

Row _id strings to delete; must not be empty

curl -X POST 'https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/bulk-delete' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "row_ids": [
    "692397ea61746762ff5d587f"
  ]
}'

Response

{
  "detail": "Successfully deleted 1 rows",
  "deleted_count": 1,
  "requested_count": 1
}

POST/augment

Augment with data

Create a list, import rows, and enrich them with one data-and-prompt request.

Request Body

dataarrayrequired

Row objects to import. Row limits depend on your plan; see /docs#rate-limits.

promptstringrequired

AI prompt with {field} placeholders referencing your data fields

ai_columnstringrequired

Column name where generated content will be stored

list_namestringrequired

Name for the new list that will be created

modelstring

AI model: gpt-5.4-mini (default), gpt-5.4, gpt-5.4-nano, gpt-5.3-codex, claude-haiku-4.5

enable_web_searchboolean

Enable web search for each row (adds $0.01/row)

Response

statusstringrequired

"started" when generation begins

messagestringrequired

Human-readable status message

list_idstringrequired

ID of the newly created list

list_namestringrequired

Name of the created list

rows_importedintegerrequired

Number of rows imported

curl -X POST https://api.detris.ai/augment \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"name": "John Smith", "company": "Acme Inc"},
      {"name": "Jane Doe", "company": "Tech Corp"}
    ],
    "prompt": "Score this lead 1-10: {name} at {company}",
    "ai_column": "lead_score",
    "list_name": "Q4 Leads"
  }'

Response

{
  "status": "started",
  "message": "Created list 'Q4 Leads' with 2 rows. AI generation started.",
  "list_id": "new_list_abc123",
  "list_name": "Q4 Leads",
  "rows_imported": 2
}

POST/lists/{list_id}/augment

Augment existing list

Add AI-generated columns to an existing list.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

promptstringrequired

AI prompt with {field} placeholders referencing row data

ai_columnstringrequired

Column name where generated content will be stored

row_idsarray

Specific row IDs to process (defaults to all rows in list)

modelstring

AI model: gpt-5.4-mini (default), gpt-5.4, gpt-5.4-nano, gpt-5.3-codex, claude-haiku-4.5

enable_web_searchboolean

Enable web search for each row (adds $0.01/row)

Response

statusstringrequired

"started" when generation begins

messagestringrequired

Human-readable status message

list_idstringrequired

List being processed

ai_columnstringrequired

Column being populated

rows_queuedintegerrequired

Number of rows queued for processing

curl -X POST https://api.detris.ai/lists/692397ea61746762ff5d587e/augment \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Score this lead 1-10 based on {name} at {company}",
    "ai_column": "lead_score"
  }'

Response

{
  "status": "started",
  "message": "AI generation started for 100 rows",
  "list_id": "692397ea61746762ff5d587e",
  "ai_column": "lead_score",
  "rows_queued": 100
}

GET/lists

Get all lists

Retrieve all lists in your account. Use this to find the list_id for other operations.

Response

(response)arrayrequired

Bare JSON array of list objects; there is no top-level data envelope

_idstringrequired

Unique list identifier

namestringrequired

List name

stats.rowCountinteger

Number of rows, when list statistics are available

created_atstringrequired

ISO 8601 creation timestamp

curl https://api.detris.ai/lists \
  -H "X-API-Key: sk_live_your_api_key_here"

Response

[
  {
    "_id": "692397ea61746762ff5d587e",
    "name": "Enterprise Leads",
    "stats": { "rowCount": 1234 },
    "created_at": "2025-01-15T10:30:00Z"
  }
]

GET/lists/{list_id}

Get list by ID

Retrieve a specific list by its ID. fields_schema lists known column keys; settings.columnTypes holds available display/type hints. Columns are custom, not a fixed contact schema.

Path Parameters

list_idstringrequired

The unique identifier of the list

Response

_idstringrequired

Unique list identifier

namestringrequired

List name

statsobject

List statistics, including rowCount when available

fields_schemaarray

Known custom column keys, including sparse columns

settings.columnTypesobject

Optional column display/type hints, not a required contact schema

created_atstringrequired

ISO 8601 creation timestamp

curl https://api.detris.ai/lists/692397ea61746762ff5d587e \
  -H "X-API-Key: sk_live_your_api_key_here"

Response

{
  "_id": "692397ea61746762ff5d587e",
  "name": "Enterprise Leads",
  "stats": { "rowCount": 1234 },
  "fields_schema": ["email", "firstName", "company"],
  "created_at": "2025-01-15T10:30:00Z"
}

GET/lists/{list_id}/rows

Get rows

Read custom rows from a list. For a complete integration sync, explicitly set use_view_state=false so saved dashboard filters cannot hide rows. updated_since reads changed existing rows, not a deletion feed.

Path Parameters

list_idstringrequired

The unique identifier of the list

Query Parameters

limitinteger

Max rows to return (default: 50, max: 10000)

offsetinteger

Number of rows to skip (default: 0)

sort_bystring

"row_order" or "updated_at"

updated_sincestring

ISO 8601 timestamp for delta sync

use_view_stateboolean

Set false for sync. Ignores saved UI sorting/filtering; explicit query filters still apply. Set true to opt into the saved view.

Response

rowsarrayrequired

Array of row objects (not a top-level data envelope)

_idstringrequired

Unique row identifier

dataobjectrequired

Row field values as key-value pairs

created_atstringrequired

ISO 8601 creation timestamp

updated_atstring

ISO 8601 last update timestamp

totalintegerrequired

Total number of rows in the list

limitintegerrequired

Limit used in the request

offsetintegerrequired

Offset used in the request

essentialColumnsarray

Visible/preferred column keys, not an exhaustive or fixed contact schema

filteredTotalinteger

Matching count when the active view filters rows; total may include hidden rows

curl "https://api.detris.ai/lists/692397ea61746762ff5d587e/rows?limit=100&use_view_state=false" \
  -H "X-API-Key: sk_live_your_api_key_here"

Response

{
  "rows": [
    {
      "_id": "692397ea61746762ff5d587f",
      "data": {
        "email": "[email protected]",
        "firstName": "John",
        "company": "Acme Inc"
      },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 1234,
  "limit": 100,
  "offset": 0
}

POST/lists/{list_id}/rows

Create row

Add a single row. Put all custom column values inside data. A flat body is not supported. An empty data object intentionally creates a blank row.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

dataobjectrequired

Custom column keys and values. email, firstName and company below are examples, not reserved or guaranteed fields.

insertAfterRowIdstring

Optional existing row ID for insertion position

Response

_idstringrequired

Unique row identifier

dataobjectrequired

The row data you provided

created_atstringrequired

ISO 8601 creation timestamp

curl -X POST https://api.detris.ai/lists/692397ea61746762ff5d587e/rows \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "email": "[email protected]",
      "firstName": "John",
      "company": "Acme Inc"
    }
  }'

Response

{
  "_id": "692397ea61746762ff5d587f",
  "data": {
    "email": "[email protected]",
    "firstName": "John",
    "company": "Acme Inc"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

PATCH/lists/{list_id}/rows/batch

Batch update

Patch multiple rows using updates: [{row_id, data}]. Updates may partially succeed; inspect updated and failed, then errors when present. Not an all-or-nothing transaction.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

updatesarrayrequired

Array of update objects

row_idstringrequired

Row ID to update

dataobjectrequired

Key-value pairs of fields to update

Response

updatedintegerrequired

Number of rows successfully updated

failedintegerrequired

Number of rows that failed to update

totalintegerrequired

Total rows in the request

errorsarray

Array of error messages for failed updates

curl -X PATCH https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/batch \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "row_id": "692397ea61746762ff5d587f", "data": { "status": "qualified" } },
      { "row_id": "692397ea61746762ff5d5880", "data": { "status": "contacted" } }
    ]
  }'

Response

{
  "updated": 2,
  "failed": 0,
  "total": 2
}

POST/lists/{list_id}/rows/upsert

Bulk upsert (import)

Import data in bulk or sync from your CRM. Matches rows by a field (like email) - updates existing rows, creates new ones. Perfect for periodic syncs from Salesforce, HubSpot, or your database.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

rowsarrayrequired

Array of row objects to upsert

match_fieldstringrequired

Field name to match on (e.g., "email")

dataobjectrequired

Row data as key-value pairs

Response

insertedintegerrequired

Number of new rows created

updatedintegerrequired

Number of existing rows updated

failedintegerrequired

Number of rows that failed

totalintegerrequired

Total rows in the request

curl -X POST https://api.detris.ai/lists/692397ea61746762ff5d587e/rows/upsert \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "match_field": "email",
        "data": { "email": "[email protected]", "firstName": "John" }
      }
    ]
  }'

Response

{
  "inserted": 150,
  "updated": 850,
  "failed": 0,
  "total": 1000
}

GET/aitemplates/

Get templates

Retrieve all AI templates in your account. Templates define reusable AI prompts for data augmentation.

Response

_idstringrequired

Unique template identifier

namestringrequired

Template name (used as column name)

custom_user_messagestringrequired

The AI prompt with {field} placeholders

modelstring

AI model to use (default: gpt-5.4-mini)

enable_web_searchboolean

Whether web search is enabled

created_atstringrequired

ISO 8601 creation timestamp

curl https://api.detris.ai/aitemplates/ \
  -H "X-API-Key: sk_live_your_api_key_here"

Response

[
  {
    "_id": "template_123",
    "name": "lead_score",
    "custom_user_message": "Rate this lead from 1-10...",
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST/aitemplates/

Create template

Create an AI template for data augmentation. Use {field_name} placeholders to reference row data in your prompt.

Request Body

namestringrequired

Template name (becomes the column name when applied)

custom_user_messagestringrequired

AI prompt with {field} placeholders

modelstring

AI model: gpt-5.4-mini (default), gpt-5.4, gpt-5.4-nano, gpt-5.3-codex, claude-haiku-4.5, etc.

enable_web_searchboolean

Enable web search for each row (adds $0.01/row)

Response

_idstringrequired

Unique template identifier

namestringrequired

Template name

custom_user_messagestringrequired

The AI prompt

created_atstringrequired

ISO 8601 creation timestamp

curl -X POST https://api.detris.ai/aitemplates/ \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lead_score",
    "custom_user_message": "Rate this lead from 1-10: {name} at {company}"
  }'

Response

{
  "_id": "template_123",
  "name": "lead_score",
  "custom_user_message": "Rate this lead from 1-10: {name} at {company}",
  "created_at": "2025-01-15T10:30:00Z"
}