Developers / Demo
Try the Detris API
Explore real requests, inspect responses, and run an agent. Start with examples, then connect your own account when you’re ready.
1. Connect your account
Create a key in Settings → API Keys. Examples work without a key; live calls use your account and its limits.
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.
BASE URL
https://api.detris.aiREST AUTHENTICATION
X-API-Key: YOUR_API_KEYNever put a live key in frontend source or a public repository. Clear the key when finished. REST calls use X-API-Key; the separate MCP connection uses its documented bearer header.
2. Search data & inspect your account
These GET requests do not start an AI agent. Searches don’t use an allowance; exports use your export allowance. Click Run with my key to send a request; browsing examples sends nothing.
GET /peoplePeople, filtered, without waiting for an exact total. No model; total:null means not counted.
curl "https://api.detris.ai/people?industries=Software%2FSaaS&page_size=2&count_mode=deferred" \ -H "X-API-Key: $DETRIS_KEY"
{
"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_levelThe thing a bought list cannot do: filter on how senior someone is.
curl "https://api.detris.ai/people?seniority=c_level&industries=Software%2FSaaS&page_size=2&count_mode=deferred" \ -H "X-API-Key: $DETRIS_KEY"
{
"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 /companiesCompanies, filtered by industry, location and size.
curl "https://api.detris.ai/companies?industries=Software%2FSaaS&page_size=2" \ -H "X-API-Key: $DETRIS_KEY"
{
"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": 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.
curl "https://api.detris.ai/people?seniorities=c_level&page_size=2" \ -H "X-API-Key: $DETRIS_KEY"
{
"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/usageExport quota left on your plan.
curl "https://api.detris.ai/api/published-leads/usage" \ -H "X-API-Key: $DETRIS_KEY"
{
"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 /listsYour lists, including anything the agent just built.
curl "https://api.detris.ai/lists" \ -H "X-API-Key: $DETRIS_KEY"
[
{
"_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.
curl "https://api.detris.ai/aitemplates/" \ -H "X-API-Key: $DETRIS_KEY"
[
{
"_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/meThe account behind your key, its plan, and what it has spent.
curl "https://api.detris.ai/users/me" \ -H "X-API-Key: $DETRIS_KEY"
{
"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.
3. Start an agent & follow its progress
Agent · paid action
Start an agent run
POST /agent/runGive Detris a task. This uses your account’s AI allowance and may create or change data if your prompt asks it to. Selecting this section does not run anything.
A step limit is not a dollar cap. This demo allows up to 18 steps. Demo rate limits and your account limits also apply.
Add your API key in Setup to run this example.
Request example · curl
curl -X POST 'https://api.detris.ai/agent/run' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"prompt":"Find up to 3 Canadian software companies in Detris. Return their names and websites. Do not create a list or contact anyone.","max_iterations":6}'Agent · read-only
Check a run
GET /agent/run/{id}Paste a run ID to check progress. Save it before leaving. A slow response doesn’t mean you should start another run.
{
"id": "6a1f2c9e4b7d8e0a11112222",
"status": "queued"
}curl 'https://api.detris.ai/agent/run/RUN_ID?rows=10' \ -H 'X-API-Key: YOUR_API_KEY'