API playground

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.

API referenceDocs

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

REST AUTHENTICATION

X-API-Key: YOUR_API_KEY

Never 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 /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 /companies

Companies, filtered by industry, location and size.

The request
curl "https://api.detris.ai/companies?industries=Software%2FSaaS&page_size=2" \
  -H "X-API-Key: $DETRIS_KEY"
Example 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": 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.

3. Start an agent & follow its progress

Agent · paid action

Start an agent run

POST /agent/run

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

Example response · no request sent
{
  "id": "6a1f2c9e4b7d8e0a11112222",
  "status": "queued"
}
curl 'https://api.detris.ai/agent/run/RUN_ID?rows=10' \
  -H 'X-API-Key: YOUR_API_KEY'