extruct-api

# Extruct API Use `<extruct_api_cli>` for supported Extruct operations. Do not construct raw HTTP requests for operations the CLI already supports. Extruct AI is a company discovery and research platform for finding, enriching, and evaluating companies. Its core workflows are semantic search, lookalike search, and Deep Search for company discovery, plus AI Tables for repeatable company and people enrichment, scoring, and contact-finding workflows. ## Source Of Truth Use the bundled CLI and the instructions in this skill as the default path. When behavior is unclear, when the user asks for a capability that may not be covered here, or when the request may depend on recently changed API behavior, consult the official Extruct API reference as the source of truth: - https://www.extruct.ai/docs/api-reference/introduction Decision rule: - if the CLI already supports the operation, use the CLI - if the CLI does not cover the operation or the documented behavior here conflicts with the live API, defer to the official API docs ## Resolve The Bundled CLI First `<extruct_api_cli>` means the absolute path to the bundled CLI script for this skill. - Resolve it from the directory that contains this `SKILL.md`. - In shell or Bash tool calls, prefer the resolved absolute path, not `scripts/extruct-api` relative to the workspace root. - All command examples below use `<extruct_api_cli>` as shorthand for that resolved absolute path. Example: ```bash /absolute/path/to/skills/extruct-api/scripts/extruct-api auth user ``` ## Core Workflow This section covers the default operating intent of the skill: identify the Extruct object the user is working with, choose the right execution path, inspect before mutating, and use the CLI to carry the task through to completion. 1. Resolve `<extruct_api_cli>` first, then establish account and billing context. Before the first authenticated CLI call in a conversation, run `<extruct_api_cli> auth user` to get the user and subscription snapshot. If it fails, run `<extruct_api_cli> healthcheck` to distinguish credential problems from connectivity issues. 2. Classify the request into the right Extruct path: - if the user provides an Extruct table URL or a raw table UUID, treat it as an existing table operation first - if the user provides an Extruct task URL or a raw task UUID, treat it as an existing Deep Search task first - known company lookup: fetch the canonical company profile for one domain or UUID - company discovery: semantic search, lookalike search, or Deep Search - research report: Deep Research for a deep, cited report on one target — a company, a person, or a team - existing table operation: inspect, add/update rows or columns, run, poll, read - company-table workflow: enrich or score companies in a reusable table - people workflow: find people at companies or enrich existing people rows 3. If the user already has a table or task, inspect it before mutating it. Default inspection is `tables get`, `columns list`, and a small `tables data` page. On `company` tables, inspect `company_profile` on the first read before adding standard company-fact columns. When you only need a surgical read, add `--columns` on the first `tables data` call instead of fetching the full row payload. 4. Start from the inline command and payload examples in this file. If a payload spans more than a few lines, prefer `--payload-file`. Read `references/column-guide.md` before designing or changing columns. 5. Carry async work through to completion with `tables poll` or `deep-search poll`, then summarize the final result or API error in plain language, including IDs, counts, and the next relevant object when it matters. If any request shape, field name, response contract, or endpoint capability is uncertain while executing this workflow, re-check the official API reference before proceeding: - https://www.extruct.ai/docs/api-reference/introduction ## Plan Access Preflight For Pro-Only Actions Deep Search mutations and table mutations are Pro-gated unless bypassed by manual or organization access. Before the first Pro-only action in a conversation, run: ```bash <extruct_api_cli> auth user ``` Use the response fields: - `subscription.requires_subscription` - `subscription.plan_tier` - `user.organization_id` - `user.organization_is_active` Treat access as allowed if any of these conditions is true: - `subscription.requires_subscription == false` - `subscription.plan_tier` is `pro` or `legacy` - `user.organization_id` is present and `user.organization_is_active == true` If none of those conditions is true, stop before running Pro-only commands and tell the user the feature requires Pro. Pro-only actions in this skill: - Deep Search mutations: `deep-search create`, `deep-search resume`, `deep-search pause` - Deep Research mutations: `deep-research create` - Table mutations: `tables create`, `tables update`, `tables delete`, `tables clone`, `tables run`, `rows create`, `rows update`, `rows delete`, `columns add`, `columns update`, `columns delete` ## Resolve Extruct Identifiers Users may provide Extruct objects as raw IDs or as dashboard URLs. Interpret them as follows: - if the user provides an Extruct table URL such as `https://app.extruct.ai/tables/<table_id>` or `http://app.extruct.ai/tables/<table_id>`, treat the path segment after `/tables/` as the table id - if the user provides an Extruct task URL such as `https://app.extruct.ai/tasks/<task_id>` or `http://app.extruct.ai/tasks/<task_id>`, treat the path segment after `/tasks/` as the Deep Search task id - if the URL includes extra path segments, query params, or fragments, still extract the id from the `/tables/<table_id>` or `/tasks/<task_id>` segment - if the user provides a raw table UUID, use it directly as the table id - if the user provides a raw task UUID, use it directly as the task id - do not ask the user to restate an id that is already present in the URL - when a table URL is present, default to the existing-table workflow unless the user explicitly asks for a new table or a search workflow - when a task URL is present, default to the Deep Search task workflow unless the user explicitly asks to start a new search task Example: User request: ```text Add a funding column to http://app.extruct.ai/tables/0a1a669a-9a40-497c-bb00-d49dd8ee5b74 ``` Resulting table id: ```text 0a1a669a-9a40-497c-bb00-d49dd8ee5b74 ``` First CLI reads: ```bash <extruct_api_cli> tables get 0a1a669a-9a40-497c-bb00-d49dd8ee5b74 <extruct_api_cli> columns list 0a1a669a-9a40-497c-bb00-d49dd8ee5b74 <extruct_api_cli> tables data 0a1a669a-9a40-497c-bb00-d49dd8ee5b74 --limit 20 --offset 0 ``` User request: ```text Check results for https://app.extruct.ai/tasks/d530c3ad-626c-4d7b-ab15-181d4058e4f8 ``` Resulting task id: ```text d530c3ad-626c-4d7b-ab15-181d4058e4f8 ``` First CLI reads: ```bash <extruct_api_cli> deep-search get d530c3ad-626c-4d7b-ab15-181d4058e4f8 <extruct_api_cli> deep-search results d530c3ad-626c-4d7b-ab15-181d4058e4f8 --limit 20 --offset 0 ``` ## Choose The Right Company-Finding Path ### Semantic Search Use semantic search when the user describes a market, ICP, category, product, or use case in natural language. Typical asks: - "search Extruct for AI procurement startups" - "find German fintech companies in Extruct" - "show me B2B treasury automation companies" Commands: ```bash <extruct_api_cli> companies search --query "vertical SaaS for logistics procurement" --limit 20 <extruct_api_cli> companies search --query "enterprise sales AI" \ --filters '{"include":{"country":["United States"]},"range":{"founded":{"min":2018}}}' \ --offset 20 --limit 20 ``` Use `--filters` when the user specifies geography, city, company size, or founded range. Pass a JSON object like one of these as the `--filters` value. ```json { "include": { "country": ["United States"], "size": ["51-200", "201-500"] } } ``` ```json { "range": { "founded": { "min": 2018, "max": 2024 } } } ``` **Result limits and paging.** A single request returns at most 250 results (the page size); read deeper by holding `--limit` near 250 and walking `--offset` in steps. Paid plans (Starter, Pro) can page through up to 2,000 results per query; the free tier is capped at 25. To assemble a full list, keep paging until you reach the plan ceiling or a page returns fewer rows than `--limit`. If search filters or pagination behavior appear different from the guidance here, verify current request and response details in the official API reference before guessing. ### Lookalike Search Use lookalike search when the user already has a reference company and wants similar companies. Prefer domains for `--company-identifier` unless a prior Extruct response already gives you a UUID. Typical asks: - "find companies similar to Stripe in Extruct" - "lookalike search from ramp.com" Commands: ```bash <extruct_api_cli> companies similar --company-identifier extruct.ai --limit 20 <extruct_api_cli> companies similar --company-identifier stripe.com \ --filters '{"include":{"country":["United Kingdom"]}}' ``` Pagination uses the same `--offset` and `--limit` behavior as semantic search. If identifier handling is unclear for a specific seed company or the live API behavior differs, verify the current lookalike-search request contract in the official API reference. ### Company Lookup Use company lookup when the user has one known company and wants its full canonical Extruct company profile. This is not a discovery tool. Use lookup for: - "pull up Stripe's profile" - "get the Extruct profile for ramp.com" - "fetch details for this company profile UUID" Do not use lookup when: - the user describes a category or market — use semantic search - the user asks for similar companies — use lookalike search - the user wants a scored shortlist — use Deep Search Command: ```bash <extruct_api_cli> companies lookup --company-identifier stripe.com ``` `--company-identifier` accepts a domain or Extruct company profile UUID. A ready profile response returns `id`, `domain`, `company_name`, and the rich company profile in `context`. If Extruct accepts the lookup and starts enrichment, the response has `status: "enriching"`, `domain`, and `message`; retry the same lookup later. Company lookup currently consumes 0 credits, but successful and accepted lookups may appear in usage analytics. ### Deep Search Use Deep Search when the user wants a higher-precision asynchronous company search, wants explicit criteria, or is comfortable waiting for a task. Deep Search mutations (`create`, `resume`, `pause`) are Pro-gated. Run the plan-access preflight before those commands. Typical asks: - "run Deep Search for B2B revenue intelligence vendors" - "find high-conviction AI procurement startups and show me the first result" Create a task: ```bash <extruct_api_cli> deep-search create --payload '{"query":"AI procurement startups serving enterprise finance teams","desired_num_results":25}' ``` Create a task with explicit criteria: ```bash <extruct_api_cli> deep-search create --payload-file criteria.json ``` `criteria.json`: ```json { "query": "vertical SaaS companies serving freight forwarding", "desired_num_results": 25, "criteria": [ { "key": "has_logistics_focus", "name": "Logistics Focus", "criterion": "Company serves freight forwarding or logistics operations." }, { "key": "b2b_fit", "name": "B2B Fit", "criterion": "Company sells primarily to business buyers." } ] } ``` Inspect, poll, read results, or request more: ```bash <extruct_api_cli> deep-search list --limit 20 <extruct_api_cli> deep-search get <task_id> <extruct_api_cli> deep-search poll <task_id> <extruct_api_cli> deep-search results <task_id> --limit 20 --offset 0 <extruct_api_cli> deep-search resume <task_id> --payload '{"desired_new_results":25}' ``` Deep Search pipeline: A task progresses through four stages, each tracked by a counter on the task object: 1. **Discovery** (`num_results_discovered`) — candidates are gathered from data sources 2. **Enrichment** (`num_results_enriched`) — candidates are filtered for relevance and enhanced with company profiles 3. **Evaluation** (`num_results_evaluated`) — enriched candidates are scored against criteria 4. **Qualification** (`num_results`) — evaluated candidates that meet the fit threshold become final results `is_exhausted` means the candidate pool is depleted (enrichment has caught up with discovery). It does **not** mean the task is done — evaluation and qualification continue after `is_exhausted` becomes true. A task can be `is_exhausted: true` + `status: "in_progress"` for a significant period while the remaining candidates are scored. `status` is the only reliable completion indicator: - `done` — task completed successfully - `failed` — task did not complete (inspect error details) `deep-search poll` blocks until `status` reaches `done` or `failed`. Deep Search notes: - `deep-search results` can be read while the task is still running - `is_exhausted: true` means resume will fail (no more candidates to discover) — to get more results, create a new task - if the user wants follow-on enrichment, move shortlisted domains into a company table - if the payload spans more than a few lines or includes `criteria`, prefer `--payload-file` over inline `--payload` If Deep Search payload fields, task states, or resume behavior are unclear, verify them against the official API reference before constructing raw fallback requests. Read `references/finding-companies.md` when the task is a fuller company-discovery workflow instead of a single search command. ### Deep Research Use Deep Research when the user wants a deep, cited report on one research target — a company, a person, or a team: account planning, buyer research, researching a lead before outreach, initiative summaries, diligence. For discovering many companies, use Deep Search; for repeatable enrichment across a list, use tables. `deep-research create` is Pro-gated. Run the plan-access preflight before it. Typical asks: - "research Shell for me: buying centers, initiatives, sales angles" - "build an account plan brief for Stripe" - "research this lead and the team they work with before my call" - "do diligence on this company and give me a sourced report" Write the brief as a detailed paragraph, not a one-liner. Pack in everything you know from the conversation: what the user sells or researches, who the target buyer is, what decision the report supports, constraints, and time windows. The more context and specifics the brief carries, the better the report. If the user's ask is thin, ask one or two clarifying questions before creating the task. Create a task (markdown report): ```bash <extruct_api_cli> deep-research create --payload '{"brief":"We sell a cloud cost-optimization platform to large enterprises; typical buyers are VPs of Infrastructure and FinOps leads. I am preparing outreach to Shell. Research how Shell'"'"'s IT and digital organization is structured, who owns cloud infrastructure and FinOps decisions, which cloud, data, or efficiency initiatives they announced in the last 18 months, and which vendors or system integrators they already work with. I want practical conversation angles tied to live initiatives, plus any signals of cost-cutting programs or budget pressure.","depth":"medium"}' ``` People are first-class targets — include the user's own context and the profile to research: ```bash <extruct_api_cli> deep-research create --payload '{"brief":"Here is my company: example.com. We sell AI-powered sales-enablement software to mid-market B2B teams. Research this person and the team they work with: https://www.linkedin.com/in/example-profile. I want their role and scope, what their team owns, recent initiatives or public statements, tools they already use, and the best angle to open a conversation.","depth":"medium"}' ``` Create a task with structured output (`--payload-file` preferred for schemas): ```bash <extruct_api_cli> deep-research create --payload-file research.json ``` `research.json`: ```json { "brief": "We provide fraud-prevention APIs for fintech platforms and are building an account plan for Stripe. Summarize Stripe's enterprise product initiatives from the last 12 months (payments, billing, risk, AI), identify concrete product or partnership angles where a fraud-prevention vendor could plug in, and flag risks that could stall a deal, such as in-house solutions, recent vendor consolidation, or compliance constraints.", "depth": "high", "output_schema": { "type": "object", "properties": { "summary": {"type": "string"}, "recommended_angles": {"type": "array", "items": {"type": "string"}}, "risks": {"type": "array", "items": {"type": "string"}} }, "required": ["summary", "recommended_angles", "risks"] } } ``` Inspect, list, and wait for completion: ```bash <extruct_api_cli> deep-research list --limit 20 <extruct_api_cli> deep-research get <task_id> <extruct_api_cli> deep-research poll <task_id> ``` Depth and billing: - `depth` sets the research-agent budget: `medium` = 25, `high` = 50, `xhigh` = 75. - Creating a task requires the full budget in available credits; the user is billed only for agents that actually run (1 credit each). Failed tasks refund all charges. - If create returns `insufficient_credits` with `required_credits`/`available_credits`, a lower depth may still fit — offer it. Reading the result: