DetrisDetris

API Reference

Add AI-generated data to your leads, contacts, or any list. Import data from your CRM and get enriched results back.

Common Workflows

  • Quick start: 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

Authentication

Include your API key in the X-API-Key header.

https://api.detris.ai

Webhooks

Get notified when AI generation completes or data is imported. Configure webhooks in Settings → Webhooks. You can set global webhooks or scope them to specific lists.

Quick Start: 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/augment

Augment with data

The simplest way to use Detris: send your data and an AI prompt in one call. Creates a list, imports rows, and runs AI generation. Perfect for quick integrations.

Request Body

dataarrayrequired

Array of row objects to import (max 50,000 for Free, 200,000 for Plus)

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

Run AI generation on an existing list. Use this when you already have data in Detris and want to add AI-generated columns.

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

dataarrayrequired

Array of list objects

_idstringrequired

Unique list identifier

namestringrequired

List name

rowCountintegerrequired

Number of rows in the list

created_atstringrequired

ISO 8601 creation timestamp

curl https://api.detris.ai/lists \
  -H "X-API-Key: sk_live_your_api_key_here"
Response
{
  "data": [
    {
      "_id": "692397ea61746762ff5d587e",
      "name": "Enterprise Leads",
      "rowCount": 1234,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}
GET/lists/{list_id}

Get list by ID

Retrieve a specific list by its ID.

Path Parameters

list_idstringrequired

The unique identifier of the list

Response

_idstringrequired

Unique list identifier

namestringrequired

List name

rowCountintegerrequired

Number of rows in the list

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",
  "rowCount": 1234,
  "created_at": "2025-01-15T10:30:00Z"
}
GET/lists/{list_id}/rows

Get rows

Export data from a list. Use pagination for large lists, or updated_since for delta sync with your CRM or database.

Path Parameters

list_idstringrequired

The unique identifier of the list

Query Parameters

limitinteger

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

offsetinteger

Number of rows to skip (default: 0)

sort_bystring

"row_order" or "updated_at"

updated_sincestring

ISO 8601 timestamp for delta sync

Response

dataarrayrequired

Array of row objects

_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

curl "https://api.detris.ai/lists/692397ea61746762ff5d587e/rows?limit=100" \
  -H "X-API-Key: sk_live_your_api_key_here"
Response
{
  "data": [
    {
      "_id": "row_123",
      "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 to a list. Use this when a new form is submitted, a new subscriber signs up, or any real-time data entry from your website.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

{field_name}any

Any field name and value. All fields are optional and dynamic.

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 '{
    "email": "[email protected]",
    "firstName": "John",
    "company": "Acme Inc"
  }'
Response
{
  "_id": "row_123",
  "data": {
    "email": "[email protected]",
    "firstName": "John",
    "company": "Acme Inc"
  },
  "created_at": "2025-01-15T10:30:00Z"
}
PATCH/lists/{list_id}/rows/batch

Batch update

Update multiple rows at once. Each update object specifies a row ID and the fields to update.

Path Parameters

list_idstringrequired

The unique identifier of the list

Request Body

updatesarrayrequired

Array of update objects

_idstringrequired

Row ID to update

updatesobjectrequired

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": [
      { "_id": "row_123", "updates": { "status": "qualified" } },
      { "_id": "row_456", "updates": { "status": "contacted" } }
    ]
  }'
Response
{
  "updated": 2,
  "failed": 0,
  "total": 2,
  "errors": []
}
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"
}