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)
  • Find people: GET /people?q=Dana%20Okafor&companies=Acme
  • Find companies: GET /companies?industries=Software/SaaS
  • Research anything else: POST /agent/run
  • 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

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

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

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.

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_..."
No install needed. Use https://detris.ai/mcp with that header. Start by asking for your lists—a read-only check. Agent runs and generation use your allowance.
Or run it on your machine (adds local SQLite sync)
claude mcp add detris \
  -e DETRIS_API_KEY=sk_live_... \
  -e DETRIS_API_URL=https://api.detris.ai \
  -- npx -y detris-mcp
Requires Node 22.13+.
Search for a person without running AI
curl -G https://api.detris.ai/people \
  -H "X-API-Key: sk_live_..." \
  --data-urlencode "q=Jane Doe" \
  --data-urlencode "companies=Acme" \
  -d count_mode=deferred -d page_size=5
q searches names, titles and companies; companies narrows to the employer. Verify the returned name and employer: full-text matches are candidates, not exact identity matches. Add count_mode=deferred to avoid waiting for an exact total; total: null means not counted, not zero. No model runs. If nobody matches, POST /agent/run can research the web using your AI allowance.
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"
  }'
GET/people

Search people

Search people without AI. Use count_mode=deferred to fetch a page without waiting for an exact total. q is full-text candidate search, not exact identity matching: verify each returned name and employer. Broad exact counts can time out with 503. Starting offset (page - 1) * page_size must be at most 10,000.

Query Parameters

qstring

Full-text over name, title, company and bio. Unquoted words can match separately; quote a phrase when needed. Verify identity from returned fields.

count_modestring

exact (default), deferred (page without waiting for exact count), or only (count without rows). Deferred total may be null, not zero.

companiesstring

Employer names, comma-separated; case-insensitive contains match

titlesstring

Job titles, comma-separated

senioritystring

e.g. c_level,vp,director (one comma-separated value; repeating the key is refused)

locationsstring

Locations, comma-separated

industriesstring

Industries, comma-separated

has_emailboolean

Only people with an email value (not a delivery guarantee)

pageinteger

Page number, from 1

page_sizeinteger

Results per page, max 200

Response

peoplearrayrequired

Matching people

totalinteger | nullrequired

Exact total when available; null means not counted, not zero

has_morebooleanrequired

More pages exist

curl 'https://api.detris.ai/people?q=Dana+Okafor&companies=Acme+Robotics&count_mode=deferred' \
  -H 'X-API-Key: sk_live_your_api_key_here'
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": 50,
  "has_more": false
}
GET/people/filters

Filter values

The most common values for each /people filter. A value missing here can still match. One name differs: the key is seniorities, the /people param is seniority. The others match (titles, companies, locations, industries, departments).

curl 'https://api.detris.ai/people/filters' \
  -H 'X-API-Key: sk_live_your_api_key_here'
Response
{
  "facet_counts_hidden": true,
  "seniorities": [
    {
      "value": "c_level",
      "count": 0
    }
  ],
  "industries": [
    {
      "value": "Software/SaaS",
      "count": 0
    }
  ],
  "titles": [],
  "locations": [],
  "departments": []
}
POST/people/export

Export people to a list

Copy matching people into a new list, or append them to one you name with target_list_id. Uses your export allowance. Send either lead_ids from /people results or a search_query object with the same filters as /people.

Request Body

list_namestringrequired

Name of the list to create

lead_idsarray

id values from /people results

search_queryobject

Same filters as /people, as an object

limitinteger

Maximum people to export

target_list_idstring

Append to this existing list (from an earlier export) instead of creating one

curl -X POST 'https://api.detris.ai/people/export' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
  "list_name": "Acme Robotics — leadership",
  "search_query": {
    "companies": "Acme Robotics",
    "seniority": "c_level,vp"
  },
  "limit": 25
}'
Response
{
  "success": true,
  "list_id": "6a1f2c9e4b7d8e0a12345678",
  "exported_count": 2,
  "remaining_quota": 24586
}
GET/companies

Search companies

Search companies by name, industry, location, size, stage or funding. Every list filter also has an exclude_ form (exclude_industries, exclude_countries, ...). An unknown parameter is refused with 422. Use a result's id with /companies/{company_id}/people.

Query Parameters

qstring

Text search over company name, description and industry

industriesstring

Industries, comma-separated (values from /companies/filters)

countriesstring

Countries, comma-separated

citiesstring

Cities, comma-separated

sizesstring

Size tiers, comma-separated

tagsstring

Company tags, comma-separated; matches any

company_typesstring

private, public, nonprofit, government

company_stagesstring

Business stage, e.g. Startup, Scaling, Established (not a funding round)

company_focus_optionsstring

Customer focus, e.g. B2B, B2C

specialtiesstring

Sub-industries, comma-separated

acceleratorsstring

Y Combinator, Techstars, Creative Destruction Lab, SOSV

funding_scopestring

latest_round (default), any_round (all funding conditions true of the same round) or total

funding_minnumber

Minimum amount in funding_currency

funding_maxnumber

Maximum amount in funding_currency

funding_currencystring

ISO code, default USD. Unknown currency is left out of amount filters

funding_fromstring

Round date on or after, YYYY-MM-DD (not with total)

funding_tostring

Round date on or before, YYYY-MM-DD (not with total)

funding_stagesstring

Round stages, e.g. Seed,Series A (not with total)

funding_investorsstring

Investor names on the round (not with total)

pageinteger

Page number, from 1

page_sizeinteger

Results per page, max 200

curl 'https://api.detris.ai/companies?industries=Software%2FSaaS&countries=Canada' \
  -H 'X-API-Key: sk_live_your_api_key_here'
Response
{
  "companies": [
    {
      "id": "6a1f2c9e4b7d8e0a99990001",
      "company_name": "Acme Robotics",
      "company_website_domain": "acme-robotics.example.com",
      "company_industry": "Software/SaaS",
      "company_size_label": "Medium",
      "company_city": "Toronto",
      "company_country": "Canada"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "has_more": false
}
GET/companies/{company_id}/people

People at a company

Everyone we have at one company.

Path Parameters

company_idstringrequired

id from /companies results

Query Parameters

pageinteger

Page number, from 1

page_sizeinteger

Results per page, max 200

curl 'https://api.detris.ai/companies/6a1f2c9e4b7d8e0a99990001/people' \
  -H 'X-API-Key: sk_live_your_api_key_here'
Response
{
  "company": {
    "id": "6a1f2c9e4b7d8e0a99990001",
    "name": "Acme Robotics",
    "website": "https://acme-robotics.example.com",
    "industry": "Software/SaaS",
    "size": "Medium"
  },
  "people": [
    {
      "id": "6a1f2c9e4b7d8e0a12340001",
      "full_name": "Dana Okafor",
      "job_title": "Chief Technology Officer",
      "seniority": "c_level",
      "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": 50,
  "has_more": false
}
POST/agent/run

Run the agent

Give the agent a task in plain language. It searches Detris, reads the web when it has to, and can build a list. Returns an id at once; a run takes about 30-120 s. At most 10 runs at once per account. Try /people first for a known person.

Request Body

promptstringrequired

The task, in plain language

modelstring

Model to use; defaults to claude-sonnet-5-5 (server default)

max_iterationsinteger

Upper bound on agent steps

curl -X POST 'https://api.detris.ai/agent/run' \
  -H 'X-API-Key: sk_live_your_api_key_here' \
  -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."
}'
Response
{
  "id": "6a1f2c9e4b7d8e0a11112222",
  "status": "queued"
}
GET/agent/run/{id}

Get a run

Poll every few seconds until status is complete. Returns the answer and the rows of any list the run built.

Path Parameters

idstringrequired

id returned by POST /agent/run

Query Parameters

rowsinteger

Rows to include inline per list, max 100

curl 'https://api.detris.ai/agent/run/6a1f2c9e4b7d8e0a11112222?rows=10' \
  -H 'X-API-Key: sk_live_your_api_key_here'
Response
{
  "status": "complete",
  "answer": "Created \"Acme Robotics — senior people\" with 1 row.",
  "lists": [
    {
      "name": "Acme Robotics — senior people",
      "total_rows": 1,
      "link": "https://detris.ai/shared/6a1f2c9e4b7d8e0a12345678"
    }
  ]
}
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, claude-sonnet-4-5

enable_web_searchboolean

Search the web for each row. Needs a Claude model (claude-haiku-4-5 or claude-sonnet-4-5); with a GPT model the request is refused with 400. About $0.01 per search

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": "692397ea61746762ff5d5890",
  "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, claude-sonnet-4-5

enable_web_searchboolean

Search the web for each row. Needs a Claude model (claude-haiku-4-5 or claude-sonnet-4-5); with a GPT model the request is refused with 400. About $0.01 per search

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

llm_parameters.modelstring

AI model the template runs on (default: gpt-5.4-mini)

enable_web_searchboolean

Present when set: whether the template searches the web

updated_atstring

ISO 8601 last update timestamp

curl https://api.detris.ai/aitemplates/ \
  -H "X-API-Key: sk_live_your_api_key_here"
Response
[
  {
    "_id": "692397ea61746762ff5d5891",
    "name": "lead_score",
    "custom_user_message": "Rate this lead from 1-10...",
    "llm_parameters": { "model": "gpt-5.4-mini" },
    "updated_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, claude-sonnet-4-5. Saved as llm_parameters.model

enable_web_searchboolean

Search the web for each row. Needs a Claude model (claude-haiku-4-5 or claude-sonnet-4-5); with a GPT model the request is refused with 400. About $0.01 per search

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": "692397ea61746762ff5d5891",
  "name": "lead_score",
  "custom_user_message": "Rate this lead from 1-10: {name} at {company}",
  "llm_parameters": { "model": "gpt-5.4-mini" },
  "created_at": "2025-01-15T10:30:00Z"
}