{"service":"Detris API","environment":"production","base_url":"https://api.detris.ai","web_app":"https://detris.ai","environment_note":"DEV credentials and data are separate. Test DEV MCP without a production deployment.","authentication":{"header":"X-API-Key","value":"your key, created at Settings -> API Keys in the web app","example":"curl -H 'X-API-Key: YOUR_KEY' https://api.detris.ai/lists","note":"REST uses X-API-Key. Hosted MCP uses Authorization: Bearer. Do not use an API key as a REST Bearer token.","scope":"Keys keep your resource permissions and workspace limits; treat them like passwords. They grant neither admin access nor other members' private data. Key management and /sandbox require a signed-in session."},"workspaces":{"enabled":true,"default":"Personal","create_key":"Select Personal or a Team, then open Settings -> API Keys.","team_key":"Uses its Team automatically and requires your active paid seat. No Personal subscription needed.","personal_key":"Personal and older keys default to Personal.","header":"X-Detris-Organization","selection":"A Personal key can select a Team you can access. A Team key refuses a different Team header.","sharing":"Team membership does not share lists automatically. Existing resource permissions still apply.","revocation":"Member removal or Team deletion revokes Team-bound keys. Rejoining needs a new key."},"endpoints":[{"group":"Lists and rows","endpoints":[{"method":"GET","path":"/lists","does":"your lists; response is a bare JSON array, not {data:[...]}"},{"method":"POST","path":"/lists","does":"create an empty list without AI generation","body":{"name":"Example list"}},{"method":"GET","path":"/lists/{list_id}","does":"list metadata; fields_schema contains known custom column keys"},{"method":"GET","path":"/lists/{list_id}/rows","does":"rows in a list","response":"{rows:[{_id,data,...}],total,offset,limit,essentialColumns}","sync":"Send use_view_state=false for sync, so saved dashboard filters cannot hide rows. limit defaults to 50, max 10000; offset pagination is not a snapshot. updated_since returns changed existing rows, not deleted-row events.","fields":"data keys are custom per list. email/firstName/company are examples, not required fields. essentialColumns is a visible/preferred subset; use fields_schema and row data for mapping."},{"method":"POST","path":"/lists/{list_id}/rows","does":"create one row","body":{"data":{"email":"person@example.com"}},"note":"Field values must be inside data; do not send a flat body."},{"method":"GET","path":"/lists/{list_id}/rows/{row_id}","does":"read one row; response is the row object directly"},{"method":"PATCH","path":"/lists/{list_id}/rows/{row_id}","does":"merge supplied row fields; omitted fields stay unchanged","body":{"data":{"title":"CEO"}},"note":"PATCH, not PUT; requires edit access."},{"method":"DELETE","path":"/lists/{list_id}/rows/{row_id}","does":"permanently delete one row; requires edit access"},{"method":"PATCH","path":"/lists/{list_id}/rows/batch","does":"update multiple rows; may partially succeed","body":{"updates":[{"row_id":"692397ea61746762ff5d587f","data":{"title":"CEO"}}]},"note":"Inspect updated, failed and errors when present. Not an all-or-nothing transaction."},{"method":"POST","path":"/lists/{list_id}/rows/bulk-delete","does":"permanently delete specified rows; inspect deleted_count vs requested_count","body":{"row_ids":["692397ea61746762ff5d587f"]}}]},{"group":"People and companies","endpoints":[{"method":"GET","path":"/people","does":"search people; response {people:[...], total, page, page_size, has_more}","find_one_person":"q=<full name>&companies=<employer>&count_mode=deferred. No model. q is full-text over name, job title, company and bio, not exact identity matching: unquoted words can match separately. Inspect full_name and employer in each result; quote a phrase when appropriate. companies is a case-insensitive contains match. Try this before /agent/run.","same_as":"/api/published-leads/search (older name; returns the list under leads)","params":"is_decision_maker, departments, seniority, locations, industries, company_sizes, estimated_headcounts, has_email, has_website, titles, companies, person_tags, min_activity_score, company_specialties, company_stages, company_focus, company_tags, company_target_markets, company_revenue_ranges, accelerators, q, match_mode, exclude_* for most, page, page_size, count_mode","repeated_params":"Pass multiple values as ONE comma-separated param (seniority=vp,c_level). Repeating a query key is rejected with 422 repeated_query_parameter. Python requests with a list value repeats keys; join the values with commas instead.","totals":"count_mode=deferred returns the page without waiting for an exact count; total can be null (unknown, not zero). Use has_more to decide whether to request another page. The default exact count can return 503 LEAD_SEARCH_TIMEOUT on broad filters. count_mode=only requests a count without rows and can also time out.","limits":"page_size max 200; the starting offset (page-1)*page_size must be at most 10,000. Narrow the filter rather than paging past it.","quality":"has_email means a value exists, not that it delivers. The field is email_validation_status; mx_valid and smtp_valid are VALUES of it, not fields of their own. Most rows are not_provided.","unknown_params":"422 naming the closest real parameter, on this endpoint and the two /companies ones. Elsewhere unknown params are ignored."},{"method":"GET","path":"/companies","does":"search companies; response {companies:[...], total, page, page_size, has_more}","params":"q, industries, countries, cities, sizes, tags, company_types, company_stages, company_focus_options, specialties, accelerators, exclude_* for each, funding_scope, funding_min, funding_max, funding_currency, funding_from, funding_to, funding_stages, funding_investors, page, page_size (max 200)","funding":"funding_scope is latest_round (default), any_round (amount, date, stage and investor all true of the SAME round) or total (amount bounds only). Dates are YYYY-MM-DD; funding_currency defaults to USD. Unknown funding is missing, not zero, and is left out of amount filters."},{"method":"GET","path":"/companies/{company_id}/people","does":"people at one company; response {people:[...], total, ...}. company_id comes from /companies results"},{"method":"GET","path":"/people/filters","does":"top filter values (option frequencies are hidden)","note":"Top values, not all — a value missing from facets can still match. One name differs: the facet is seniorities, the param is seniority. The others match (titles, companies, locations, industries, departments). facet_counts_hidden=true: option count=0 is a temporary legacy-browser placeholder (0 = hidden, not zero), NOT a measured zero. Ignore it; never report it as inventory. Search totals and firmographic_coverage are unchanged."},{"method":"GET","path":"/people/filters/locations","does":"ranked location labels with country/state/city types","note":"facet_counts_hidden=true; numeric count=0 is only a legacy-browser placeholder (0 = hidden, not zero), NOT a measured zero. Do not interpret it as inventory."},{"method":"GET","path":"/companies/filters","does":"ranked company filter labels (option frequencies are hidden)","note":"facet_counts_hidden=true; numeric count=0 is only a legacy-browser placeholder (0 = hidden, not zero), NOT a measured zero. Do not interpret it as inventory."},{"method":"POST","path":"/people/export","does":"export matching people into one of your lists","body_differs_from_search":"Takes list_name (a string, not list_id) plus either lead_ids or a search_query OBJECT holding the same filters you would pass to /search. Flat params are rejected.","quota":"Consumes your export allowance; read remaining_quota in the response."},{"method":"GET","path":"/api/published-leads/usage","does":"export quota left"}]},{"group":"Agent","endpoints":[{"method":"POST","path":"/agent/run","does":"run the Detris agent on a plain-language task (web research, the corpus, lists). Returns an id at once; the run takes about 30-120 s.","params":"prompt, model, max_iterations","when":"for what search cannot answer. Look up known people with /people first. Keep a handful of runs in flight, not dozens: each one is a full agent.","limit":"At most 10 runs in flight per account. More gets 429 too_many_runs with Retry-After: wait for one to finish, then send again."},{"method":"GET","path":"/agent/run/{id}","does":"status, answer and any lists the run built. Poll every few seconds; a slow run is still running, so poll the same id rather than starting another."}]},{"group":"AI templates","endpoints":[{"method":"GET","path":"/aitemplates/","does":"your templates; the model is llm_parameters.model"},{"method":"POST","path":"/lists/{list_id}/augment","does":"add an AI column to a whole list (or row_ids) from a prompt","body":{"prompt":"Score 1-10: {name} at {company}","ai_column":"lead_score"},"note":"Runs in the background; returns rows_queued at once. enable_web_search needs a Claude model (claude-haiku-4-5 or claude-sonnet-4-5)."},{"method":"POST","path":"/augment","does":"create a list from data rows and add an AI column, in one call","body":{"data":[{"name":"Jane","company":"Acme"}],"prompt":"...","ai_column":"lead_score","list_name":"Leads"}},{"method":"POST","path":"/lists/{list_id}/bulk-generate/","does":"run one of your saved templates on many rows","body":{"template_id":"<from GET /aitemplates/>","row_ids":["<from GET /lists/{list_id}/row-ids>"]}},{"method":"POST","path":"/lists/{list_id}/rows/{row_id}/generate/{template_id}","does":"run one template on ONE row"}]},{"group":"Loops","endpoints":[{"method":"POST","path":"/loops","does":"start a scheduled agent run","models":{"claude":"claude-sonnet-5-5","gpt":"gpt-6.1-sol"},"model_policy":"Scheduled loops use these models. Other Claude/GPT model IDs map to their family’s loop model.","budget":"Optional budget.maxIterationsPerRun limits iterations. Explicit budget.maxSpendPerRun is rejected with 422: per-run dollar caps are not supported yet; your weekly AI allowance applies."}]},{"group":"Integrations","endpoints":[{"method":"GET","path":"/api/integrations/email/status","does":"Gmail connection status for your account"},{"method":"GET","path":"/api/integrations/hubspot/status","does":"HubSpot connection status; when connected, reads provider account limits"},{"method":"GET","path":"/api/integrations/phantombuster/status","does":"PhantomBuster connection status without the provider key"}]},{"group":"Account","endpoints":[{"method":"GET","path":"/users/me","does":"your account and plan"}]}],"mcp":{"what":"An MCP server that gives an AI agent these capabilities as tools.","hosted":"https://detris.ai/mcp (Streamable HTTP; send the key as Authorization: Bearer)","claude_code_hosted":"claude mcp add --transport http detris https://detris.ai/mcp --header \"Authorization: Bearer YOUR_KEY\"","install":"npx -y detris-mcp (local; also offers SQLite sync to your machine)","package":"https://www.npmjs.com/package/detris-mcp","env":{"DETRIS_API_KEY":"key from the selected workspace on this environment","DETRIS_API_URL":"https://api.detris.ai"},"claude_code":"claude mcp add detris -e DETRIS_API_KEY=YOUR_KEY -e DETRIS_API_URL=https://api.detris.ai -- npx -y detris-mcp","note":"Paid-research, Gmail bulk send and PhantomBuster tools are held from the default surface. See the package README.","first_check":"List your lists: read-only, no agent run. Agent runs and generation use your allowance."},"limits":{"per_tier":{"free":{"requests_per_minute":20,"requests_per_month":5000,"rows_per_month":5000,"max_bulk_rows":50000,"metered_tool_spend_usd_per_period":5.0},"plus":{"requests_per_minute":200,"requests_per_month":"unlimited","rows_per_month":"unlimited","max_bulk_rows":200000,"metered_tool_spend_usd_per_period":25.0},"premium":{"requests_per_minute":500,"requests_per_month":"unlimited","rows_per_month":"unlimited","max_bulk_rows":1000000,"metered_tool_spend_usd_per_period":50.0},"pro":{"requests_per_minute":500,"requests_per_month":"unlimited","rows_per_month":"unlimited","max_bulk_rows":1000000,"metered_tool_spend_usd_per_period":100.0}},"note":"Read live from the same table the middleware enforces, so this cannot drift from what is actually applied. GET /users/me for your own tier."},"errors":{"400":"Invalid workspace header. Send one non-empty X-Detris-Organization value with a valid Team ID.","401":"Missing or invalid credential. REST needs X-API-Key; hosted MCP needs Bearer.","402":"A paid Personal plan or active paid Team seat is required for the selected workspace.","403":"Revoked/expired key, permission, plan or quota refusal. Read detail before retrying.","404":"Resource or workspace unavailable, conflicting Team selector, or session-only route. /sandbox cannot be reached with an API key; do not retry it with another key.","422":"Unprocessable; inspect the body. detail.error == 'unknown_query_parameter' means you sent a filter this endpoint does not have -- read detail.did_you_mean for the closest real name and detail.accepted for the full list. repeated_query_parameter means a query key appeared more than once; send one comma-separated value. Other failures include type validation (page_size above 200, a non-boolean has_email).","429":"Rate limited. See limits above.","502":"Upstream/gateway failure; a restart is one possible cause, not proof. Retry safe reads with bounded backoff. For a write, send, export or generation, the outcome may be unknown: read back its operation/resource before retrying. Do not automatically replay a non-idempotent action.","503":"Temporarily unavailable. LEAD_SEARCH_TIMEOUT means an exact search/count exceeded its time budget; narrow filters or use count_mode=deferred for a page without an exact total. A null total is not zero. Read-only retries should be bounded; do not replay ambiguous writes."}}