Tulina

Abort a running actor — stops the billing.

Fetch one actor's card: builds, versions and defaultRunOptions (default memory and timeout).

Read it before a first run to size memory_mbytes/timeout_secs. The actor's INPUT fields are documented on its Store page, not here.

List the actors of THIS account (not the public Store).

Read the results a run produced.

Returns: the LIST of items.

Businesses on Google Maps for a search in an area — name, address, phone, website, category, rating, review count, opening hours. compass/crawler-google-places.

For a quick look, serper_maps_sample is cheaper; use this one for full place records or a whole city/region (it splits big areas for you).

Returns — the LIST of places (or {error, run_id, status, items}).

Google Maps reviews of given places — text, rating, date, owner reply. compass/Google-Maps-Reviews-Scraper.

Returns — the LIST of reviews (or {error, run_id, status, items}).

Live job postings from Indeed — title, company, location, salary, date, description. Very cheap per job. valig/indeed-jobs-scraper.

Returns — the LIST of jobs (or {error, run_id, status, items}).

LinkedIn company pages — description, website, industry, headcount, locations, followers — from their URLs, or found by company name.

Also how you find a company's LinkedIn URL from its name. A name search returns the best match, which can be a namesake: check the returned website against the company's domain. harvestapi/linkedin-company.

Returns — the LIST of company pages (or {error, run_id, status, items}).

The people working at a company, from its LinkedIn page — with filters on title and location. No LinkedIn login needed.

Use it when Apollo / AI Ark miss people (small companies, non-US, recent hires): titles come straight from LinkedIn and are often fresher. harvestapi/linkedin-company-employees.

Keep only rows whose currentPosition[0].companyUniversalName is the target: LinkedIn search can return people from namesakes.

Returns — the LIST of employee profiles (or {error, run_id, status, items}).

Live job postings from LinkedIn Jobs — title, company, location, date, description, applicants, the job poster and company details. curious_coder/linkedin-jobs-scraper.

Hiring signals: who recruits for which role, where, since when. For structured, deduplicated postings across boards, try theirstack_jobs_search first.

Returns — the LIST of jobs (or {error, run_id, status, items}).

LinkedIn posts matching a search, or published by given people or companies — text, author, date, reactions and comment counts. No LinkedIn login needed. harvestapi/linkedin-post-search.

Benchmark what performs on a topic, watch what a competitor or a prospect posts, or find who talks about a subject.

Returns — the LIST of posts (or {error, run_id, status, items}).

Full LinkedIn profiles from their URLs — current title and company, experience, education, skills, location. No LinkedIn login needed.

harvestapi/linkedin-profile-scraper: check one person's current job, or refresh the titles of a list. About $4 per 1,000 profiles, $10 with the email search.

Returns — the LIST of profiles, one per URL found (or {error, run_id, status, items} for a run that did not succeed — billed too).

Start an actor WITHOUT waiting for it — for scrapes longer than 300 s.

Returns — {data: {id, status, defaultDatasetId, …}} — keep id for apify_run_status and defaultDatasetId for apify_dataset_items.

Check a run: status (READY, RUNNING, SUCCEEDED, FAILED, TIMED-OUT, ABORTED), defaultDatasetId (where the output is) and usageTotalUsd (what it cost so far).

Run an actor and return its results in one call. Waits up to 300 s.

The normal path for a bounded scrape. A run still going after 300 s is NOT stopped: the error names its run id — continue with apify_run_status then apify_dataset_items. For a scrape you know is long, use apify_run.

Returns: the LIST of dataset items — or, for a run that ended FAILED, TIMED-OUT or ABORTED, {error, run_id, status, items} (that run is billed too).

Search Apify's public Store for an actor that already scrapes your target.

Start here: naming a target ("google maps reviews", "linkedin company", "amazon products") is how you find the actor to run, along with its pricing and its identifier.

Returns — {data: {items: [{id, username, name, title, description, stats, pricingInfos, …}], total}}. Run it with username/name.

Contact details published on company websites — emails, phones, and LinkedIn / Facebook / Instagram / X / YouTube links. One merged row per site. vdrmota/contact-info-scraper.

Find a company's LinkedIn page or generic email from its website. ~$0.30 for 50 sites with the defaults. More than ~30 sites can exceed the 300 s wait: the run keeps going, pick it up with apify_run_status then apify_dataset_items (the error names the run).

Returns — the LIST of sites with emails, phones, linkedIns… (or {error, run_id, status, items}).

Crawl a website and return the text of its pages as Markdown — for reading a whole site (docs, product pages, a blog), not one page. apify/website-content-crawler.

One page only? web_read is free and faster.

Returns — the LIST of pages with url, markdown, metadata (or {error, run_id, status, items}).

Live job postings from Welcome to the Jungle (France and Europe) — title, company, contract, remote policy, salary, full description. bebity/welcome-to-the-jungle-jobs-scraper.

Returns — the LIST of jobs (or {error, run_id, status, items}).

⚠️ ACTS at Apollo, in the key owner's name: send_email sends a one-off email prepared by apollo_email(op="draft") — IRREVERSIBLE, it reaches a real person. Preparing, following and reading emails is apollo_email.

Enrich UP TO 10 companies in a single call — same fields as apollo_enrich_organization (headcount, per-department split, growth, revenue).

Costs 1 Apollo credit per company (a batch saves CALLS, not credits: the enrich rate limit is 600/h, so batching divides your call budget by 10). Over 10 domains, split into batches yourself — the API refuses more.

Match UP TO 10 people in one call — the way a list actually gets built.

apollo_search_people returns hundreds of people with obfuscated last names and no email. This is how you resolve them: 10 per call instead of one, so 300 people cost 30 calls, not 300.

⚠️ A LOT DOES NOT SAVE CREDITS — Apollo bills PER PERSON, exactly as if you had called apollo_match_person ten times. What it saves is calls, and the rate limit that comes with them. Ask only for the reveals you need.

matches comes back one entry PER PERSON, in the order you sent them, with null where nothing matched. An entry carrying _stub: true is an empty record Apollo minted and CHARGED for — count it as a failure, not as data.

Each match drops employment_history, the Apollo CRM account record and the employer's heaviest blocks by default — a lot of 10 overflowed MCP output limits. projection names them; full=True returns everything.

⚠️ Phone numbers are not in this response: with reveal_phone_number Apollo delivers them to oto minutes later and hands back a request_id — pass it to apollo_reveal_phone_result. Either reveal needs your own Apollo key; a plain match works on the shared one.

Read and edit a CONTACT — a person saved in YOUR Apollo workspace, with the values your team wrote on them. BYO key only, all three ops, and all three cost 0 Apollo credits.

⚠️ A CONTACT IS NOT A PERSON, AND THE TWO IDS ARE DIFFERENT OBJECTS. apollo_search_people returns PERSON ids, which every op here REJECTS. Two things hand you a real contact id: apollo_match_person, nested at person.contact.id — present once that person is a contact of your workspace, and free because you already paid for the match — and op="search" below. Never pass a person id: it fails, it does not fall back.

⚠️ op="get" IS THE CHEAP WAY TO READ SOMEONE BACK. apollo_match_person costs a credit and returns the SHARED record — not your team's stage, owner, lists or custom values. To re-read a contact you already own, use this.

⚠️ CUSTOM FIELDS ARE KEYED BY ID, NEVER BY NAME. typed_custom_fields looks like {"60c39ed82bd02f01154c470a": "2026-08-07"} — call op="fields" FIRST to get the ids. Ids are validated against your team's catalogue before the write, and an unknown one is refused with the valid ids named.

⚠️ FOR A PICKLIST FIELD, THE VALUE IS THE OPTION'S ID, NOT ITS LABEL. op="fields" returns picklist_values for those — send picklist_values[].id. Sending the human label is the one mistake Apollo swallows silently.

⚠️ A NEW FIELD MEANT TO HOLD A SENTENCE MUST BE field_type="textarea". string is length-capped (120 characters by default) and Apollo truncates past it without complaining — a personalised opener would arrive cut mid-word.

⚠️ THE THREE ENDPOINTS NEED AN APOLLO MASTER API KEY (or the matching scope) and answer 403 otherwise. When op="fields" cannot be read, op="update" still writes — but it says so in field_validation, it never pretends the ids were checked.

⚠️ label_names REPLACES list membership instead of adding to it — sending one list removes the contact from every other. Every other field is a true PATCH: what you omit is left untouched.

Args by op:

• fields: the custom field definitions of your team — id (the bare id the write expects), name, type, modality and, for picklists, picklist_values. modality filters which object's fields you get (default "contact"; "account", "opportunity", or "all" for every object). full=True returns the raw catalogue instead of the projected one.

• create_field: declare a NEW custom field — the API equivalent of Apollo's Settings → Custom Fields, for when you have no access to that UI. label (required), field_type (string, textarea, number, date, datetime, boolean), max_length, modality. Returns the field with its id, ready to use as a typed_custom_fields key. dry_run=True echoes without creating. A SETUP gesture — run it once per field, not per lead.

• search: find the contact ids you need. q_keywords (name, title, employer or email), contact_stage_ids, contact_label_ids, sort_by_field (contact_last_activity_date, contact_email_last_opened_at, contact_email_last_clicked_at, contact_created_at, contact_updated_at) + sort_ascending, per_page (Apollo caps at 100), page (Apollo stops at 500 pages — past 50 000 records, filter instead of paging). Searches YOUR saved contacts only, never Apollo's database.

• get: contact_id (required). Returns the contact and its labels.

• update: contact_id (required) + at least one field among typed_custom_fields, first_name, last_name, title, email, organization_name, account_id, website_url, label_names, contact_stage_id, present_raw_address, direct_phone, corporate_phone, mobile_phone, home_phone, other_phone. dry_run=True validates the custom field ids and echoes the exact payload without writing.

Recorded conversations (calls/video meetings) — transcripts, recordings, participants. BYO key only (all ops): real recorded conversations, and the credit cost is conditional (1 if the conversation has AI insights, 0 otherwise) so it can't be metered against a platform quota up front.

Args by op:

• search: conversation_type (video_conference/phone_call), account_id, contact_ids, tag_ids, tracker_ids, organization_ids, date_range ({"start":, "end":} ISO 8601), per_page, page.

• get: conversation_id. ⚠️ 1 Apollo credit IF the conversation has AI insights, 0 otherwise — not knowable before the call.

• export: start_time + end_time (ISO 8601, GMT) + email (team member to notify). ASYNC — returns export_id; does not wait for completion. Poll with export_status.

• export_status: export_id (from export) — returns redirect_url once ready.

One-off emails (outside sequences): prepare, follow, read. SENDING is apollo_act(op="send_email") — another tool, the one your client asks you to confirm: draft here never reaches anyone. BYO key only on EVERY op: search/content/stats read the key owner's OWN sent mailbox (bodies included), not Apollo's shared database — unlike organization/people search, a platform key here would leak someone else's inbox.

Args by op:

• draft: contact_id required UNLESS in_response_to_emailer_message_id is set (thread reply). Optional subject, body_html, recipients ([{"email":, "contact_id":, "recipient_type_cd": "to"|"cc"|"bcc"}]), emailer_template_id, attachment_ids, enable_tracking, outreach_task_id. Does NOT send: apollo_act(op="send_email", message_id=…) does.

• status: message_id — poll send status.

• search: stats, reply_classes, sequence_ids, exclude_sequence_ids, keywords, date_range_mode (due_at/completed_at), date_min/date_max (YYYY-MM-DD), per_page, page.

• content: ids (up to 10 SENT email ids) + body_format (plain/html).

• stats: message_id — opens/clicks. ⚠️ Apollo doc says this needs a Master API key, not verified from this environment.

List the mailboxes connected to THIS Apollo account (BYO key only — this is the key owner's own inbox configuration, never the platform key's).

Get the id to pass as send_email_from_email_account_id to apollo_sequence_contacts(op="add").

List the send schedules configured on THIS Apollo team (BYO key only).

Get the id to pass as emailer_schedule_id to apollo_sequence(op="create") — required, creation fails without it.

Enrich a company from its domain (firmographics, size, industry…).

Returns the exact estimated_num_employees, its per-department split (departmental_head_count), 6/12/24-month headcount growth, revenue, founding year and tech stack. Costs 1 Apollo credit. For several companies at once, prefer apollo_bulk_enrich_organizations (same cost, 10× fewer calls).

List active job postings for an Apollo organization id (hiring signal).

Match a single person (enrichment). Returns {} if no match.

Pass the strongest identifier you have. Coming from apollo_search_people, that is person_id = the id of the search result — search obfuscates last names, so the id is the ONLY reliable handle on someone you just found. Otherwise: email or linkedin_url, or a FULL name (first + last) with the company.

⚠️ Costs 1 Apollo credit per call, charged even when nothing matches: a weak identifier (first name + company) makes Apollo mint an EMPTY record rather than return nothing. Such an answer carries person._stub: true — treat it as a failure, not as data. Calls with no usable identifier are refused before the credit is spent.

⚠️ ON THE SHARED PLATFORM KEY, the response carries platform_quota (used/limit/remaining TODAY, on THIS key) — check it while working through a batch to stop BEFORE the next call hits the wall, instead of finding out mid-lead. Absent on a BYO key (no ceiling applies) or when the platform quota is unlimited for your org. Once remaining reaches 0, the NEXT call fails outright (no partial/degraded match) — either pose your own key, or fall back for THIS lead to hunter_email_finder (email) and kaspr_enrich_linkedin / fullenrich_enrich_linkedin (phone, LinkedIn history): different source, no credit burned on a call that would just fail.

⚠️ NO MOBILE OR DIRECT DIAL HERE: Apollo never returns those synchronously. apollo_reveal_phone orders them, on your own Apollo key.

⚠️ reveal_personal_emails=True needs YOUR OWN Apollo key too: Apollo bills that reveal ON TOP of the match, and the shared key's meter can only charge a plain match. Same rule as apollo_reveal_phone.

The employer's heaviest blocks (tech stack, funding, sub-orgs, keywords) are dropped by default — they were 91% of the payload and overflowed MCP output limits on ONE person. projection names them; full=True returns them.

Order someone's phone numbers, mobile and direct dial included (ASYNC).

Same identifiers as apollo_match_person — the surest is person_id from apollo_search_people.

⚠️ THE NUMBERS ARE NOT IN THIS RESPONSE. Apollo delivers them to oto minutes later; what comes back here is a request_id. Pass it to apollo_reveal_phone_result — free, kept 30 days — and KEEP IT where the next agent will look (a datastore row, the run journal). Lose it and the credits are spent with nothing to collect.

⚠️ Your own Apollo key only: a reveal costs ~9 Apollo credits where a plain match costs 1, so it never runs on the shared platform key.

Collect the numbers ordered with apollo_reveal_phone or apollo_bulk_match. 0 Apollo credits. Readable through the Apollo key that paid for the reveal: whoever reaches the connector with that same key, nobody else.

done: false carries retry_after_seconds — wait that long, call again. When done, the numbers are at result.webhook_result.people[].phone_numbers[] (nested: result is Apollo's envelope). An order Apollo closed without numbers comes back as delivered: false with its reason (out_of_credits when the account ran dry): nothing more will arrive for it. Each number carries sanitized_number, type_cd ("mobile"/"work_direct") and dnc_status_cd (do-not-call: read it before dialling). Kept 30 DAYS, then gone.

With datastore, numbers go straight into your table (first mobile in phone_column, type and dnc_status_cd in its comment); only counts return.

Find companies by firmographics — the CHEAP way to qualify a list.

Costs 1 Apollo credit per PAGE (up to 100 results), where enrichment costs 1 credit per COMPANY: filter here, enrich only what you keep.

⚠️ Results carry revenue and headcount GROWTH, but NOT the headcount itself — that's why you filter by employee_ranges instead of reading a number. For the exact headcount and its per-department split, enrich (see apollo_enrich_organization / apollo_bulk_enrich_organizations).

Search people by company domains/ids, titles, seniorities, location (net-new).

Returns identities WITHOUT email/phone — reveal a contact with apollo_match_person (which costs an Apollo credit).

⚠️ LAST NAMES COME BACK OBFUSCATED here ("Vi***l"). To reveal someone you found, pass the id of the result as person_id to apollo_match_person — NEVER first name + company, which matches nobody: Apollo then mints an empty record and charges the credit anyway.

⚠️ A DOMAIN IS WORLDWIDE. On a subsidiary of an international group, the domain is shared across every country: franke.com returns 1887 profiles, verifone.com 3282, sonova.com 3147 — targeting the French entity by domain alone means revealing at random, one credit each, mostly on the wrong country. Add person_locations=["France"]. Same for the reverse case: a French head office with expatriates is organization_locations.

Manage Apollo sequences (search/create/update/activate/deactivate/archive).

Args by op:

• search: name (partial match), per_page, page. BYO key only — this lists the key owner's OWN sequences (names + open/reply rates).

• create: name + emailer_schedule_id REQUIRED (get one from apollo_email_schedules — the API refuses creation without it). Optional active (default False — prefer op="activate" once steps/templates are reviewed), label_names, folder_id, max_emails_per_day, emailer_steps (nested step/template definitions — see Apollo docs). BYO key only.

• update: sequence_id + any of name, active, emailer_schedule_id, label_names, max_emails_per_day, cc_emails, bcc_emails, emailer_steps (include id per step to MODIFY it, omit to CREATE one). BYO key only.

• activate / deactivate: sequence_id. BYO key only.

• archive: sequence_id. BYO key only. Supports dry_run=True (no get-by-id exists on this endpoint — the preview cannot show a real diff, just echoes the intended action).

dry_run=True on create/update/activate/deactivate/archive validates but skips the actual API call.

Enroll/update/inspect contacts in Apollo sequences. BYO key only for add/update_status (starts or stops an automated campaign to real people); activity (read) accepts the platform key.

Args by op:

• add: sequence_id + send_email_from_email_account_id (id of a CONNECTED mailbox — get one from apollo_email_accounts; REQUIRED, refused locally without it) + contact_ids or label_names (at least one). The HIGHEST-RISK call here: it starts a multi-step automated campaign to real people, not a single send. Supports dry_run=True (echoes the request, no get-by-id available to show a real diff).

• update_status: emailer_campaign_ids + contact_ids + mode (mark_as_finished, remove, or stop). Supports dry_run=True.

• activity: contact_id (required) + optional sequence_id filter + per_page (1-50, most recent events, not pagination). 0 credit, but BYO key only — the events are the key owner's OWN sequences.

US wages for one occupation — annual P10/P25/median/P75/P90, mean and employment, per area. Source: BLS OEWS (open data, no key needed).

LATEST published year only (the API serves no OEWS history); the year is in the result. Wages are published at the 6-digit SOC: an 8-digit O*NET-SOC code ("15-1299.08") is accepted but its suffix is STRIPPED — the figures then cover the whole SOC ("15-1299"), and the result says so in note.

Shared daily quota: one upstream request per 3 areas, 25 requests/day for the whole platform — batch areas in ONE call rather than one call per area.

Returns — {"source", "soc", "year", "note"?, "requests", "areas": [...], "messages"}. Each area: area, area_type (N|S|M), area_code, year, percentiles {p10,p25,p50,p75,p90} and mean (annual USD), employment, footnotes, raw, missing, series_ids. A value BLS withholds or caps comes back null with its raw form ("-") in raw and the reason in footnotes — never a guessed number. missing lists measures with no series for that SOC × area (small metros, rare occupations).

BODACC legal notices across ALL French companies (DILA open data, no key): find companies FROM their notices — every receivership opened in a department this week, every business sale in a city, accounts filed, deregistrations. For the notices of ONE known company, fr_events(siren) is the shorter path.

op="search" (default) — notices matching the filters, most recent first. Returns total_count, next_offset (null on the last page) and notices: flat lines — the company (siren, parties, commercant, denomination, forme_juridique, capital, adresse_siege, activite), the place (ville, departement, region, tribunal), the judgment, resume (the notice's own text). ⚠️ A SALE names two companies: siren is null and parties gives each SIREN with its role. full=true returns the full notices (heavy). ⚠️ Pagination stops at offset+limit = 10000: past it, narrow the period rather than paging.

op="count" — the number of matching notices grouped by group_by (required), largest first; mois/jour come in date order. Count BEFORE paging a large set: one call sizes it.

op="get" — one notice in full by id (the id of a search line).

Filters (search and count) combine with AND. Always bound a sweep by date: the bulletin holds tens of millions of notices since 2008.

List the Google calendars the user can access.

Returns {calendars: [{id, summary, primary, accessRole}]}. Use an id as the calendar_id argument of calendar_event; omit it for the user's main calendar ('primary').

An event in a calendar — list, read, create, fix or delete one.

op:

• "list" (default): list events from a calendar over a time range (ordered by start). Returns {events: [{id, summary, start, end, ...}], count}.

• "get": get a single calendar event by id (event_id, detailed — adds description, attendees, recurrence, reminders).

• "create": create a calendar event (summary + start, optional attendees = guest emails). ⚠️ Writes into a real calendar. With send_updates="none" (default) the guests are added but nobody is emailed — pass "all" to send the invitations. meet=True attaches a Google Meet link (returned as hangoutLink).

• "update": fix an existing event (event_id + what changes). PATCHES — only the fields you pass are touched, everything else (attendees, recurrence, reminders, meeting link) is left alone. Use this instead of creating a second event. attendees, when passed, REPLACES the whole guest list (Google's rule for lists): pass everyone — read the current guests with op="get" — and [] removes them all.

• "rm": delete an event (event_id). Irreversible. Returns what was deleted (summary + start), read before the deletion — so that deleting the wrong id does not look exactly like deleting the right one.

An article of a French collective agreement (convention collective, KALI/DILA) — search the full text, or read one article in full.

op:

• "search" (default): search the full text of French collective agreements: articles, avenants, salary schedules, extension orders. Returns {count, articles: [{id, num, texte_titre, idcc, convention, extrait, permalien, lien_construit, …}]}. Fetch full text with op="get".

• "get": full consolidated text of a collective-agreement article (KALIARTI…), with its parent text (avenant/accord), convention (IDCC), a verifiable permalien and a best-effort Légifrance lien_construit.

List French branch collective agreements (conventions collectives) by exact IDCC or title substring. Resolve "which convention is 3090?" or "conventions du spectacle" before searching articles with ccn_article(op="search").

Checks before an act, deterministic, nothing stored, nothing filed.

op:

• "check_mutual_termination": check a French mutual termination (rupture conventionnelle) BEFORE it is filed for approval.

Returns verdict (conforme | non_conforme | incomplet) and one entry per check in controles — reference salary, length of service, legal severance floor, collective-agreement floor, withdrawal period, filing date, earliest termination date — each with its figure, its status (ok | ko | non_couvert | donnees_insuffisantes | info) and the article it applies. non_couvert means the agreement's own floor is not coded yet: say it must be checked by hand, never report it as compliant. telerc lists the fields of the online filing (TéléRC, mandatory since April 2022 — no paper form to fill) in their order, for HR to copy as is; a null field could not be established and is filled in by hand. The figures come from the employee's payroll: read them with the payroll tools, never estimate them.

Build a direct export URL for a filtered subset of LES.

The caller (or another tool) fetches the URL — the full valid set is ~6 MB CSV, regional subsets are smaller.

Fetch all receipts (récépissés, L1/L2/L3 categories) for a given SIREN/SIRET.

A single structure often holds multiple licences across categories; use this to pivot from a SIREN to its full LES footprint.

Search Licences Entrepreneurs Spectacle (LES) — French open data.

Composed AND filters: this is the gap vs the official datagouv MCP which only supports one filter at a time. Returns ~63k valid licences as of 2026.

Group-by aggregation on LES — fills the gap of the official datagouv MCP.

Use cases: distribution NAF among L2/L3 producers, top regions for active spectacle entities, count per department for territorial targeting.

Aggregate rows SERVER-SIDE — stats over a whole (optionally filtered) table WITHOUT pulling the rows into context (feedback #191). Use this for totals and distributions over a large vivier (e.g. total kWc, average score, count per department) instead of reading 300+ rows and summing them yourself.

metrics = list of {op, field?}; op ∈ count|count_rows|sum|avg|min|max (default [{"op":"count"}]). count without field = total rows; sum/avg/min/max require a numeric field and ignore non-numeric values. group_by = a column to group on (omit = one global row). Results are sorted by the first metric descending when grouped (so group_by gives you the TOP groups first).

A metric may carry its OWN condition — where, same clauses as filters — so the total and a subset are counted in the SAME query. That is how you get a RATE without crossing two calls whose scopes can silently differ. Give such a metric a label, and it comes back under that name.

group_by also accepts a LIST of columns: their values are POOLED, one row contributing one occurrence per filled column ("all ranks together"). Under a pooled group, count counts OCCURRENCES and count_rows counts ROWS — two different questions, so ask for the one you mean.

A list column (e.g. contacts) is aggregated ACROSS ITS ITEMS with contacts[].<attribute>. group_by: "contacts[].fonction" makes every item of every matching row one occurrence — same vocabulary: count counts the contacts, count_rows the rows; a contact without that attribute falls in the null group. filters still select ROWS (a row kept by contacts[].fonction eq DRH contributes ALL its contacts). sum/avg/min/max with field: "contacts[].<numeric attribute>" aggregate over all items (read on the current item when grouping by the same list). A list path cannot be pooled with other columns, nor sorted; contacts[0].x targets one rank. A list of plain VALUES (e.g. tags) is read element by element with tags[]: group_by: "tags[]" counts each tag (count) and the rows carrying it (count_rows); filters on tags[] keep the rows holding the value.

⚠️ Pooling is NOT a two-dimensional group-by, and group_by: "a,b" is not one either — it is REFUSED (oto#50). A comma-separated string used to be read as a single column name containing a comma: no row carries it, so you got 200 with ONE group of key null holding every row, and no way to tell that from empty data. Group on one column per call, or pass the list if you meant to pool. Crossing two dimensions is not served yet.

Returns {results: [...]} — each entry carries the group_by value (when set) plus one key per metric (count, sum_<field>, avg_<field>, or label).

count_by = a list of columns to profile in ONE call (not with group_by or metrics): returns {counts: {column: {values: [{value, count}], empty, distinct, total, truncated}}} — most frequent values first, at most values_limit (default 50, max 500) per column; truncated says more exist.

Examples — - total rows matching a filter: metrics omitted, filter={"statut":"qualified"} - MWc by department: group_by="departement", metrics=[{"op":"sum","field":"kwc_estime"}, {"op":"count"}] - share of companies with an HR contact on ANY rank, by headcount band — one call, no rows pulled: group_by="tranche_effectif", metrics=[{"op":"count","label":"fiches"}, {"op":"count","label":"avec_rh","where":[ {"fields":["contact1_fonction","contact2_fonction", "contact3_fonction"], "op":"in","value":["DRH","DAF"]}]}] - which roles appear across all contact ranks: group_by=["contact1_fonction","contact2_fonction","contact3_fonction"] - the same on a list column, contacts and companies counted apart: group_by="contacts[].fonction", metrics=[{"op":"count"}, {"op":"count_rows"}]

SHOW a table to the user: draws its rows INLINE in the conversation, in the app's own table look (typed cells, select colours, links). READ-ONLY.

Use it whenever the user wants to SEE or browse a table's content; then answer in text. WITHOUT datastore = the list of your tables. To read rows yourself, use data_rows — this view gives you only a one-line summary.

CHOOSE the columns: pass fields with only those that matter for the question (in the order to show them) — most tables have more columns than a reader needs. Omitted = the declared columns, in schema order. Keep limit small: the user scrolls and asks for more; the default (25) is usually right.

Sort, filter and search are arguments, same grammar as data_rows: call again to change them. Next page = the next_cursor of the previous call, with the SAME order_by/q (a cursor never crosses from one to the other).

Atomically claim the NEXT unprocessed row of a datastore (work queue).

Claim with empties="sentinel" when you will re-send a list: an assumed empty (written @empty, its reason in comment) then comes back "@empty" and, sent back as is, stays one; sent back as "" it becomes an ordinary empty, refused on a required field. Never copy @empty into a deliverable.

⚠️ Your filter MUST name a column your processing WRITES. That is the one condition which makes the queue EMPTY, and nothing enforces it. The order: rows never served first, then the least recently served — a released row goes behind every fresh row, but it comes back once they are served, for as long as it still matches your filter.

⚠️ How to see a queue running empty: the row carries _claims. Above 1 it means « you have already been served this row and it was not written » — that is the signature. Stop and re-read your filter; claiming again will not help.

⚠️ A claim lives in a run. Call run_start first and pass its run_id as _run_id= on this call: without an active run the claim is REFUSED and nothing is reserved — a row held outside a run could not be written, so you would research it for nothing.

Write your result and release it by the _id of the returned row.

⚠️ Address the table by its NUMBER, not its name: the reply carries ns_id (e.g. 174), the form to pass as datastore in every following call — data_write(datastore=174, id=…), data_release(datastore=174, …).

The primitive for draining a table with N parallel (sub-)agents without collisions: picks, among rows whose claim lease is free or expired, the one served least recently (never-served rows first, then creation order), stamps _claimed_by/_claimed_until and returns it — two concurrent workers never get the same row. Returns {row: null} when nothing is left to claim.

Filter on column A, write into column B, and the queue never empties: once the fresh rows are served, your own finished rows come back, round after round. Measured on a 3 766-row table, when the order was still « oldest first »: three workers filtered on a column the processing never touched. 834 fresh rows were never reached, and one worker claimed the SAME row seven times. Every call succeeded and no error was raised — a livelock, not a failure, and you cannot see it from inside. Rows claimed again and again without a write end up set aside (the ceiling below) — LOST to the pass, without being at fault.

A name still resolves as datastore until 2026-11-08 — then it is refused — but the number is what to carry: it survives a rename, it is unique where a name is only unique per owner, and it is what the platform records. datastore in the reply is the table's REAL name whatever form you passed in, so reading "600" back from a claim on 600 no longer happens.

worker is a label YOU choose and REUSE verbatim on data_release — the guard so one agent cannot release another's claim. filter (exact {col: val}, e.g. {"status": "nouveau"}) selects what counts as claimable; it narrows the table's declared lifecycle.claimable, never widens it. The claim does NOT change the row: write your progress via data_write (id=…), then release it — writing a "final" status does not free it (#317). Release the row with data_release if you have it; otherwise finishing your run (run_finish) releases it. Never write your intent into the row (no _action/_liberation columns). The lease (lease_s, default 900s) only covers a worker that died. While you hold a row, nobody else can write it.

Multi-pass table (lifecycle.advance declared): claim by the state of YOUR pass (filter={"statut": "societe"}), write your findings, release — the platform moves the row to the next state. Do not write that state yourself.

The row carries _claims = how many times it has been claimed since the last successful write. A row claimed over and over WITHOUT a write is a queue running empty: past the ceiling — lifecycle.max_claims declared on the table, else a platform default of 3; max_claims here can only RAISE it for this pass — the server sets it aside: it stamps _abandon with the reason, ending with what the LAST attempt hit (the job's error, a refused write, the tools in error, or no write attempted) and _abandon_run with that attempt's run, moves it to lifecycle.abandon_state when the table declares a ceiling (with the default one its status is left untouched), and STOPS serving it — whatever your filter says. It stays readable and repairable: an explicit data_write puts it back in the queue and resets the counter.

⚠️ layers="nested" gives the row back in the SHAPE YOU WRITE — a cell that carries layers comes as {"valeur": …, "comment": …} instead of the flat pair champ + champ.comment. ⚠️ It stays a READ: do NOT send this row back. Write only the fields you established — and never <field>.origine, which is read here and set by the platform, never by an agent. The flat form shows a key with a DOT, and a dot does not look like a field name: agents turn effectif.comment into effectif_comment, which creates a ghost column — or, on a table that refuses unknown columns, loses the whole row. This is the only read that feeds a WRITE loop, so it is the one where the shape matters.

Every column DECLARED in the schema is on the row, null when no value is in place — null means "nothing here yet": find it if your task needs it, never make it up. Sending such a null back changes nothing (a null only erases a value that is in place); still, write only the fields you established.

filters is the LIST form — [{field, op, value}], ANDed with filter. Use it when one column needs TWO bounds: filter accepts a single operator per column, so a range (score >= 10 AND score <= 20) can only be expressed here. Same grammar as data_rows.

datastore also accepts slot:<name> (table bound by the active project).

Create a new datastore (PG-backed), optionally WITH its typed schema.

⚠️ A new table is born with NO column, and a write into a column the schema does not declare is REFUSED (unknown_column): its first write is refused until columns are declared. To create a table you are going to FILL, pass schema — the SAME object as data_set_schema ({"fields": [{"key": …, "type": …}], "key"?: …}, same closed vocabulary, same validation): the table is born with it, in ONE atomic call. If the schema is refused, the table is NOT created. That is the normal way to create a table you fill; without schema it is born free, and data_patch_schema(fields=[…]) declares columns later.

The table is PRIVATE: it belongs to you, and no one else can read it — not the other members of your org, not its admins. That is the default and it is never implicit (ADR 0068).

⚠️ It used to be owned by your ACTIVE ORG, readable by every member. To share a table with your org or a team, say so: the REST route takes owner: {type: "org"|"group", id: N}. Tables created before 2026-09-04 keep the owner they have.

⚠️ _org= does NOT change the owner. It decides which org you read and write under — never who owns what you create. Create a table under _org=N without an owner and it is still YOURS: every later call of yours keeps working, so nothing looks wrong. It shows up at the second agent, or at the colleague who cannot find the table and concludes it does not exist. The reply tells you the owner, and warns you in exactly that case.

A personal table is LISTED in your PERSONAL org, whatever org you create it under — data_list_datastores from any other org does not show it. Its number (ns_id) opens it from anywhere.

Delete a datastore and all its rows (irreversible). Owner (or org/platform admin governing it) only.

Delete a row by _id — or a BATCH of rows with ids, in one call. datastore accepts slot:<name> (active project).

expected_revision = the _revision of the row as you read it, when it is that read that made you decide to delete. If the row changed since (any column, or its reservation), nothing is deleted and the call is refused. Omit it when you delete a row you did not have to read first.

BATCH (ids, up to 500): each item is an _id, or {"id": …, "expected_revision": …} to guard that row. Each row is deleted on its own: one refused row (changed since read, reserved by another work) does not stop the others. Returns deleted, not_found and refused (id, error, current_revision on a conflict). A malformed item refuses the whole call before anything is deleted.

DESTRUCTIVE — erase a column from EVERY row of a datastore (confirm=True required). Removing a field from the schema takes it out of the view, but the key stays in each row: it still shows up on read, and keeps attracting writes. Writing null does not erase it either. Use it after RENAMING fields — the old names often describe the content better than the new ones, so an agent re-reading a row writes into them believing it aims right; purge them once instead of warning every agent forever. A key still DECLARED in the schema is refused: take it out of the schema first (data_set_schema). Returns {rows} = how many rows carried it, ALWAYS >= 1: a name that no row carries is REFUSED, never reported as a zero — so a success is always a removal you can tick off. The refusal says which of the two it is: a typo (no column of that name), or an ANNOTATION such as site_web.comment — served flat next to its column but stored under it, so a column purge does not reach it (write {"site_web": {"comment": null}} instead).

Read a datastore's declared TYPED schema (the one data_set_schema posts). Returns {datastore, ns_id, schema, enforced, reglages} — schema is null when none is declared, which is a normal state, not an error. reglages gives the head setting AS APPLIED, default included: new_rows (create | reject — whether a write that designates no existing row may create one). unknown_columns was REMOVED on 2026-10-05 (columns and values are always checked); a stored leftover of it, or of strict, unknown_fields and key_required, is named in warning. ns_id is the table's NUMBER (e.g. 174) and datastore its canonical name, whatever form you addressed it by: pass the NUMBER as datastore from here on — a name still resolves until 2026-11-08, then it is refused. Read it BEFORE amending: data_set_schema posts the schema WHOLE, it does not merge, so adding one field means re-posting the existing definition plus that field. The work queue itself needs NOTHING declared: data_claim_next reserves rows on any table, with or without a schema. A lifecycle block only RESTRICTS it, on the column that carries the block: states/transitions/terminal — transitions maps each state to a LIST of reachable states, even for one ({"a": ["b"]}, never {"a": "b"}, which is refused) — plus max_claims + abandon_state — the ceiling of claims WITHOUT a write past which a row leaves the queue; labels ({state: "Displayed name"}) names each step for a screen and is never applied to a write. enforced lists the validation keys THIS deployment actually applies (required, max_length, pattern…): check what you are about to declare against it, rather than against documentation — a key posted but not enforced looks like a contract and is not one, and one enforced only after the next deploy freezes rows all at once, weeks after the cause. ⚠️ It says what BITES, not what is USEFUL: a key absent from enforced is not dead — presentation keys are read by whoever renders the table, and oto cannot know who reads what downstream. Never drop a key on the strength of its absence here. warning appears only when the stored schema still carries keys no level admits — posted before the vocabulary was closed (2026-10-01), typically a leftover enum beside the options that actually constrains the field. When it does, trust the key the warning names: the other is a residue, whatever it says. Writing a NEW unknown key, or changing one, is refused. tel_que says which reading this is. servi (default) is the schema as served to you: through this tool, columns the owner keeps from agents are left out, and colonnes_masquees counts them. stocke — owner or governor only — is the schema as stored, whole, plus gardes: per column, what the guards actually do HERE (verrouillees, masquees_a_l_agent, lecture_seule_agent) and sans_effet, what is declared and applied by nothing, with the reason. forme=compacte keeps only the keys that constrain, without prose or null keys — for inspection, never to post back.

List the datastores of the active org: the org's and your teams' tables, and those shared with the org or your teams — never a personal table nor one shared with you as a person. Those are listed in your PERSONAL org only, which also lists ALL your personal tables (whatever org they were created under) and the tables shared with you as a person (shared: true).

A table missing from this list is not gone: it still opens by its number from any org.

Each entry carries the table's NUMBER under BOTH names — ns_id (the form to pass as datastore from here on, and the one every other reply uses) and id (the same number, kept for the dashboard's deep links).

Change a datastore's schema BY KEY, without rewriting the whole field list. Prefer this over data_set_schema for any EDIT: set REPLACES, so rebuilding the list from what you know silently drops the per-field settings you did not restate (labels, help, max_length, pattern, width, options) — same call, same success, no way to tell. fields merges by key: listed properties overwrite, unlisted ones are PRESERVED, unknown keys are appended. remove: ["key", …] is the explicit deletion (a wrong key is refused, never silently ignored) — it takes the field out of the SCHEMA; to erase the column from the rows' DATA, that is data_drop_column. remove_attrs: {"column": ["attr", …]} takes attributes off columns that STAY — merging only completes, so this is the only way to drop one declaration without reposting the whole schema; an unknown column or attribute is refused, and key cannot be dropped. key/new_rows change the head keys, untouched when omitted — key names the BUSINESS KEY: A write that DESIGNATES by the key — key= passed to the call (a batch, or a single row naming this key), or any write without id on a CLOSED table — modifies the row of an existing key value and creates a new one. A write that ADDS (neither id nor key=) with a key value already present is REFUSED unless it passes upsert=true, which merges onto that row — data_write, REST and oto_upload_url alike. The key never duplicates: its UNIQUE index guarantees it. new_rows: "reject" CLOSES the table (a write designating no existing row is refused), "create" reopens it. ⚠️ A column the schema does NOT declare is REFUSED at write, on EVERY table: declaring a column (data_patch_schema(fields=[{"key": …}])) is the ONLY way to add one. ⚠️ The declared format is a CONTRACT on every table: top-level options are enforced, the SHAPE of text/url/object/list/enum values is checked, an unknown layer is refused and a declared sub-record refuses an attribute it does not declare. There is NO head setting for it any more: unknown_columns was REMOVED on 2026-10-05 and is refused — columns and values are always checked. To ADD a column, list it in fields ({"key": …, "type": …}): it is appended, the others are untouched; to ACCEPT a value its options refuse, list the column again with the full options. key_required was REPLACED by new_rows on 2026-10-02 (refused with its exact equivalent); strict, unknown_fields and unknown_columns are refused: no head setting decides what is checked any more. Per field, readonly: true locks a value once SET (layers such as .comment stay open); a cell with NO value — key absent, null or "" — can still be filled once, so a column locked after its import is not empty for good, while @empty counts as set — the table's OWNER, or whoever GOVERNS it, can still replace such a value with data_write(readonly_override=true), for that one call and journaled, so locking a column never means nobody can correct it again. On the field that carries lifecycle, the block merges KEY BY KEY and its transitions merge STATE BY STATE: naming one state leaves the others alone, so declaring a way OUT of a terminal state is one line and costs nothing else. Each state maps to a LIST, even for one destination — transitions: {"won": ["lost"]}; a bare string is refused. Taking one out is explicit — transitions: {"lost": null} drops that state's exits, lifecycle: {transitions: null} drops the whole table. labels (the displayed name of each state) merges STATE BY STATE too: lifecycle: {labels: {"lost": "Lost"}} names that step and keeps the others' labels, {"lost": null} drops that one label. A key that its level does not admit (head, column, sub-field, of, lifecycle) is REFUSED when the patch posts or changes it — the refusal names the path, the key and the closest known one; an unknown key ALREADY stored and left untouched does not block a patch of another column, and remove_attrs takes it off. Your own annotations go in meta (an object, at every level, carried as is, never read, at most 4096 bytes as JSON; a patch replaces it whole); help text goes in description (note, help, hint, placeholder are refused). Field ORDER is never reshuffled. Returns the resulting schema plus {added, updated, removed} and any warning the schema raises, and existing_violations: per path (contacts[].email), how many rows ALREADY IN PLACE break the resulting schema, a sample of their ids and the consequence (blocking_rows accept no write at all until fixed) — clean them before arming the guard. existing_violations_scope.complete: false means the row cap was hit: the counts are floors.

Release a claimed row — the NORMAL end of processing one row, and the counterpart of data_claim_next. Guarded by worker (same label as at claim time), and addressed by the _id that data_claim_next returned.

⚠️ Call it after EVERY row you finish, not only when abandoning: writing a "final" status no longer frees the row (#317). If you wrap your work in run_start / run_finish, closing the run frees everything it held — that is the safety net when you forget.

On a table that declares lifecycle.advance, releasing a row you WROTE since claiming it moves it to the next state (advanced: {field, from, to} in the reply); a row you did not write stays where it is.

datastore = the table's NUMBER (ns_id, the one data_claim_next handed you) — the form to use. Its name still resolves until 2026-11-08, then is refused. slot:<name> also works.

Rename a datastore. Only the name changes — the id, URL/deeplink and shares stay stable (grants are keyed by id). Governance right required (owner, or the org/platform admin governing it). The new name must be free for the same owner.

Use this to lift a name collision (e.g. two reconcile_log across orgs) before transferring/consolidating: rename one side, then transfer with oto_resource.

Review queue card (MCP App) — ONE row at a time, two buttons, in the chat.

For a procedure's HUMAN step ("a person reviews the pending leads and launches them"): shows the next row whose status column equals pending (title, a few fields, the note), the USER clicks approve or reject, the status is written and the card moves to the next row. The user decides — never call this to decide on their behalf; to set statuses yourself, use data_write.

The only rendered app that writes, and only this: one status column, set to approve or reject, on a row still at pending at click time (a row changed meanwhile is skipped, never overwritten). When the queue is done, the card offers one "Continue in chat" button: the user's click posts a factual summary as their message ("Done reviewing: 2 launched, 1 skipped.") — the signal to resume the procedure. It still sends or launches nothing in any other tool.

Add a comment to ONE datastore row, as the caller. Anyone who can read the row can comment. It does not change the row: to change a value, write it.

Read the comments people left on ONE datastore row, oldest first within a page; before_id (= the previous next_before_id) reads older ones. Comments are not row values: they never change the row or its history.

Read the revision history of ONE datastore row: every write, newest first, with the values before and after (diff: {column: {avant, apres}}), who wrote it (acteur), under which run (run_id), through which face (source: import, agent, console, api, upload, system) and in which gesture (geste_id). champ keeps only the revisions touching that column. Page with limit and before_id (= the previous next_before_id). ⚠️ Coverage: the journal only holds writes made since it went live on 2026-09-24. A row with NO revision is NOT a row that was never modified: it may simply not have been written since. coverage.insert_recorded: false means the row predates the journal and its history starts mid-life. Deleting a row IS a revision (suppression: true, every value under avant, stamped with who deleted it). A deleted row keeps its history, readable only by whoever governs the table (row_deleted: true, deletion = who and when, null if it was deleted before the journal recorded deletions).

Read rows. WITH id = the single row (by _id). WITHOUT id = one PAGE of rows (filter/q narrow it, order_by sorts it) with a stable cursor.

Read with empties="sentinel" before re-sending a list: an assumed empty (written @empty, its reason in comment) then comes back "@empty" — an ordinary "" stays "" — and, sent back as is, stays one; sent back as "" it becomes an ordinary empty, refused on a required field.

⚠️ datastore = the table's NUMBER (ns_id, e.g. 174) — the form to use; the reply carries it back. A name still resolves until 2026-11-08, then is refused. slot:<name> also works.

⚠️ List mode returns {rows, count, next_cursor, ns_id}. When next_cursor is not null there are MORE rows: call again with cursor=<next_cursor> (same datastore/filter/order) — repeat until next_cursor is null. A page is not the table.

versions picks which VERSIONS of each cell you get. By default, the current value only; the origin (the FIRST version of the data) is asked for with versions=["current","origine"]: current is what we established, origine what the client handed over. ⚠️ Ask for BOTH in ONE call when you compare them — two calls are not atomic, and an write in between would make you compare the before of one state with the after of another.

Layers come back FLAT by default (champ.origine beside the bare name); layers="nested" returns the shape you write — guide datastore-semantics. The bare name ALWAYS carries the current version; versions only decides what is added beside it — at any depth: without origine, a list item carries no item["email.origine"] either. The reply states what it served in versions_servies, so "I did not ask for it" never looks like "this cell has none". The REST face GET …/rows pages by offset with a total, no cursor.

Without order_by the cursor is keyset-stable (rows created meanwhile don't shift the paging). With order_by it pages by offset instead, since an arbitrary sort has no stable keyset — so a row inserted mid-walk can shift the remaining pages. q without order_by ranks the rows (best match first), so it pages by offset too. Keep the SAME order_by and q across a walk: passing a cursor from one regime into the other is rejected rather than silently mispaged.

Use count_only=True to get just the TOTAL number of (optionally filtered) rows — computed server-side, no rows returned — when you only need the count (e.g. how many leads match a filter) without pulling the data into context.

Use fields to PROJECT a subset of columns when the full row is heavy and you only need a few (e.g. name + email + score over a large vivier): each row is trimmed to those columns (plus _id, always kept so you can still update the row), drastically shrinking the payload. Bump limit when projecting — narrow rows let you pull far more per page.

Every column DECLARED in the schema is on each row, null when no value is in place ("nothing here yet", not "no such column") — including in a projection.

Declare (or clear with schema=null) a datastore's TYPED schema (ADR 0032 §6).

A typed datastore renders as readable cards/records instead of a flat table. schema = {"fields": [{"key": str, "label"?: str, "type"?: "text|number|date| datetime|bool|json|object|list|url|email|phone|ref|enum", "options"?: [str], "display"?: "title", "role"?: "status|metric|note|qualif", "description"?: str, "meta"?: {…}}], "key"?: str, "new_rows"?: "create|reject", "description"?: str, "meta"?: {…}}. An enum column's allowed values go in options, ON the field ({"key": "status", "type": "enum", "options": ["kept", "rejected"]}) — that is what constrains the values and what a board groups on. Never in meta: a key the field admits is REFUSED there (stored, it would do nothing). ⚠️ The vocabulary is CLOSED: a key its level does not admit is REFUSED — at the head, on a field, on a sub-field, in of, in lifecycle. The refusal names the path, the key and the closest known one (read_only → readonly), or where it belongs (states → lifecycle.states, semantic_search → a parameter of this call). An unknown key ALREADY stored and left unchanged is tolerated (named in warning), never one you add or change. Your own annotations go in meta — an object, allowed at every level, carried as is, never read, bounded in size. Help text goes in description (note, help, hint, placeholder are refused). Each level's keys, who reads each one and the meta bound (meta_max_bytes) are served at GET /api/datastore/schema/keys. ⚠️ This REPLACES the schema — it does not merge. Any setting absent from the body you send DISAPPEARS (a field note, a bound, options, the business key and its UNIQUE index). The response now names what it just removed (declarations_effacees, with the lost VALUES — it is the only copy left) and enforced (the validation keys THIS version applies). To EDIT a schema without risking part of it, use data_patch_schema: it merges by key and cannot destroy what it does not name. The response also carries existing_violations: per path (contacts[].email), the rows ALREADY IN PLACE that the posed schema condemns — rows, blocking_rows (rows that accept no write at all until fixed), sample_ids and consequence. Clean them before arming the guard; existing_violations_scope.complete: false means the row cap was hit and the counts are floors.

The optional top-level "key" names the field that is the row's BUSINESS KEY (e.g. "email", "siren"). A write that DESIGNATES by the key — key= passed to the call (a batch, or a single row naming this key), or any write without id on a CLOSED table — modifies the row of an existing key value and creates a new one. A write that ADDS (neither id nor key=) with a key value already present is REFUSED unless it passes upsert=true, which merges onto that row — data_write, REST and oto_upload_url alike. The key never duplicates: its UNIQUE index guarantees it. ⚠️ A column the schema does NOT declare is REFUSED at write, on EVERY table: declaring a column (data_patch_schema(fields=[{"key": …}])) is the ONLY way to add one. ⚠️ The declared format is a CONTRACT on every table: top-level options are enforced, the SHAPE of text/url/object/list/enum values is checked, an unknown layer is refused and a declared sub-record refuses an attribute it does not declare. There is NO head setting for it any more: unknown_columns was REMOVED on 2026-10-05 and is refused — columns and values are always checked. ONE head setting is left (strict, unknown_fields and key_required were replaced on 2026-10-02; unknown_columns was REMOVED on 2026-10-05 — no setting decides what is checked, all are refused):

• "new_rows" — whether a NEW row may be born: "create" (default) or "reject", which CLOSES the table: a write that designates NO existing row (no id, and no key value the table already carries) is REFUSED instead of creating one. Needs key. A table often fills up before it has its key, hence the default. data_get_schema serves it AS APPLIED (reglages). Pass schema=null to switch back to free-table mode.

PRESENTATION — the schema also DRIVES THE UI (there is no visual editor: this tool IS the way to configure how a table looks):

• field ORDER in the record view = the order of fields here. Reorder the list to reorder the form.

• type picks the WIDGET: date/datetime → date picker (readable, not a raw ISO string), url → compact field + open link (never a giant text box), email → mail field, enum (+ options: [...]) → dropdown, bool → true/false, number → numeric. Untyped fields fall back to a plain text box, so DECLARE the type when the rendering matters.

• width: "half"|"full" = the field's width in the record form. Without it the width is derived from the widget — declare it to keep a stable layout.

• hidden: true = keep the field OUT of the table columns by default (still editable in the record). Use it for opaque ids and technical fields.

• display: "title" NAMES the row: that field titles the record everywhere the server names a line (work queue, undo, cards) instead of a raw _id. One per table.

• role only steers the dashboard's rendering (metric tiles, note placed last, status badges) — oto does not read it: a lifecycle block designates its own column, no role needed. ⚠️ The dashboard still titles rows from role: "title", which the server no longer reads. On a table meant to look right in BOTH, declare both until they converge.

STRUCTURED RECORDS (ADR 0046 — every layer opt-in):

• nested types: type:"object" + fields:[…] (sub-record, e.g. occupant); type:"list" + of:<field-def> (list of scalars or sub-records, e.g. contacts = list of {nom, titre, email}).

• write validation: field.required: true, type conformity, field.required_when: {"<field>": "<value>"} (e.g. deliverables required when status="qualified" — ⚠️ to UNDO, clear the gated field AND leave the triggering state in the SAME data_write call: the gate is judged on the MERGED row, so a call that only clears the field while the state still matches is refused), field.max_length: <int> on a SCALAR field, and field.pattern: "<regex>" for its SHAPE when the size does not separate anything (a code, a snake_case identifier) — re.search, so anchor it yourself (^…$). A pattern applies on its own: the value it reads is bounded by max_length when declared (≤1000), else by 1000 characters — a longer value is refused. The cost of a regex is bounded against that length, and oto refuses what it cannot price — an ambiguous repeated group, a backreference, a lookaround are rejected AT DECLARATION TIME, each naming why. type: "phone" holds a phone number: international (+, country code — E.164) preferred, national digits accepted, spaces, dots and dashes allowed; a sentence or an identifier is refused. type: "ref", "target": <table number> is a LINK column: the cell holds the _id of a row of that table (a list of links: "type": "list", "of": {"type": "ref", "target": <number>}). A name written there is refused — find the row with data_rows on the target and write its _id. The target must be a table you can read. field.required_layers: ["comment"] refuses a write that leaves a NON-EMPTY value in that column without posting the layer — the value must arrive WITH its provenance, in the SAME call ("col": {"valeur": …, "comment": "where it comes from"}). A null or empty value, and a layer posted alone without a value (a note beside the value, not an assumed empty — that is @empty), trigger nothing — even when the value already in place lacks the layer: that is how you add it ("col": {"comment": …}), without re-sending the value. Applies to sub-fields of objects and of list items too; never to readonly nor the lifecycle column; never to a column this write does not name. It arms ITSELF — no head setting needed. ⚠️ It does NOT make a comment TRUE: it forces you to NAME a source, which makes a lie checkable — the truth is still established on the documents. Every declared constraint applies (the format as a whole from the date above). A non-conforming write FAILS naming the culprit (max_length reports the actual length AND the bound; pattern reports the value it saw AND the motif). Only what a write SETS is judged: a row whose stored value is already off-format still accepts a write to its OTHER columns — the stale value is named back in hors_type, never a reason to refuse. Fields the caller does NOT write — one question ("whose column is this?"), and each refusal names the field, the reason and where the thing goes: field.readonly: true refuses a write that CHANGES a value already SET (layers stay open — what another source says goes in <field>.comment); a cell with NO value (key absent, null or "") can still be filled once, @empty counts as set, and clearing a set value (null) is a change; ⚠️ field.origine: "system" was REMOVED on 2026-09-08 and is now REFUSED like any unknown key. Nothing captures a previous value automatically any more: the origin is set by the call that BRINGS the data, with donnees_d_origine=true (data_write says how). Re-sending the SAME value is never a write, so re-emitting a record you just read always passes. Bound the fields meant to hold ONE short value (a job title, a city): a column that collects reasoning stops being groupable/filterable. The bound applies to the keys a write actually SETS, so rows already over it keep working until that field is rewritten — and setting a bound on a table that already overflows answers with a warning saying how many.

• lifecycle: the column that carries the block IS the status column (no role tag needed), lifecycle: {states:[…], transitions:{from:[to…]}, terminal?:[…]} — unknown state or undeclared transition is refused. Each transitions value is a LIST, even for one destination: {"a": ["b"]}; {"a": "b"} is refused at declaration; terminal is a LIST too. ⚠️ It no longer releases the work-queue claim: writing a "final" state does NOT free the row (#317). Release is a gesture of the LOCK — data_release, or closing your run — never an inference from a business value.

• step labels: lifecycle.labels: {"a_qualifier": "To qualify", …} — the name a screen shows for each state instead of its code. Presentation only: no write reads it, a row still carries the code. Each key must be a state of states (an unknown one is REFUSED and named), each value a non-empty string of at most 60 characters; a state without a label is fine (the screen derives one from the code).

• work-queue ceiling: lifecycle.max_claims: <int >= 1> + lifecycle.abandon_state: "<terminal state>" — a row claimed that many times WITHOUT a successful write leaves the queue in that state, with a platform reason in _abandon (ending with what the last attempt hit; its run in _abandon_run). Both go together: a ceiling without an abandon state, or an abandon state that is not terminal, is REFUSED here. Counter (_claims) resets on the first successful write to the row. Undeclared, a platform default ceiling (3) still applies: the row is set aside with its reason in _abandon, its status left untouched. lifecycle.claimable: {col: val | {op: val}} (filter grammar) = the rows the queue SERVES: no claim hands out a row outside it, whatever filter says.

• passes: lifecycle.advance: {"societe": "dirigeant", "dirigeant": "email"} — the counterpart of abandon_state. A claimed row RELEASED (data_release, run_finish) after at least one successful write since its claim moves to the next state, as a platform revision of that run. Agents claim by state and never write it; if a pass writes the state itself, its write wins. No write, no move (the ceiling applies). Each step must be a declared transition, never from a terminal state — refused here otherwise.

SEMANTIC SEARCH (#67 V2.2 — opt-in per datastore): pass semantic_search=true to make this datastore's ROWS findable by MEANING via oto_search (not just exact words), embedding each row (has a per-row cost → off by default; enable it on the tables you actually search by concept). false turns it off and purges the embeddings. Passing ONLY semantic_search leaves the schema untouched.

Share (or with remove=True, unshare) a datastore with another oto user. The recipient accesses it with their own oto account.

Identify the recipient by email, or by recipient_sub when one address carries several accounts — an ambiguous address is REFUSED, never guessed.

Set columns on EVERY row matching a filter, server-side, without pulling ids into your context — e.g. derive a tier from several columns. filter/filters = the data_rows grammar; set = {column: value}. only_if_empty=true skips rows where the column already holds a value (@empty counts as empty), so ordered rules (Hot, then Tier 1, 2, 3) run first-match-wins. Start with dry_run=true: it returns matched and sample rows (from → to). Each row goes through the same checks as data_write(id=…) and lands in its data_row_history; a row changed since selection is skipped (conflicts), never overwritten. A missing target column is declared first. Returns counts, not rows. If next_cursor is set, the time budget ran out: call again with cursor=<next_cursor>. set={"journal[+]": "…"} appends a line to each row's text cell (or an element to a list), under the row lock, without a revision check: concurrent appends all land. An append is never unchanged — rerunning the rule appends again. Past 64 000 characters a cell refuses the append: a log that long belongs in a table, one row per entry.

Return the web URL of a datastore, for the user to open it. url is null when this account's product has no table page — url_absente then says why; the table still exists. datastore accepts slot:<name> (active project). With filter/q/order_by (as in data_rows), the URL opens that filtered, sorted view — a shareable link — and count = the rows it shows.

Write one row, or a BATCH of rows in a single call.

⚠️ Provenance goes in comment, never in origine. Put WHAT you established and WHERE it came from in <field>.comment, and the page in <field>.link. origine is the platform's layer — an agent never writes it. Writing <field>.origine is REFUSED unless the call declares origine_override=true — which belongs to an import, not to a write of your own.

Layers: valeur/comment/link are yours to write, origine is read only — write nested, {"field": {"valeur": …, "comment": …, "link": …}}, never these as top-level keys of your own row. Provenance (WHAT you established, WHERE it came from) goes in <field>.comment, the page in <field>.link — never in origine, the platform's layer. A misspelled layer name next to a known layer ({"valeur": …, "comnent": …}) is REFUSED; alone ({"field": {"comnent": "x"}}), it is no layer: that dict IS the value. What a write destroys, what readonly and the business key protect, and where the REST face differs: guide datastore-semantics (oto_guide op=read slug=datastore-semantics).

⚠️ Writing a value DROPS the comment and link that came with it — they described the OLD value. To keep one while the value changes, send it back as it is.

Two gestures on a cell, and only two: null = ERASE the cell: {"field": null}. The erased value is kept nowhere: the response hands it back once, in valeurs_effacees. "@empty" = "searched, nothing found", its reason in comment: {"valeur": "@empty", "comment": "registry and imprint: none"}. It satisfies required (a plain "" does not) and reads back "" — or "@empty" with empties="sentinel". On a layer (comment, link), it only empties that layer.

⚠️ On a cell that holds a value: keep it and write the layers alone ({"field": {"comment": "…"}}), erase it with null, or discard it with @empty and the reason in comment. A field you leave out is "not mine" — its value stays. A comment alone is a note beside the value, never "searched, nothing found".

⚠️ "@keep" and "@clear" are not accepted: a write carrying them anywhere is REFUSED whole. Instead of @clear, write null. Instead of @keep, leave the sub-field out — or, for a comment or link that must survive a value that changes, send it back as it is.

"" and [] are values: they REPLACE the value in place, like any other value, and the replaced value comes back in valeurs_effacees. To keep a value, leave the field out; to erase it, write null.

⚠️ Business key: ADDING a row whose key value already exists is REFUSED (business_key_exists, naming the existing row) unless you pass upsert=true, which merges onto it. To DESIGNATE a row, pass its id=, or name the business key with key= (a batch, or a single row naming the declared key): an existing key value then MODIFIES its row and a new one creates it, no upsert needed. Without id or key=, a write ADDS a row. Two rows of one call with the same key value refuse the WHOLE batch, before anything is written, unless upsert=true. A batch reports every merge in fusions — {rang, dans_rang, id, cle}, dans_rang being the earlier row of the SAME batch that made the target row, null for a row already in the table — and ids stays aligned row for row. On a CLOSED table (new_rows: "reject") every write without id designates by the key.

⚠️ A write into a column the schema does NOT declare is REFUSED (unknown_column), on every table — nothing is written, a batch is refused WHOLE. To write a NEW column, declare it first — data_patch_schema(datastore=…, fields=[{"key": "<column>", "type": …}]) — then write. ⚠️ The declared format is a CONTRACT on every table: top-level options are enforced, the SHAPE of text/url/object/list/enum values is checked, an unknown layer is refused and a declared sub-record refuses an attribute it does not declare. A violation is refused (row_invalid; an off-options value alone in its fault is set aside and the rest of the row is written). Only what a write SETS is judged: a row already off-format still accepts a write to its OTHER columns (the stale value is reported in hors_type). No head setting changes this.

⚠️ @empty must be the ENTIRE sub-field, alone. Mixed into a sentence it is just text and gets stored as such — "@empty ; nothing on the imprint" lands in the cell verbatim, and a client reads it in their deliverable. The reason goes in comment.

In a list, the word goes on the element's field: {"contacts": [{"nom": "Alice", "fonction": "@empty"}]}. A list whose schema declares no of.key is REPLACED by what you send: read the row with empties="sentinel" and send each element back as it came, so an assumed empty stays "@empty". Refused on an element's identity (of.key), in a list of plain values, and inside an object or a json column.

ONE element of a list is written at its RANK — the address you read and filter by: {"contacts[1].email": "d@x.fr"} (or {"valeur": …, "comment": …}; contacts[1].email.comment alone annotates it, null erases it). {"contacts[+]": {…a whole record…}} appends, {"contacts[0]": null} removes. Ranks start at 0 and point at the list AS YOU READ IT; the append comes last. To add or remove WITHOUT reading the row first: {"tags[+]": ["x", "y"]} appends one element or a list of them, in order, duplicates kept; {"tags[-]": ["x"]} removes every occurrence of each value (plain values only — a record is removed at its rank; an absent value is refused). Both are applied under the row lock: two concurrent appends both land. On a text column, {"journal[+]": "…"} appends a line to the cell (a list = several lines) without resending it; a log kept by many is better as a table — past 64 000 characters (unless the column declares max_length) an append is refused: move the log to a table, one row per entry. Refused, with the form that works: a rank that does not exist (append with contacts[+]), contacts[0]: {…} (write its fields), contacts[].x, and the whole column together with one of its ranks.

A requirement declared on a sub-field (required, options, max_length… on an element's nom) is enforced like one on a column. In a list with of.key, only the elements your write CHANGES are judged: an element sent back unchanged never blocks yours — its defect comes back in hors_type. Written at its rank, only that element is judged, with or without of.key.

Dates: a date/datetime column reads ISO in any variant, 04/09/2026 (day first) and Unix timestamps, and STORES one form — 2026-09-04T10:00:00Z (UTC) for an instant, 2026-09-04 for a day; known only to the month or the year, it stays 2026-09 / 2026. An instant without a time zone is taken as UTC, and notices says so: write its offset (+02:00) if it is local time.

A schema refusal ends with the payload to send back: only the fields to fix, a <…> template in place of each value, | @empty where that is allowed — {"contacts": [{"role": "RH", "nom": "<text> | @empty"}]}. Fill the templates and write again; a list goes back WHOLE, that element fixed in its place (by its of.key, else its rank), the others as they were — or write only that element's fields at its rank (contacts[1].nom).

⚠️ A write DESTROYS what is in the column. On an open column there is no undo: the previous value leaves the row the moment yours lands. It survives only in the row's revision journal — data_row_history serves each write's before and after, kept 90 days by default — and nothing puts it back for you. If the value was supplied by the table's owner, announce what you are about to change on a column you did not fill yourself.

⚠️ There is NO automatic safety net. origine: "system" was REMOVED on 2026-09-08. It captured the previous value lazily, on the first write that changed it — which required having been declared BEFORE the row existed. Declared after the fact it caught nothing: 837 cells out of 846 lost on one campaign table, the owner's values already overwritten by agents.

What replaces it is a DECLARED gesture, carried by the call that brings the data in: donnees_d_origine=true. It sets the FIRST version of the data (the origin) and marks the write as an import in the journal — the current value and the origin both go in at the moment the value enters, so there is no "before" and no "after" to get wrong. Three rules: an origin ALREADY set is never touched (a re-import updates the current value, never the origin) ; an EMPTY column receives nothing (supplying nothing is not supplying blank) ; the call's layers go into BOTH versions.

So on a column whose origin was never captured, overwriting is FINAL in the row: only data_row_history still shows the previous value. The 28 799 origine layers already in the base are untouched — they are still read, served and protected; it is the mechanism that went, not the data.

Re-writing the SAME value changes nothing and captures nothing, by design. And it does not depend on how the row was created: a row appended through the MCP tool and one created through the REST face behave identically (measured 2026-09-04, both faces call the same store).

SINGLE (row): WITHOUT id = ADD a NEW row (new JSON keys auto-create columns, unless the table is CLOSED — see below); if the table declares a business key and your row carries a value that already exists, the business-key rule above applies. WITH key=<the declared key> = DESIGNATE the row by its key value: an existing value modifies that row and returns its _id, a new one creates it. WITH id = PARTIAL update of that row (only provided fields change). Returns the row (with _id/_created_at/_updated_at/_revision).

expected_revision (with id only) — Only when what you write was COMPUTED from a row you read (a list or text you re-send whole, a status chosen from the current one): pass that read's _revision. If the row changed since — any column, or its reservation — nothing is written and the call is refused with revision_conflict and the current revision: read again, recompute, write again. Omit it otherwise: writes to different columns never overwrite each other.

On a row you CLAIMED, address it by the _id of the row data_claim_next returned.

BATCH (rows = list of dicts): write them all at once — for importing a dataset without round-tripping each row through your context. If a business KEY is in effect (the key arg, else the datastore's declared schema.key): with key= the batch DESIGNATES — a row whose key value exists modifies that row, a new value creates one; without key= it ADDS, and the business-key rule above applies to values already in the table. Two rows of the batch with the same key value follow that rule either way; rows without a key are appended. Returns a summary {inserted, updated, count, key, ids, fusions?} — ids holds one _id per row sent, rank for rank. Use data_set_schema to declare a persistent key. For a FILE, never retype its rows here: oto_import loads it from where it is (link, Drive, project file), oto_upload_url takes it from your disk.

⚠️ An error on the way BACK (expired session, dropped connection, timeout) does NOT mean the write failed: it may have committed before the error. Read the row back (data_rows, by id or filtered on its key) before re-sending. Re-sending is safe with id, or with key= (or upsert=true) on a table with a business key: the row is designated, or merged; a keyless append re-sent creates a DUPLICATE.

⚠️ A table can be CLOSED by its schema (new_rows: "reject", next to its business key) — data_get_schema says whether it is. On such a table there is NO append at all: a write designating no existing row (no id, and no key value the table already carries) is REFUSED, single row and batch alike, and nothing is created — including a key value that is simply NEW. That is a deliberate setting of that table, not a platform rule. To make a row EXIST there, it is a schema move and not a write: data_patch_schema(datastore=…, new_rows="create"), your write, then data_patch_schema(datastore=…, new_rows="reject") to close it back.

origine_override=true belongs to an IMPORT, not to a write of your own: it declares that this call knowingly sets the origine layer — refused without it. ⚠️ For a real import, prefer donnees_d_origine=true, which sets the first version (origin) in one gesture; the override only says "I know what I am doing on this layer".

⚠️ A COLUMN can be LOCKED by the schema (readonly: true) — it holds a value someone put there, and an ordinary write that CHANGES it is refused by name (writing the same value again is fine, and <column>.comment always stays open for what another source says). The lock holds what is SET, not what is missing: a cell with no value (key absent, null or "") can be filled once; @empty ("searched, nothing") IS a value, and clearing one (null) is a change. To REPLACE it anyway, pass readonly_override=true ON THIS CALL. It is open to the OWNER of the table (you, your org or your team) or to whoever GOVERNS it — a table merely SHARED with you in write is refused, by design. It applies to this one call and nothing else: there is no schema setting to reopen and therefore none to close back. Every forced replacement is written to the call journal (row, column, replaced value) next to who called. ⚠️ That journal entry is BOUNDED: at most 25 replacements per call, each value cut at 120 characters (…, with was_len/now_len giving the original length). When it is cut short it says so (readonly_forced_bilan: "25 of N") — the count you read there is then a floor. The full history, whole values, is the row history: data_row_history.

⚠️ The datastore must EXIST first (create it with data_create_datastore); writing to an unknown datastore raises "datastore inconnu" — it is NOT auto-created.

⚠️ Address the table by its NUMBER. The reply carries ns_id — the table's number — and that is the form to pass as datastore: data_write(datastore=174, id=…). A name still resolves until 2026-11-08, then it is REFUSED.

datastore also accepts slot:<name> = the table BOUND under that slot name by the ACTIVE project (procedures reference tables as slot:name; the project maps the name via its links). Requires an active project + the binding — otherwise an actionable error, never a fallback.

ElevenLabs account, read-only: credits, voices and models. Nothing here spends credits; the generations are elevenlabs_act.

op:

• get_subscription — plan, credits used this period (character_count) against the allowance (character_limit), reset time (next_character_count_reset_unix), voice slots. Read it before a batch.

• list_voices — the voices the account can use (its own and the default ones): id, name, category, labels (accent, age, gender, use case), preview URL. Narrow with search, voice_type, category; page with next_page_token while has_more is true.

• get_voice — one voice (voice_id): labels, description, default settings.

• list_models — the models and what each can do (languages, maximum characters per request). A model id is what create_speech takes.

The two lists are tightened by default (a voice's samples, fine-tuning, sharing and verification records; a model's language and rate matrices), and the answer's projection names what was removed: full=true returns the raw records.

On the SHARED key (granted by oto, no key of your own) the reads are free, and get_subscription is refused: that balance is the instance's, not yours.

A restricted key may lack the permission a read needs (user_read, voices_read, models_read) even when it can generate.

Generate audio with ElevenLabs. EVERY call spends the account's credits (characters for speech, seconds for music and sound) and is not retried: read elevenlabs op='get_subscription' before a batch. On the shared key, text is at most 5,000 characters per call (text_too_long): cut a longer script into lines, or use your own key, which lifts the limit.

On the SHARED key (granted by oto, no key of your own), only the generations this instance serves run — by default create_speech; the others ask for your own ElevenLabs key.

The audio comes back as a signed URL (url, valid expires_in seconds, deleted after a day), never inline: download it right away.

op:

• create_speech — text read by voice_id (from elevenlabs op='list_voices'), with model_id, voice_settings, seed and language_code optional. previous_text / next_text make a line sound continuous with its neighbours when a script is read line by line. With timestamps=true the answer also carries words (each word's start and end, seconds) and the raw per-character alignment.

• create_music — a track from a prompt (length music_length_ms, 3,000 to 300,000) or from a composition_plan (sections, each with its duration and positive and negative styles), never both; respect_sections_durations, force_instrumental, seed optional. A prompt naming an artist or a copyrighted work is refused. Billed per minute of track (~900 credits a minute). On the shared key, when the instance serves it: the length is required (music_length_ms, or each section's duration_ms), the quota is checked against it.

• create_sound — a sound effect described in text; duration_seconds (0.5 to 30, else the model decides), prompt_influence (0 to 1), loop optional.

• create_transcript — the words said in an audio file (Scribe): source designates the file (a {"kind": "transit", "ref"} an oto tool returned, a project file, a URL…), language_code pins the language (else detected), audio_seconds its length. Returns text, language_code and words (each with its start and end, seconds). Billed per second of audio (~330 credits a minute). On the shared key, when the instance serves it: audio_seconds is required, at most 300 seconds and 1 MB of audio per call.

• create_voice_design — up to three previews of a voice described in voice_description, each reading text (or a text the model writes with auto_generate_text=true); each preview has its generated_voice_id and its own URL. Saving a preview as a voice of the account is not done here.

output_format is <codec>_<sample rate>[_<bitrate>], default mp3_44100_128; some (mp3_44100_192, pcm_44100) are paid plans only.

Report a usage signal about oto. signal='tool_feedback' = feedback on a tool you just used (target = the tool name ; kind = bug | misleading_doc | wrong_result | praise | other). signal='gap' = a use case oto could NOT do, call it whenever you wanted to act but no oto capability covered it (target = what you were trying to accomplish ; kind = missing_tool | missing_doctrine | missing_data | other). text = optional detail. A subject already reported (same workspace, signal and target) and still awaiting a decision is not duplicated: your report is added to it and the answer says its status and decision.

Declared greenhouse-gas inventories (BEGES, ADEME open data), keyed by SIREN.

~11,800 published inventories, ~7,000 of them from organisations under the legal obligation (art. L229-25: companies over 500 staff, communes over 50,000 inhabitants, the State). Each carries emissions per category, the reporting year, headcount band, and a link to the full report.

WHY THIS EXISTS ALONGSIDE foncier_conso_elec. Consumption data is indexed by ADDRESS or by IRIS: it describes a SITE that still has to be resolved to a company, and it does not locate everything — on one métropole, 25 rows and 10,621 MWh carry no usable address at all. Here the key IS the SIREN, so the inventory joins straight to the organisation. It reports DECLARED energy and emissions rather than metered consumption: a different fact, not a better one.

⚠️ The reporting year is not the publication year — an inventory published in 2026 may cover 2015. annee filters on the reporting year, which is the one that makes two organisations comparable.

⚠️ A missing emission post is not a zero. Totals sum only what was declared, and each category carries postes_declares / postes_absents so a low total can be told apart from a partial declaration.

Beyond emissions, each inventory carries contact (the declared energy officer — name, role, phone, e-mail; absent means MASKED at source, not unlisted), entites_consolidees (the SIREN of the declared consolidation perimeter — neither ownership nor directorships) and electricite, a MWh figure DERIVED from post 2.1 with the French average factor, marked certitude: "infere" and returned with that factor. It is the only public route to a consumption tied to a NAMED legal entity — grid data (Enedis by address, RTE by IRIS) is anonymous on both tiers.

⚠️ total is the number of inventories RETURNED, not how many exist: it saturates on limit (department 59 at limit=5 reports total 5, at limit=1000 reports 504). When it does, tronque is true and avertissement_troncature says so — never read a saturated total as a count.

Rendered transactions around an address (MCP App / interactive table), DVF+.

Visual flagship variant of foncier_comparables_adresse: geocodes the address, then renders the local median €/m² plus a sortable/searchable table of nearby DVF+ mutations (date, address, type, surface, price, €/m², distance — all property types). Use when the user wants to see nearby sales. For raw JSON use foncier_comparables_adresse.

Annual electricity consumption of French sites (open data, no key).

TWO GRID TIERS, and they are not interchangeable. reseau="distribution" (default) reads Enedis: consumption per ADDRESS, with the NAF division. reseau="transport" reads ODRE (RTE): the sites connected to the transmission grid, which are ABSENT from Enedis entirely — and they are the largest consumers in the country. Saint-Jean-de-Maurienne (73248) returns zero NAF-24 address on Enedis and 1,702,616 MWh on ODRE for 2023 — one IRIS (732480104) holding 3 delivery points, so that row comes back marked maille="iris_agrege", not as a single site. A "heavy electricity user" list built on distribution alone is a list without the heavy users: use reseau="les_deux" for a real one.

⚠️ THE TRANSPORT TIER IS A YEAR BEHIND. ODRE's newest millésime is older than Enedis's (2023 against 2024, measured 2026-09-09). Asking ODRE for a year it does not carry returns ZERO rows for the whole tier — which reads exactly like "no transmission-connected site here" while it means "that year does not exist yet". That zero is now NAMED in avertissement_millesime: read it before concluding. Nothing is invented to fill the hole — an absent year stays absent, it is only said out loud.

TWO GRAINS, and maille governs BOTH tiers with the same meaning: "site" = one row is one site. On DISTRIBUTION, Enedis publishes ONE ROW PER ADDRESS AND PER NAF DIVISION, so maille="ligne" (default) returns rows, and thresholding them one by one MISSES sites whose divisions are each below the bar but whose total is above it; maille="site" sums an address's divisions and applies min_mwh AFTER the sum — the grain almost every caller means. A site then carries naf2_principal, naf2_detail and multi_naf2. On TRANSPORT, "site" keeps only the IRIS that hold a single delivery point, and "ligne" also returns the aggregated ones. Filtering those out is how a query for the largest consumers returns the small ones — see maille below.

Rows Enedis publishes without an address are real consumption that cannot be located: they are never returned as sites, and counted in lignes_ignorees / mwh_ignores instead of being silently dropped.

Energy performance diagnostics (DPE, ADEME open data) — raw records around an address, or the label distribution of a commune. ~15M dwellings, since July 2021.

op:

• "adresse" (default): geocodes the address (BAN), returns raw DPE records within radius_m metres, nearest first. Each: etiquette_dpe (A–G), etiquette_ges, conso_ep_kwh_m2_an, surface_habitable, annee_construction, type_batiment, adresse, date_dpe, distance_m, lat/lon. Needs adresse.

• "stats": DPE label distribution (A–G) for a commune — aggregated view of energy performance across all its dwellings. Needs code_commune.

• "tertiaire": the NON-residential stock — hospitals, schools, offices, shops, restaurants (~560k diagnostics). The other half of the building stock, and the one electricity-consumption data describes without qualifying: Enedis says HOW MUCH a site consumes, this says WHAT the building is (ERP sector, SHON surface, label). Coordinates come back already in Lambert 93 under lambert_x/lambert_y, so a row matches an establishment with no intermediate geocoding. sans_position counts the ungeocoded ones — they are never placed at the centre of their commune. Needs code_commune or departement.

Real-estate transactions from DVF+ open data (Cerema, since 2014) — price stats for a commune, or the raw mutations of a commune / around an address.

op:

• "prix_m2" (default): price stats (€/m²) for a French commune. Median/mean/min/max €/m² + per-year breakdown, on clean mono-bien sales (one Appartement or Maison per mutation; outliers <100 or >50000 €/m² filtered). Use to value a property by comparables. Needs code_commune.

• "comparables": RAW transactions for a commune. NOT filtered: ALL property types (flats, houses, land, dependencies, mixed-use, commercial) and ALL natures (sale, VEFA off-plan, auction, exchange) — the agent decides the use (valuation, land analysis, market volume…). For a clean median €/m², use op="prix_m2" instead. Needs code_commune.

• "comparables_adresse": RAW transactions around a PRECISE address. Geocodes the address (BAN), returns ALL mutations whose parcel lies within radius_m metres (distance to nearest parcel vertex — robust to multi-parcel goods), nearest first, each with distance_m. NOT filtered by property type/nature; median_prix_m2 is computed on residential mono-bien rows only (indicative). Needs adresse.

Each raw row (both "comparables" ops): date_mutation, nature_mutation, valeur_fonciere, type_bien (raw DVF+ label) + type_local (set only for residential mono-bien, else null), surface_reelle_bati, surface_terrain, prix_m2 (null if not computable), nombre_locaux, vefa, id_parcelle(s), adresse (reverse-geocoded BAN), lat/lon. Most recent first (nearest first for "comparables_adresse").

⚠️ Dense communes (Paris arrondissements) can time out on a FIRST call. The public DVF+ API takes 20 to 35 s to serve the first page of one arrondissement-year it has not served lately (measured 26/10/2026: 75115, 75116, 75117), beyond this tool's wait; once served, the same query answers in ~1 s. Each year warms up on its own, so a few calls may be needed. A timeout here says nothing about the data: retry once or twice before concluding.

With with_dpe=True (op="comparables_adresse" only), each sale is enriched with ADEME energy data: a HOUSE gets its matched dpe (etiquette + dpe_match confidence by proximity & surface); a FLAT gets dpe_immeuble (the building's DPE list — NO 1:1 match, as DVF and DPE share no dwelling key).

Geocode a French address → coordinates, canonical label, INSEE code.

Returns candidates (label, score, lat, lon, citycode, postcode, type), best first. The BAN label is a canonical address key (two spellings converge on one point). type grades the match: housenumber (exact door) > street > locality > municipality — a locality answer to a numbered query is NOT the address.

Postcode fallback: SIRENE addresses often carry the commune's generic postcode (80000 Amiens) while the BAN indexes the real one for that stretch (80090). The query then yields only a low-score locality. When the query carries a street number and no housenumber comes back, this retries WITHOUT the postcode (both the argument and the one written in the address) — those candidates are tagged relaxed="postcode". If that still finds no housenumber, every candidate is tagged warning="no_housenumber_match": treat them as approximate.

The reverse direction (point → nearest address) is foncier_site(op="adresse").

Declared industrial installations (Géorisques): ICPE registry, or IREP emissions.

op="installations" (default) — the ICPE registry by siret or code_insee: regime (Déclaration / Enregistrement / Autorisation), IED, Seveso, activity state, geolocation, DREAL service, latest inspection reports, and rubriques (nomenclature number, nature, authorised quantity) with rubriques_energie — those whose very activity IS energy use, each with a plain reading: 2910/3110 combustion, 2920/2921 cooling, 4735/1185 industrial refrigeration. Long sheets are capped at 10, energy ones FIRST, and rubriques_tronquees says so. Detects HEAVY INDUSTRIAL SITES when power consumption is masked in Enedis open data — a SOURCED "big consumer" presumption (cite the codeAIOT), NOT a consumption: an authorised quantity is m³ or MW of plant, never kWh.

op="emissions" — the IREP registry: declared emissions per ESTABLISHMENT, with its SIRET and coordinates, by departement, code_insee or siret. The complement to foncier_beges: a GHG inventory covers a whole ORGANISATION and never says where, IREP names WHICH site weighs — and therefore which address to call on. ⚠️ 89% of the registry's quantities are the string "< seuil" (declared BELOW the reporting threshold): they come back as quantite: null with sous_seuil: true, never as zero, sorted after the known quantities. ⚠️ CO2 comes in three labels — fossil (the default), biomass, and the total that sums both; reading the total as fossil inflates a site that burns wood.

A parameter the chosen op cannot honour is REFUSED, never silently dropped. fields keeps only these keys in each record; the envelope always stays.

Reachable-area (isochrone / catchment) polygon around a point, via IGN.

The travel-time zone one can reach from (lat, lon) — the primitive for a retail catchment area. Give EITHER minutes (time budget) OR metres (distance budget), not both. mode: "pied"/pedestrian or "voiture"/car. direction: "departure" (area reachable FROM the point) or "arrival" (area FROM WHICH the point is reachable — differs by car with one-ways).

Returns the GeoJSON geometry (Polygon of the reachable area) plus its centroid and bbox. To answer "who is > N min away from X", compute an isochrone around each X and test population/points against the polygons — this tool returns one zone; the coverage analysis is the caller's compose step (e.g. cross with urba_iris population). Geocode the address first (foncier_geocode → lat/lon).

Building/urbanism permits (Sit@del, SDES) for a commune, department or APPLICANT.

Live query on the DiDo API (server-side filter) — no bulk download. National register of urban-planning authorizations (PC/PA/DP) since 2013, monthly refresh. A scope is REQUIRED — code_commune, dept or siren/siret — because a national scan is huge. siren needs NO geography: "every permit filed by this company", France-wide, in one query (due diligence on a company's projects).

Three files, pick with kind:

• "logements": permits creating housing (developer/promoteur core).

• "locaux": non-residential premises (offices, retail, industry, warehouses — the big-roof PV / commercial prospecting file; carries destination_libelle and sp_finale_estimee_m2).

• "amenager": land-development permits (subdivisions, large layouts).

Each permit is normalized: identity (num_dau, type, etat), commune/dept, deposit year, real dates, applicant (demandeur: SIREN/SIRET/denomination/APE — ~35 % empty by GDPR for natural persons, this is the diffusion rule not a data gap), terrain address + cadastral parcels, surfaces.

To find the permits on a given cadastral PARCEL there is no server-side filter (DiDo stores up to three section/number pairs per permit and ANDs them): scope by commune, then match the parcelles key of the returned permits.

Rendered PRICE STATS (€/m²) for a commune (MCP App / interactive card), DVF.

Visual flagship variant of foncier_prix_m2: renders the headline €/m² figures (median/mean/min/max) and a per-year breakdown table. Use when the user wants to see a commune's price levels. For raw JSON use foncier_prix_m2.

Buildings and the SIREN of their legal-entity owner (BDNB, CSTB).

The only public source that ties a PLACE to a LEGAL ENTITY without address matching: the link comes from the land registry, so it is exact. Works both ways — code_commune (+ emprise_min) lists a town's large buildings with their owner, siren lists every building a company owns.

Each record also carries floor footprint, use, construction year, DPE class and the building's professional electricity and gas consumption (kWh/year, 2020 vintage), so a site is qualified without a second call.

⚠️ ONLY legal entities published in MAJIC are here. Natural persons — family SCIs, farmers, craftsmen — are anonymised at source by the tax administration and absent entirely: a missing building is NOT a building without an owner. Every response repeats this in couverture_partielle.

⚠️ The upstream API serves 10 rows per call, so limit above 10 costs one round-trip per additional 10 — requetes says how many were made. total is what was RETURNED, never what exists: the source publishes no count.

⚠️ No offset: only the FIRST limit rows are readable, in the source's own order (ascending owner SIREN, not size). On a large commune or a department, tronque: true says more exist and you hold the smallest SIRENs, not the biggest buildings — narrow with emprise_min, or go commune by commune, before concluding on a territory.

What a point (lat, lon) carries — cadastral parcel, built footprint, nearest address, solar yield. Geocode the address first (foncier_geocode).

op:

• "parcelle" (default): cadastral parcel at the point (API Carto IGN), or null. Returns idu (unique id), commune, INSEE code, section, numéro, area (contenance_m2) and GeoJSON geometry. Use to identify the land unit under an address.

• "bati": built footprint on that parcel (IGN BDTOPO V3) — ground area, real CES, uses, heights. Resolves the cadastral parcel at the point, then sums BDTOPO buildings whose centroid falls inside it. ces_reel = built area / parcel area (low CES in a dense area = under-developed land signal). Returns an error key if no parcel is found at the point.

• "solaire": annual solar yield (kWh) for a PV system of kwc kWp at the point, via PVGIS (JRC). Picks optimal tilt/azimuth for a rooftop install. Returns physical data only (productible_kwh_an, irradiance, losses, optimal angles) — no tariff or business assumptions. Null if inputs invalid or PVGIS unavailable.

• "adresse": reverse-geocode the point (BAN) → nearest known address, or null.

Rendered SITE sheet for a French address (MCP App / interactive card).

Visual flagship variant of foncier_geocode + foncier_parcelle + foncier_bati: geocodes the address (BAN), resolves the cadastral parcel and built footprint, and renders ONE card — canonical address, parcel id/section/number, area (contenance), real CES, buildings. Use when the user wants to see a parcel/ site summary. For raw JSON, use the individual foncier_* tools.

Fetch a single company agreement by its DILA id (ACCOTEXT…) or numero (T…).

Returns METADATA (who, when, themes, branch…). The body text is NOT in the local index — it is fetched per act from Légifrance, so ask for it with include_text=True (or call fr_accords_text, which also paginates long agreements). Without that, this tool cannot tell you what an agreement SAYS — and what it says is often the point: theme codes are declarative and incomplete (cf. fr_accords_search), so a health clause is regularly found only by reading.

Search French company collective agreements (accords d'entreprise, ACCO).

Neutral primitive returning raw rows — compose your own need via filters, sort and per-company reduction.

⚠️ themes PROVES PRESENCE, NEVER ABSENCE. Theme codes come from DILA's own indexing of the filing: declarative, uneven, and demonstrably incomplete. Measured case — CAFES BIBAL VENDING (SIREN 345255087) filed the SAME kind of agreement twice: the 2019 one is coded 111/112, the 2025 one is coded 081-084 only, yet its article 5 ("Régime de remboursement complémentaire de frais de santé et de prévoyance") re-institutes health AND pension for 4 years. Filtering on 111/112 there returns the 2019 act alone — reading "no recent act" off that is a FALSE NEGATIVE produced by the source, not by this tool. Health clauses routinely travel inside an agreement titled "égalité professionnelle" or "NAO", and get coded accordingly.

Consequence for prospecting: to assert a company's scheme is DORMANT, theme codes are not enough — search by siren WITHOUT themes, then read the recent acts with fr_accords_text (health sections carry very stable headings: "frais de santé", "régime de prévoyance", "complémentaire santé"). Use themes to FIND candidates cheaply, the text to CONFIRM the ones you are about to act on.

Common recipes:

• Who just renegotiated their health/pension scheme (candidates, not an exhaustive set): themes=["111","112"], nature="AVENANT", sort_dir="desc".

• Does THIS company have a health/pension agreement, and when: search by siren WITHOUT themes, sort_dir="desc", then read the recent acts.

• PROSPECTING AUTONOMOUS SMEs (skip group subsidiaries, whose insurance is decided at HQ): exclude_categories=["GE"]. 26% of the companies filing a health/pension agreement are GE — filtering here is one query instead of a per-company qualification pass.

Full text of a company agreement (accord d'entreprise) by its DILA id — fetched on demand from Légifrance (the local ACCO index only has metadata). Chain after fr_accords_search / fr_accords_get.

Returns metadata + texte (extracted from the filed docx; may be empty when no integral version was published) + texte_chars/offset/ next_offset + permalien (verifiable link, 404s honestly when the text is absent) + lien_construit (best-effort Légifrance pattern, not guaranteed to resolve).

List the agreement theme codes present in the database (code → label → count). Discovery helper so you can pick themes for fr_accords_search.

The counts say how often DILA APPLIED a code, not how many agreements cover the topic — the indexing is declarative and misses clauses (see the warning on fr_accords_search).

COMPLETE record of an aid (source of truth after re-ranking fr_aides_search — full purpose/conditions/amount, funders, contacts, official sources). Decoded text (HTML entities cleaned) and cache_indexation reduced to its useful extracts (natures, funders, territories, contacts, sources).

Shortlist of French public aid (grants, loans, guarantees, calls for projects) for a company/project — data.aides-entreprises.fr database (State reference, ~2,400 active aids, updated daily, the database prunes expired ones).

Returns the DETERMINISTIC filter (geo by hierarchy commune→dept→region→ France/EU + headcount band + nature + deadline) with the measured funnel (funnel). ⚠️ SECTOR relevance can NOT come from the database (its profile tagging is 99% over-inclusive) nor from lexical scoring: it is UP TO YOU to re-rank the shortlist by reading name/purpose. Anti-hallucination rule: keep only ids, then re-render each record via fr_aides_get(id) — NEVER rephrase name/purpose from memory, quote literally.

Official INSEE « Avis de situation au répertoire SIRENE » PDF of an establishment — the signed 1-page administrative document, for a dossier.

Unlike fr_siret (JSON identity, needs the SIRENE key), this wraps INSEE's PUBLIC avis endpoint (no key) and returns a directly-fetchable URL to the PDF (availability is checked). The caller downloads the URL to get the file.

Fetch one INPI/BCE annual filing with full financial ratios.

Returns: CA, EBE, EBIT, résultat net, marge EBE, autonomie financière, taux d'endettement, liquidité, vétusté, BFR, rotation stocks, crédit clients/fournisseurs, couverture intérêts. Use fr_bilans first to discover available dates.

List available INPI/BCE annual filings for a SIREN.

Returns exercise dates, bilan type (C=complet, S=simplifié, K=consolidé), confidentiality status, and turnover. Typically 3-9 years of history.

⚠️ items holds only the filings whose figures are USABLE (the annual-accounts dataset): a confidential or not-yet-keyed filing is absent from it, so the first item is NOT necessarily the latest filed year. depots_sans_donnees names the filings published in BODACC (accounts filing notices, dpc) whose closing date is not in items — filed, but without usable figures here — and avertissement says when one of them closes AFTER the most recent item: the figures you hold are then older than the company's latest accounts. If BODACC fails, the cross-check is missing and partial_errors says so.

Directors declared at the French registry (RNE), for one company or a LIST — sirens=[…] (max 100) returns {entreprises, count, obtenues, en_echec, erreurs, not_found, synthese}, one entry per SIREN in input order.

⚠️ An empty dirigeants has THREE meanings, told apart by registre: the SIREN is unknown (error: "not_found"), the legal form is not registered so it declares nobody (hors_registre — association, commune: the emptiness says nothing about the company), or the company is registered with nobody on file (attendu). Never read an empty list as "no director" without reading registre. personnes_physiques counts the NAMED natural persons — a company whose only director is another company scores 0.

⚠️ count counts the records OBTAINED, not the lines returned — en_echec and erreurs name what is missing, at the top level. ⚠️ An error other than not_found is an upstream failure, not a fact about the company — and it is RETRYABLE.

A batch of 50 where 21 calls failed returns count: 29, en_echec: 21 and names those 21 SIRENs in erreurs — at the top level, like not_found, because a hundred-line list is not re-read to find them. Reading count and not_found alone used to say "50 records, none missing" while 21 companies silently dropped out of the deliverable. The batch paces itself and retries the upstream quota (429, honouring Retry-After), so what reaches you has already been given a second chance; a SIREN still in erreurs says the upstream is busy, never that the company has no director. Ask for those SIRENs again, later or in a smaller batch.

List calls for projects / competitions / AMI (calls for expressions of interest).

List agenda events (meetups, conferences), most recent first.

List financing schemes (with type, amount, stage, eligibility).

List French Tech Central bookable scenarios (RDV with state correspondents).

Get a single directory company by its slug.

List community members (named people fiches).

Search the French Tech ecosystem directory (~694 companies).

Returns companies with name, pitch, director, email, phone, website, city, sectors, headcount, turnover, needs. A rich B2B prospecting dataset.

List BODACC legal events for a company: creations, modifications, sales, collective proceedings, annual filings.

Check BODACC legal events for MANY companies at once (e.g. screen 700 SIRENs for collective proceedings) — batched into a few upstream requests.

Deterministic: returns a flat annonces list — one row per announcement AND per requested SIREN it names (a sale names both parties: requesting both gives two rows, same bodacc_id; a non-requested party never shows up). Each row's partie is that SIREN's role: sujet, ancien_proprietaire, ancien_exploitant, nouveau_titulaire, or indeterminee (the announcement does not say — do not guess). synthese counts on the requested SIRENs (sirens_avec_annonce, sirens_sans_annonce, par_partie, …; annonces_total = distinct announcements, lignes_total = rows).

texte is the announcement's wording for EVERY family (jugement, modification or sale descriptif… — texte_source names the field); rows the source serves without it are counted in annonces_sans_texte. It does NOT decide whether a company is in proceedings, nor what a modification changed (a director or just the auditor): read texte and judge per SIREN — counting announcements is not a signal.

Full company profile by SIREN: identity (siège, directors, NAF code with its rév. 2 label activite_principale_libelle, employees) + 7 top financial ratios from the latest INPI/BCE filing

• recent BODACC legal events. Aggregates 3 open data sources in parallel. Use this as first call when investigating a company.

⚠️ latest_bilan = LITERALLY the last filed fiscal year, which does not necessarily carry revenue — a simplified balance sheet has no "total revenue" box. For revenue, go back through the years: fr_bilans(siren) returns them from most recent to oldest with their chiffre_d_affaires, and you must take the first one that carries one. Do not conclude "no revenue" from latest_bilan alone. Seen on Norauto: last year (simplified) silent, €974,718,176 the year before.

⚠️ identity.etat_administratif is the SIRENE register's state, which does NOT follow collective proceedings: a company whose liquidation was closed years ago can still read "A". When the BODACC events read here (the 10 most recent) carry a judgment closing a liquidation, procedure_collective_cloturee gives it (nature, date) and etat_administratif_avertissement flags the contradiction. Older proceedings: fr_events(siren, famille="collective").

BATCH: pass sirens=[…] (max 20 per call, chunk beyond) to qualify a LIST in one call — returns {profiles: […], count}, one profile per SIREN in input order; per-SIREN failures degrade to {error, siren} without failing the batch. For bulk HQ addresses only (no financials), fr_stock_enrich is cheaper.

latest_bilan is trimmed to 7 B2B-relevant ratios (CA, résultat net, EBE, marge EBE, autonomie financière, taux d'endettement, liquidité). For the full ratio set, call fr_bilan(siren, date_cloture).

Resilient to per-source failures: a timeout or error on INPI (bilan) or BODACC (events) degrades gracefully — the available blocks are returned and the failing sources are listed under partial_errors. Only an identity failure (the keystone source) fails the whole call.

Ownership chain of a French company — qualify its INDEPENDENCE, or inventory a group.

⚠️ confiance="indeterminee" (no parent reached) does NOT mean "independent": the beneficial-owners register has been closed to the public since 31/07/2024. motifs_indetermination says why — including sans_siren: legal-entity officer without a SIREN (often foreign), returned in exclus.sans_siren (name, capacity). No parent is an ANSWER. ⚠️ Going down, the upstream caps at 25 results/page and 10,000 in total: candidats_tronques=true signals a sample, not an inventory.

op:

• "ascendant" (default): goes up the legal-entity officers, BREADTH-first (a company often has several parents at the same level). Returns {tetes, liens, confiance, cycle, tronque}.

• "descendant": entities controlled by this SIREN — one call instead of N.

Why: categorie_entreprise (PME/ETI/GE) is computed by INSEE at the GROUP level, never at the entity level — a tiny subsidiary comes out as "GE".

confiance per link: forte = the capacity implies ownership (limited partner / unlimited liability) · moyenne = corporate office (chair, director, manager): governance proven, control suggested · faible = neither (GIE member, liquidator) · inconnue = unlisted capacity. Only forte and moyenne are traversed. Statutory audit is excluded (commissaire OR contrôleur, counted in exclus).

Fetch the headquarters (siège) of a company from INSEE SIRENE.

Search French companies — returns identity, HQ, NAF, employees, directors, finances, matched establishments. At least one filter required.

⚠️ Enumeration capped at ~10,000 (page × per_page, per_page ≤ 25): the API truncates without error beyond that. To enumerate a large set exhaustively ("all companies in sector X in region Y" when there are tens of thousands), switch to fr_stock_search (SIRENE parquet, no cap). This tool remains the right choice for searching/qualifying (indexed, fast, rich filters) as long as the result stays under ~10k.

⚠️ Geographic filters (departement, code_postal, commune) match ANY establishment, NOT only the head office (siège). To target companies whose SIÈGE is in a département, use fr_stock_search(departement=…, sieges_only=True).

⚠️ ca_min/ca_max do NOT qualify a company's size. The filter applies to an amount whose unit varies by filing (euros or thousands, sometimes from one year to the next for the same company) and whose 0 means "not declared" — so any upper bound brings back en masse companies whose revenue is unknown, which biases toward the LARGEST. Measured: tranche_effectif_salarie=51,52,53 & ca_max=400000 returns 12 results, all large companies, no true positive. To target by size, use tranche_effectif_salarie or categorie_entreprise. The finances block of the results carries the same caveats, flagged line by line (alerte) — see finances_avertissement.

Spoken legal forms: people say "the SCI Untel", but the register rarely writes the form into the name — so a query like "SCI ASC" only matches companies literally NAMED that. On page 1, this tool detects such a prefix and ALSO runs the name alone filtered on that form, appending the extra hits (flagged matched_by="legal_form") and reporting what it did under legal_form_retry.

Fetch a French establishment by SIRET (14 digits) from INSEE SIRENE.

Batch headquarters enrichment: pass a LIST of SIRENs, get each one's head-office address in a SINGLE scan. This is the bulk strength of the stock parquet — far faster than N calls to fr_get/fr_stock_siege (one scan vs one network round-trip per SIREN).

Use it to enrich a list of prospects (from fr_search, a Folk export, Unipile contacts…) with siège address/NAF before pushing to a CRM.

Returns {siren: {street, postal_code, city, code_commune, naf, raison_sociale, categorie_entreprise, denomination, status, ...}} ; SIRENs without a known siège are omitted. raison_sociale is the company name (legal-unit stock, null for a sole trader); denomination is the establishment's USUAL name, empty for most.

All establishments (siège + secondaires) of a French company from the local SIRENE stock parquet.

Use this to map subsidiaries / branches / retail locations of a group. E.g. all Carrefour Express locations for a holding's SIREN.

Multi-criteria search over the SIRENE stock parquet (INSEE local snapshot).

All filters are AND'd. Returns paginated establishments matching, each with raison_sociale and categorie_entreprise from the legal-unit stock. denomination is the establishment's USUAL name, empty for most (~88 %): the company name is raison_sociale.

Use cases:

• All NAF 4711F (supermarkets) in Marseille (code_commune=13201 or code_postal=13001)

• All "Carrefour Express" branded locations (enseigne='carrefour express')

• All "Intermarché" supermarkets in a département (enseigne='intermarché', naf='47.11F', departement='26')

• Companies of 100-499 employees HEADQUARTERED in a département (departement='13', sieges_only=True, tranche_effectifs='22,31,32') — the clean way to enumerate ETI/large-PME by real HQ location + size, server-side.

Headquarters (siège) of a French company from the local SIRENE stock parquet (INSEE, monthly snapshot).

Faster than the live INSEE API for batch enrichment. Returns the latest active siège (etablissementSiege=True). None if SIREN unknown.

Fetch a specific establishment by SIRET (14 digits) from the stock parquet.

Fetch a single BOAMP tender by its ID.

French public procurement — tender NOTICES (BOAMP) or AWARDED contracts (DECP).

op="notices" (default): the notice — a need, a deadline. op="awarded": the OUTCOME — winner SIRET, amount, notification date, duration, procedure. The only source that says who actually wins the contracts of a territory: the real competition, not the assumed one.

Shared: query (text in the subject), departement, date_from. For awarded, departement is matched as the PREFIX of the place-of-performance code (a department "59" or a postcode — the code type varies per contract). Notices only: descripteur, date_to, type_marche. Awarded only: titulaire_siret (every contract won by that establishment, alone or in a consortium), acheteur_siret (every contract passed by that buyer). A parameter the chosen op cannot honour is REFUSED, never silently dropped.

awarded reads two regimes split at the notification date — the 2022 decree from 2024 on, the 2019 decree before — and each record carries its arrete. ⚠️ Since 2024 the source publishes NO names at all (buyer, place, winners); before 2024, never the main winner's. Resolve them from their SIRET with fr_siret: nom/denomination: null is the source's shape, not a gap.

fields keeps only these keys in each record; the envelope (counts, pagination) always stays.

Submit an ASYNC enrichment job (phones + emails) via FullEnrich (waterfall 20+ providers).

Returns immediately with an enrichment_id — the job runs server-side for ~30s to 4min. THEN call fullenrich_result(enrichment_id) to collect (first poll after ~30s, then every ~20-30s until status FINISHED).

Collect the result of a FullEnrich job submitted with fullenrich_enrich_linkedin.

Single status check, returns immediately. Returns {done: false, status, retry_after_s, next_step} while the job runs — call again after retry_after_s seconds (jobs typically finish in 30s-4min). Pass the submitted_at the submission returned: past 20 minutes the answer adds verdict: "still_running_after_20_min" and says to STOP polling — do not resubmit the same contacts, it would be billed twice. A job that will never finish (canceled, unknown or expired id) is a named refusal, not a status to poll. When done, returns {done: true, status: "FINISHED", profiles} with one entry per submitted contact: {found, linkedin_slug, full_name, title, company_name, phones[], work_emails[], personal_emails[], location}. Reading a result never consumes the platform quota (the submission does).

⚠️ ACTS on a GitHub repository: creates a branch. Reading the repository and its branches is github_repos.

op='create_branch' is how a pull request is opened without a shell, in three steps:

1. github_act(op='create_branch', branch='fix/x'), from ref;

2. write the files with github_files(op='write', branch='fix/x', …) — branch is REQUIRED there, otherwise the commit lands on the default branch; GitHub refuses a write to a branch that does not exist;

3. github_pulls(op='create') with the new branch as head.

⚠️ An existing branch is refused (422), never moved.

GitHub Actions — workflows, runs, jobs, logs and artifacts.

Read first: runs then jobs then logs is the normal path to understand why a pipeline failed.

⚠️ Read status AND conclusion: a completed run may have failed, and conclusion stays null while the work is not finished.

⚠️ op='dispatch' triggers a real run — thus potentially a build, a publication or a deployment. It is dry-run by default: dry_run=false to really trigger. The workflow must declare workflow_dispatch, otherwise GitHub answers 404 — here a 404 means "not triggerable", not "does not exist". The response does NOT return the created run: find it by listing the runs right afterwards (there is a short delay).

⚠️ rerun reruns the WHOLE run (billed minutes, possible redeployment); rerun_failed only replays the failed jobs — cheaper and less risky. cancel interrupts work in progress.

⚠️ logs and download return an ephemeral signed URL (~1 minute), to be downloaded without an authentication header — the storage refuses a doubly authenticated request. None signals expired logs or a stale artifact (90 days by default).

GitHub — read and write repository files.

op='read' returns the decoded TEXT; op='list' returns the contents of a directory; op='readme' finds the README whatever its name.

⚠️ Beyond 1 MB, GitHub serves the metadata without the content: the read then says so by name rather than returning an empty string that would read as an empty file.

⚠️ Writing over an existing file REQUIRES its sha (the blob's, returned by op='list' or by a read). Without it, GitHub answers 409: it is its concurrency control, which guarantees we replace the version we read and not a change that arrived in the meantime. Omitting it is normal for a CREATION.

⚠️ Each write is a real commit on the targeted branch (branch, or the default branch) — visible in history, and attributed to the token holder.

GitHub — a repository's issues, their comments and their labels.

⚠️ At GitHub, a pull request IS an issue: the API returns the two mixed together. op='search' therefore drops PRs by default — without which "how many open tickets?" gives a wrong number, often by a lot. include_pull_requests=true returns the API's raw response. This sorting happens after pagination: a page of 30 of which 12 are PRs returns 18, which is normal.

Conversely, and this is useful: these same operations work on a PR by passing its number — thread comments, labels, assignments and milestones are shared by both.

⚠️ op='update' with labels or assignees REPLACES the list. To add without overwriting: add_labels / assign.

⚠️ op='assign' silently ignores an account without write access to the repository: the response comes back as a success without having assigned it. Compare the returned list with the requested one.

⚠️ Creating an issue or a comment notifies the repository's watchers and anyone mentioned. There is no issue draft at GitHub.

GitHub — who is in the organization, in a team, on a repository.

⚠️ Three memberships look alike and are not the same thing: member of the ORGANIZATION, member of a TEAM, collaborator on a REPOSITORY. Removing someone from one does not remove them from the others — this is the most frequent error here. remove_member leaves the organization (and all its teams); remove_team_member only touches the team; remove_collaborator only touches one repository, and does not remove access inherited from a team.

⚠️ members only shows what the token is allowed to see: without the organization scope, only PUBLIC members come out — a shorter list, with no error. It is therefore not a census.

⚠️ set_membership and add_collaborator send an invitation: access is only effective once accepted (pending until then). role='admin' on an organization gives owner rights.

⚠️ permission returns the EFFECTIVE level (team inheritance included), which the list of direct collaborators does not say.

op='me' (the token's account) and op='rate_limit' (the quota state, without consuming them) are for diagnosing before blaming a name.

GitHub — pull requests: diff, reviews, reviewers, merging.

A PR's THREAD comments, labels and assignments go through github_issues with the same number — this is intended on GitHub's side. What lives here is what is specific to a PR: the diff, reviews, line-by-line comments, and merging.

⚠️ A merged PR is closed: there is no merged state. To tell them apart, read merged_at (null = closed without merging), or op='merged'.

⚠️ mergeable may be null on op='get': GitHub computes it in the background on the first call. null means "not known yet" — ask again, above all do not read it as "not mergeable".

⚠️ op='merge' writes to the target branch and cannot be undone with one click. The three methods differ: merge adds a merge commit, squash squashes the branch into a single commit, rebase rewrites the commits. Passing sha protects against the race: if the head moved since the read, GitHub refuses instead of merging something else.

⚠️ A review without event stays PENDING (PENDING): nothing is published, nobody is notified, and it is only visible to its author. This is useful for preparing, and a trap when you thought you were approving. APPROVE can unblock a protected merge: it is an act of governance, not a comment.

⚠️ op='files' is capped at 3,000 files and omits big patches; op='commits' at 250. A massive PR is returned incomplete, without error.

GitHub — repositories: profile, branches, commits, tags, releases.

The entry point for getting oriented in a repository before reading its code (github_files) or its tickets (github_issues).

⚠️ A 404 on a private repository almost always signals a token without the right, not a wrong name.

⚠️ op='commit' returns the commit WITH its diff: GitHub caps at 300 files and truncates beyond that without saying so in files — compare to stats to notice.

⚠️ op='latest_release' ignores drafts AND prereleases: it is not the last tag created.

op: mine | org | user (repository lists) · get · branches · commits · commit (with diff) · compare (base…head) · tags · contributors · languages · topics · releases · release · latest_release · create_release · update_release.

GitHub — search: repositories, code, issues/PRs, accounts, commits.

q takes GitHub's qualifier syntax, passed as-is: repo:, org:, language:, is:issue / is:pr, state:, in:file…

⚠️ Cap of 1,000 results, whatever total_count announces. This counter is an estimate of the corpus, NOT the number of retrievable rows: beyond that, GitHub answers 422. The response therefore carries a computed troncature, which is also true when GitHub gave up the search midway (incomplete_results) — two causes invisible otherwise.

⚠️ Code search has its own rules, and they explain most of the "why doesn't it find it?" questions: only the default branch is indexed, files larger than 384 KB are not, and at least one real term is needed — repo:x alone is not enough. It does not return the file's content: read it afterwards with github_files op='read'.

⚠️ Its own, low usage limit (~30 requests/minute), an order of magnitude below the rest of the API.

The user's Gmail mailbox — READ it, or prepare a DRAFT. Nothing here sends, archives or deletes: that is gmail_act, the tool your client asks you to confirm.

op:

• "search" (default): search with Gmail query syntax. query e.g. from:foo@bar.com is:unread newer_than:7d. Returns {messages: [{id, threadId, from, subject, date, snippet, labelIds}], count}.

• "get": a full message (headers, body, attachment metadata) by message_id.

• "attachment": the CONTENT of an attachment of message_id, by filename (from op="get"; index breaks a tie between same-named ones). Small text (JSON/CSV/Markdown/ plain, ≤256 KB) comes back inline as {encoding: "text", content}; a PDF as its extracted text plus raw_url, a short-lived signed URL to the original (a scanned or protected PDF has no text: text_unavailable says why); an .xlsx as CSV per sheet (sheet, max_rows — default 200, max 5000; if truncated, ask one sheet or raise max_rows; raw_url always gives the original file). An image (png/jpeg/gif/webp, ≤3 MB) and a scanned PDF whose pages are JPEG (≤5 pages, ≤3 MB) come back as IMAGE CONTENT you can look at — nothing stored. Anything else, or over those caps, as a short-lived signed URL {encoding: "url", url, expires_in} (image_unavailable says why an image or scan was not served as image).

• "drafts": the drafts. Returns {drafts: [{id, message_id, to, subject, date, snippet}], count} — a draft id is what gmail_act(op="send", draft_id=…) sends.

• "draft": WRITE A DRAFT — a new message (to, subject, body) or a threaded reply (reply_to). It does NOT leave the mailbox. Returns kind: "draft", its id and web_link (the draft opened in Gmail web, to note where it waits): send it with gmail_act(op="send", draft_id=<id>) once the person agrees. ⚠️ A fresh draft can be MISSING from an already-open Gmail tab for a while (the API has it, the client view lags): tell the person to reload or search in:drafts.

• "accounts": the Gmail accounts this call can use — the user's own, then the mailboxes an admin shared with their team or organization. Returns {accounts: [{email, is_default, shared}]}; pass an email as _account to act on that mailbox. An unknown email is refused, never replaced.

The sending account's Gmail signature is appended by default, after -- (none added when the signature already opens with its own), like the Gmail web client does (the API never adds it on its own) — so do NOT write a sign-off block of your own in body. signature in the answer says what happened: "appended", "none_configured" (the account has no signature — nothing was added), or "disabled" (sign=False).

ACT on the user's Gmail mailbox — ⚠️ every op here takes effect: a mail LEAVES, a message moves. Reading and drafting are gmail.

op (required):

• "send": send a mail, the mail LEAVES. Either an existing draft, as it stands: draft_id (from gmail(op="draft") or gmail(op="drafts")) — the usual path, the person could read it first; or a full message: to, subject, body (or reply_to for a threaded reply), the same arguments as gmail(op="draft"). Returns kind: "sent", the message id and threadId. Never report "sent" without reading kind.

• "archive": removes the INBOX label from message_ids.

• "trash": moves message_ids to the trash (Gmail deletes them after 30 days). One call per message: a PARTIAL trash is possible and is named — replay only what was not attempted.

The sending account's Gmail signature is appended by default, after -- (none added when the signature already opens with its own), like the Gmail web client does (the API never adds it on its own) — so do NOT write a sign-off block of your own in body. signature in the answer says what happened: "appended", "none_configured" (the account has no signature — nothing was added), or "disabled" (sign=False). (A draft is sent as it stands: its signature was added when it was written.)

List the connected Google accounts and the services each one has authorised.

Returns {accounts: [{email, is_default, services, shared}]} where services names the Google services this account consented to (gmail, drive, sheets, calendar, tasks, chat). A service missing from the list has not been authorised on that account yet: connect it from its own connector card. shared is null for the user's own account, "group" or "org" for an account an admin shared with their team or the whole organization. Pass email as _account to the service tools — shared accounts included; omitted, the project's pinned account, else the default one.

Meeting content — notes, transcripts, and folders.

A webhook endpoint receiving Granola event deliveries — list, create, update, or delete one. Unlike most write-capable tools here, the full CRUD lifecycle is exposed: managing a webhook subscription isn't destructive of user data (notes/transcripts), just integration plumbing.

Look up a Greek entity in open data (GEMI registry + VIES).

query accepts a company name, a GEMI no. or a Greek VAT no. (ΑΦΜ, with or without the EL prefix). Returns the matching companies (name, GEMI no., VAT, active/inactive status). For a single result, adds the address and the VAT validity via VIES.

Higgsfield, read-only: its models, the price of a job, and the state of a job. Nothing here spends the balance.

op:

• list_models — the models the key can call: slug (what model takes, e.g. higgsfield-ai/soul/v2/standard for stills, kling-video/v3.0/pro/image-to-video, bytedance/seedance-2.5/image-to-video for clips), title, description, output_type (image, video), operation_type (text2image, image_edit, text2video, image2video, video2video…). Filter with output_type, operation_type and search (words in slug, title or description). No parameter schema is given: each model's page at docs.higgsfield.ai lists its parameters, and estimate names a missing or faulty one.

• estimate — the price of a generation, free and with no effect: model and the same params as the generation. Answers usd (null when no amount can be read, basis says why), approximate (true when read from a per-second price sentence: it prices a 16:9 output before discount) and the raw estimate.

• get_request — one job (request_id): status queued, in_progress, completed, failed (with error), nsfw or canceled. Once completed, outputs lists every file address and expires_at says when they are deleted (seven days after the end). Failed, nsfw and canceled jobs are not charged. On the shared key, only a job your organization submitted (job_not_found).

Higgsfield jobs: submit one (spends the prepaid balance once it completes), cancel or delete one, or get an address to upload an input file.

op:

• create_generation — submit model with its params, REFUSED unless its price is known and at most max_usd (US dollars, required). The price is estimated first, free; when it cannot be read (no amount, no duration on a per-second price, a video input on a model priced without one) nothing is sent and the answer says why. Answers at once: request_id, status queued, the price used for the check. The job runs for seconds (a still) to minutes (a clip): follow it with higgsfield op='get_request'. Never retried; sending the same idempotency_key again returns the original job instead of a second one. Many models make sound by default (generate_audio, sound): turn it off in params unless sound is wanted, it costs more.

• cancel — cancel a job still queued (request_id); it is refunded. A job in progress can no longer be canceled.

• delete — delete a finished job's files, prompt and parameters now (request_id). Irreversible; billing records stay. On the shared key, cancel and delete act only on a job your organization submitted (job_not_found otherwise).

• create_upload — a presigned address for one input file (content_type: image/jpeg, image/png, image/webp, image/gif, audio/wav, video/mp4). PUT the bytes to upload_url within the hour with EVERY header of upload_headers (never the API key), e.g. curl -X PUT --upload-file still.png -H "Content-Type: image/png" -H "x-amz-tagging: retention=temporary" "<upload_url>", then pass public_url in params (image_url, video_url…). A file that is already at a public https address needs no upload.

Output links (images, videos) are the provider's PUBLIC addresses, readable by anyone holding the link for seven days (expires_after shortens it, 3600 seconds or more): download them right away, never paste them anywhere public.

Read the org's custom connectors (Custom API) — ops: list, setup_link. Calls, import and changes: http_act.

• list (default): without _account, every custom connector of the org (tools connected once for every member: account, label, description, action names) — start here. With _account: that connector's definition, its actions with their input schema. Call an action with http_act(op="call", operation=…, args={…}).

• setup_link: a link to connect a tool that has no dedicated connector (a payroll, ERP or any SaaS with an API key) → {url, prefilled, instructions}. Send the url to the person who holds the key; they paste the key in the form, never in the chat — this tool takes no secret. If a key was already pasted in a chat, tell them to revoke it and create a new one.

Act on a custom connector (Custom API) — ops: call, request, import, set_definition. Reads (the org's connectors, an action's input, the setup link): http.

• call: an action by name (operation, args). _account is optional when only one of the org's custom connectors has this action. Arguments are checked against its input; an omitted one takes the connector's saved variable of the same name. Any verb.

• request: a raw call to the custom connector of this call (_account when there are several), any verb (method, path, params, body) — for what no saved action describes. Its auth and constant headers are applied. Prefer call when an action exists.

• import (admin): turns an OpenAPI/Swagger JSON document into candidate actions WITHOUT saving them (source, url | document); review, then save with set_definition.

• set_definition (admin): saves the definition of the custom connector of this call (_account), reused by every member and session. Only the parts given change. operations REPLACES the action list: each name (snake_case), description, method GET|POST|PUT|PATCH|DELETE, path relative with {param}, input (JSON schema object), optional in {arg: path|query|body}. Never a secret here: the key stays on the card.

dry_run=true (call, request) returns {method, path, query, body} without sending it.

Fetches the documentation of the API configured for your org (http connector), if its operator filled in a doc_path route on the HTTP card (e.g. an OpenAPI contract in JSON). No parameter: the route comes from the config, never from the caller. Actionable error if doc_path is not set.

Read-only HTTP GET call to the API configured for your org (http connector). path = path relative to the base_url (starts with /). params = optional query params. The configured auth (bearer, API key, basic, oauth2) is injected automatically.

HTTP POST call to the API configured for your org (http connector). path = path relative to the base_url (starts with /). body = JSON body (dict/list). params = optional query params. The configured auth is injected automatically. Use for endpoints that require a POST (paginated search, write operations); what the POST is allowed to do depends on the target API.

Check a domain: email deliverability, blocklists, DNS, whois, TLS — op picks the check.

Read-only and passive: DNS-over-HTTPS, RDAP, public CT logs, a TLS handshake, one HTTP GET. No port scan, no vulnerability probing, no key needed.

op :

• "deliverability" : full email-deliverability report for YOUR sending domain — SPF/DMARC/DKIM/MTA-STS/TLS-RPT/BIMI + blocklists, a score /100, a grade and recommendations sorted by priority. Start here to answer « do our emails land in spam? ». What could not be read (DNS error, time budget) is listed in coverage and NOT scored — coverage.partial says so. Pass ip for a dedicated sending IP and dkim_selector if the domain signs with a custom selector.

• "blocklist" : is the domain or a sending IPv4 on a spam blocklist (DNSBL)? Domain lists + IP lists (SpamCop, PSBL, NordSpam, s5h — lists whose terms allow automated commercial lookups), with reverse DNS of each IP. IPs come from ip, else from the domain's SPF ip4: entries. Each list answers listed / clean / error — an error is NOT a clean result. ⚠️ Spamhaus, SURBL, URIBL, Barracuda, Mailspike and UCEPROTECT are returned under not_checked (public resolvers refused, or terms that forbid automated commercial use), never as clean. A domain sending through Google/Microsoft/an emailing tool has no IP of its own to check — the response says so in notes.

• "email_security" : email authentication posture — SPF (record, all qualifier, DNS lookup count vs the 10 limit), DMARC (policy, sp, pct, rua, alignment), DKIM on common selectors (+ dkim_selector), MTA-STS, TLS-RPT, BIMI, MX. ⚠️ DKIM selectors cannot be enumerated: an empty dkim_selectors_found does not prove DKIM is absent.

• "whois" : domain registration via RDAP — registrar, creation/expiration dates, statuses, nameservers, registrant org when public.

• "dns" : A/AAAA/MX/NS/TXT records, with stack hints (mail provider, SaaS verification tokens).

• "subdomains" : known subdomains from Certificate Transparency logs (crt.sh). count = all distinct found, subdomains = truncated to limit. crt.sh often fails transiently: the response then carries error.

• "tls" : TLS certificate of the host (issuer, validity, SANs, protocol); a failed validation is reported (validated=false + error), not hidden.

• "headers" : HTTP security headers (HSTS, CSP, …) + server fingerprint.

Reads INSTAGRAM messaging via Unipile: 1-to-1 AND group conversations. Sending is instagram_act.

op:

• "list" (default): the conversations, newest first, in items (limit 1-100). A cursor is returned only when Unipile paginates the channel (WhatsApp does not: a full page carries truncated). Group threads are listed alongside the 1-to-1 ones (is_group, named by the group's name) and read the same way. Each 1-to-1 thread is enriched with the counterpart's name (attendee_name); with_names=False turns this enrichment off (one API call fewer).

• "read": the messages of a thread, 1-to-1 or group (chat_id from op="list"). A message Unipile passed on without text nor attachment carries content_unavailable. Each attachment carries a source: pass it to oto_import (target="project_file") to file it, or to any tool taking a source — the server fetches the file, never through the conversation.

⚠️ SENDS a INSTAGRAM message via Unipile, from the person's own account — it leaves at once, there is no draft. Reading is instagram.

op:

• "send" (default): sends text. chat_id → replies in an existing thread, 1-to-1 or group (from instagram(op="list")); otherwise recipient_id → opens a new thread with that contact.

Ask Jev typed questions about one state and get answers with probabilities.

Jev is not a chat model: it returns a typed answer per question and nothing else — no prose, no justification, no tool calls. It pays off on BATCHES — many rows or profiles to triage with the same rubric (see jev_items). A single case you can judge yourself does not need Jev.

⚠️ The state is sent to a third party (OpenRouter, which passes it to TypeSafe): put in it only the fields the judgement needs, never a whole record or document.

Put the WHOLE rubric in one call: the questions of one call are answered in parallel, each extra question costs about 48 input tokens, and the state is charged once. They cannot see each other's answers, so a question that depends on another's answer needs a second call.

Returns — {model, answers, usage}: answers[name] is {type: "noul", noul: 0.96}, or {type: "choice", choice, probabilities, confidence}, or {type: "score", score, probabilities, legend, confidence}. model names the exact snapshot that answered — store it next to the answer, it is what makes a threshold reproducible. usage carries input_tokens, output_tokens (free) and cost in USD.

A probability near 0.5 means "as likely as not", never "medium": pick two thresholds and leave the band between them to a human or to a stronger model.

Ask Jev the SAME questions about many states in one call — nothing is written.

The shape for "decide, then act": you have just read a page of rows or a list of profiles to triage with the same rubric, and you want a verdict per item before writing them, enriching them, or spending anything on them. Each item is judged on its own — one item's answer never depends on another's.

⚠️ Each state is sent to a third party (OpenRouter, which passes it to TypeSafe): put in it only the fields the judgement needs.

Returns — {model, answers, usage, failed, retry}: answers — one entry per item, in the ORDER SENT, each {index, answers: {…}} exactly as jev_ask returns them, or {index, error} for an item without an answer (a state the upstream refused, a transient failure, or not sent in time). A failed item never becomes a false verdict. usage — {decided, failed, input_tokens, cost} for the whole call. failed — the number of items without an answer. retry — the indexes that were NOT SENT because the call ran out of time (about 40 s): send exactly those again. [] when everything was sent.

A key problem (invalid key, no credits left) aborts the whole call rather than turning into N identical item errors; the answers already given are still billed, and the error says how many.

Follow or stop a jev_rows(background=true) job.

op='status' — where the job is: {job_id, status, decided, jev_errors, empty_state, skipped_leased, skipped_changed, low_confidence, thin_state, remaining, cost, errors, error_count, error, slices, model, created_at, updated_at, finished_at}. status is pending, running, done, failed (error says why; what was judged stays written and billed) or cancelled. remaining = undecided rows matching the job, as of its last slice. Poll every minute or so, not faster: a slice takes up to two minutes. op='cancel' — stop the job. One with no slice in flight stops at once; one mid-slice stops when that slice ends (rows it judged stay written and billed). Relaunching jev_rows(background=true) later resumes on the undecided rows.

Qualify a table's rows with Jev ON THE SERVER: rows are read, judged and written back here, and no row data passes through you. Write the rubric; review the sample.

Each row's state_fields are sent with the same questions; each answer is written to its output column, its confidence to <column>_p (choice and score), and the model snapshot to model_column. A noul writes its probability; a score writes the expected level (e.g. 3.34). A row Jev can never answer as is (state too large, or refused upstream as too long) or whose answer the table refuses to store gets jev_error: <reason> in model_column. A row whose state fields are all empty is counted in empty_state and left undecided: fill it, then re-run. Missing output, <column>_p and model_column columns are created, typed from the questions (choice → enum of its criteria); existing ones are never changed. The key and the rubric are checked before anything is created or written.

Only undecided rows are taken (model_column empty) unless overwrite=true, so a re-run resumes and never pays twice. Rows leased by another run are skipped, and a row changed since it was read is never overwritten.

A whole table: background=true (after a dry run). The call returns a job_id at once and the server judges every matching row itself — no cursor loop, and a dropped connection doesn't stop it. Follow it with jev_job(op='status'), stop it with jev_job(op='cancel'). The key, the write right and the quota are checked again before every slice: a revoked key or a spent quota stops the job, and what was already judged stays written and billed. One active job per table and model_column. A job keeps _run_id and bills its slices under it.

Without background, one call judges what fits in its time window (~100 rows): loop on next_cursor until done, then finish with one pass WITHOUT cursor to pick up skipped rows. Nothing reserves rows between two calls: do not run two at once on the same rows.

Any other upstream refusal (key, credits, a malformed request) stops the batch: what was already judged stays written and billed, and the error says how much.

Run dry_run=true on known cases before a full run. Jev sees only the state and the questions: put client context (ICP, offer) in the criteria or the state. Rows with a thin state score low for lack of evidence (thin_state counts them). No bucketing here: thresholds belong to you. Validate fit against known outcomes before trusting it; combine Jev's answers with structured fields in plain code.

⚠️ Each state goes to a third party (OpenRouter, then TypeSafe). Billed on real cost, about 50 µ$ per row for 3 questions and a 500-character description.

Returns — {decided, jev_errors, empty_state, skipped_leased, skipped_changed, errors, error_count, low_confidence, thin_state, created_columns, next_cursor, remaining, done, cost, model, sample}. errors and sample name rows by _id with codes and what was written — never a value read from the table. dry_run returns rows (each judged row's _id and answers) and would_create_columns, and writes nothing. background returns {job_id, status, remaining, created_columns}.

A French or European court decision (jurisprudence) — search the collections full text, or read one decision in full.

op:

• "search" (default): search French & European case law (jurisprudence) full text — how courts actually ruled. Unified collections, ranked by FTS relevance × court authority, with legal-thesaurus query expansion. Returns {count, decisions: [{id, titre, juridiction, date_dec, solution, extrait, source_url, …}]}. Full text via op="get".

• "get": full text of a French court decision, with metadata (juridiction, formation, solution, ECLI) and a verifiable Légifrance source_url.

Set custom variables on a lead — merged into its personalization data, e.g. for {{variableName}} placeholders in campaign templates.

Manage campaigns: create, configure, pause, duplicate, validate, report, export. oto_guide op=read slug="lemlist-playbook": build order, where each id comes from, and the doc↔API gaps.

Nothing here sends by itself — but a created or duplicated campaign is born RUNNING (its status reads "draft"): op="pause" is the switch. Putting messages on the wire is lemlist_campaign_start (hidden by default — enable it with oto_enable_tool lemlist_campaign_start).

Args by op:

• create: name (required), optional timezone (IANA, drives the auto-created schedule; server default Europe/Paris). Returns the campaign with sequenceId and scheduleIds — the two ids lemlist_sequence and lemlist_schedule need. settings is REFUSED here (the endpoint takes name + timezone only) — chain update on the returned id rather than believe a setting landed. ⚠️ The campaign is created in state RUNNING, not draft (its status reads "draft" only because it has no step and no lead yet). It sends nothing while the review gate holds, but chain op="pause" if you want to build it with the switch off.

• update: campaign_id + name, sender_user_ids (usr_…, the senders) and/or settings (raw PATCH body: stopOnEmailReplied, stopOnMeetingBooked, stopOnLinkClicked, disableTrackOpen, disableTrackClick, disableTrackReply, tracking, onReplied, aiFeatures…). Only the keys sent change.

• pause: campaign_id. THE off switch — a campaign created here is already running. Stops it advancing; already-scheduled leads are NOT recalled. Errors if the campaign is not running.

• duplicate: campaign_id + optional name. Copies sequence, steps, schedules and AI templates into a new campaign (CRM settings excluded). ⚠️ Like create, the copy runs (state running in reports) although its status reads "draft": chain op="pause" to hold it.

• statutes: campaign_id. The validation the lemlist UI runs — read it BEFORE starting: level 3 blocks the launch (no sender, broken DNS), 2 warns (daily limit, missing schedule), 1 informs.

• reports: campaign_ids. One row per campaign in operator vocabulary (emailsSent, emailsOpened, emailsReplied, senderNames, state) — the shape for comparing campaigns.

• batch_stats: campaign_ids (≤ 100) + optional start_date/end_date (defaults to the whole life), channels (email/linkedin/others), send_user (usr_…|sender@email), ab_selected (A/B). Same counters as lemlist_get_campaign_stats, in one call.

• export_start: campaign_id. Opens an ASYNCHRONOUS stats export and returns its id; poll export_status (campaign_id + export_id), or ask to be notified with export_email (+ email).

• export_leads: campaign_id + optional state (defaults to all; lemlist's own default filters EVERYTHING out and returns an empty list that reads as "no leads"), format (csv, the API default, or json). Returns the leads directly — the synchronous cousin of the export above.

autoReview/autoReviewConditions are not settable here: they make every added lead send immediately, which would turn lemlist_create_lead into a send path. They live in lemlist_campaign_auto_review, hidden by default — a switch that arms sending should take a deliberate gesture, not ride along in a settings dict.

Start (or resume) a campaign — lemlist begins sending.

THE send gesture at campaign level: from here lemlist walks the sequence for every launched lead, to real people. A no-op if already running.

Read lemlist_campaign(op="statutes", …) first — it names what would block or degrade the launch (missing sender, broken DNS, daily limit) with the same validation the UI runs.

⚠️ In practice this RESUMES a paused campaign: one created through lemlist_campaign(op="create") is already running, and lemlist answers 400 "You can't start campaigns that are already running".

Companies of the lemlist CRM, and their notes.

Args by op:

• list: ids_or_domains (exact lookup) or search, fields (keep only these), sort_by/sort_order, crm_sync_status, field_rejection_reason, limit, offset.

• upsert: company — identity keys companyId / domain / linkedinUrl, then name, industry, size, location…

• delete: company_id; force=True deletes it even with contacts attached (lemlist refuses otherwise).

• notes: company_id (+ limit, page, sort_by, sort_order). note_create: company_id + note.

Contacts of the lemlist CRM, and the lists that group them.

A contact is the PERSON, campaign-independent — its copy inside a campaign is a lead (lemlist_lead). Nothing here sends.

Args by op:

• list: ids_or_emails (≤ 100, exact lookup) or the filters search, email, list_id, not_in_any_campaign, company_id, company_domain, company_linkedin_url, company_salesnav_url, field_rejection_reason (why a CRM sync rejected a field), limit, offset.

• get / delete: id_or_email.

• upsert: contact — one dict, create AND update. Identity keys contactId / email / linkedinUrl; then firstName, lastName, phone, jobTitle, location, contactOwner, the company link…

• lists: optional search. list_create: name.

• list_manage: list_id + contact_ids. ADDS by default — action="remove" takes them out.

• list_export: list_id, optional entity (contact or company). Returns CSV text.

Create a lead in a campaign.

Several leads: lemlist_push_rows reads them from a datastore table instead.

All lead fields are optional (lemlist accepts phone/LinkedIn-only leads), but you'll usually pass at least email or linkedin_url. custom_variables merges extra key-value pairs into the lead, used for campaign personalization (e.g. {{variableName}} in a template). Each value goes as text (a number or boolean written out, a list joined); an object or null is refused (lemlist_custom_variable_value), and so is a key that is a lead field such as email or firstName (lemlist_custom_variable_collision) — pass it through its argument.

Enrichment flags (all default False, each may cost lemlist credits): deduplicate skips the insert if the email already exists in another campaign, linkedin_enrichment runs LinkedIn enrichment, find_email/verify_email find or verify the email, find_phone finds a phone number.

campaign_id is lemlist's campaign id as it returns it, WITH its cam_ prefix (cam_A1B2C3…) — an id without it is refused before any call.

Returns the created lead, including _id — pass it to lemlist_launch_lead/lemlist_add_lead_variables. A response without a lead _id is a named refusal (lemlist_lead_not_created), never a success. review_state is always "unknown": lemlist's answer does not say whether the lead is held for review or already in sequence (its isPaused does not tell them apart, so it is removed). To know if it will send, read lemlist_campaign(op="reports"): reviewedCount or inSequenceLeadCount rising with the add means it goes out; only totalCount rising means it is held for review until lemlist_launch_lead. A 404 « Campaign not found » is a named refusal (lemlist_campaign_not_found): the campaign is not reachable by the key in use for leads, even if its reports are.

A lead lemlist refuses as a DUPLICATE is not an error: the call returns {created: false, reason, message, campaign_id, lead} with reason already_in_other_campaign or already_in_campaign — nothing was created; count the contact as already taken and move on.

Search lemlist's SHARED prospecting database. Reads only.

Distinct from lemlist_contact/lemlist_company, which hold only YOUR data. Read op="filters" first: the filter vocabulary is server-side, and a filters payload built from guesswork comes back empty. Every call spends the quota of your lemlist key. Saving or deleting a persona is lemlist_act.

Args by op:

• people: filters, search, excludes, page, size.

• companies: filters, page, size.

• filters: no argument — the available filters.

• personas: optional mode — the saved personas.

Delete the recording transcript attached to a call activity.

Its own tool because it is the only destructive gesture on the activity log — a transcript deleted here is not recoverable through the API.

Deliverability alerts — fire when inbox rate, spam rate, score, delivery or bounce rate crosses a threshold.

Args by op:

• list / get (alert_id) / delete (alert_id).

• create: widget (warmup/outreach), metric (inboxRate, spamRate, score, deliveryRate, bounceRate), severity (warning/critical), scope (global/mailbox/domain), threshold, comparison_operator (equal/below/above), period_days, period_mode (rolling/consecutive) — all required; then scope_entities, channel_config (in-app only when omitted; email needs at least one address), recheck_delay_hours.

• update: alert_id + settings (threshold, enabled, channelConfig…).

Submit an ASYNC enrichment on a person — no campaign, no lead needed.

Returns immediately with an enrichment_id; the work runs server-side. THEN call lemlist_enrich_result(enrichment_id) to collect it (first poll after ~10-20s, then every ~15-30s until done).

Args: email, linkedin_url, first_name, last_name, company_name, company_domain: the identity to enrich. All optional, but lemlist only resolves what it can match — pass a LinkedIn URL, or a first/last name together with a company domain.

Enrichment actions — at least one is required, and each spends lemlist credits: find_email finds a verified email, verify_email verifies the email you passed (debounce), linkedin_enrichment runs the LinkedIn enrichment, find_phone finds a phone number. Ask only for what you need.

Submit several enrichments in one call.

Returns submitted: one entry per person, in order, each carrying either enrichment_id or error (e.g. MISSING_INPUTS). Unlike a FullEnrich job, a bulk submit yields one id PER PERSON — pass the whole list of ids to lemlist_enrich_result.

Enrich a lead that is ALREADY in a campaign, in place.

Same actions as lemlist_enrich, but the identity comes from the existing lead and lemlist writes the result back onto it. Async too: returns an enrichment_id for lemlist_enrich_result.

Only works on a lead still AWAITING REVIEW — lemlist answers 400 "lemrich is not available for lead reviewed" once a lead has been reviewed, which is the state of every lead in a campaign without review-before-send. For anyone else, enrich the person with lemlist_enrich and write the result back yourself.

Enrichment actions — at least one is required, and each spends lemlist credits: find_email finds a verified email, verify_email verifies the email you passed (debounce), linkedin_enrichment runs the LinkedIn enrichment, find_phone finds a phone number. Ask only for what you need.

Collect the result of an enrichment submitted with lemlist_enrich, lemlist_enrich_lead or lemlist_enrich_bulk.

Single status check per id, returns immediately — no waiting. If a result is not done, wait ~15-30s and call again.

Returns results: one entry per id, {enrichment_id, status, done, input, data, found}. status is done, in-progress or not-found. data is lemlist's raw payload; found is the digest to read — only the axes that actually carry a value (email, email_status deliverable/undeliverable, phone, linkedin). An axis key is present in data even when empty, so presence alone means nothing, and notFound: false has been seen on a payload with no number.

A result can come back done with nothing in it: lemlist sometimes flips the status before the payload lands. Such an entry carries a warning and is NOT counted in all_done — poll it once more before concluding nothing was found (a poll costs no credits).

Get activity events (opens, clicks, replies, LinkedIn actions…).

Fetch full campaign details by ID.

Campaign performance (leads reached, opened, replied, bounced…).

Reads lemlist's own counters. Previously derived from one page of activities, which under-counted every campaign past 1000 events — the field names changed with the fix (nbLeads, messagesSent, opened, replied… instead of emails_sent & co).

List all leads for a campaign with their state (sent, replied…).

⚠️ Goes through the JSON export, NOT get_all_leads: the latter calls the export without state, hence with lemlist's default — which filters everything out and returns an empty list that reads as "no leads". A one-lead campaign thus came back empty (signal 719) while the single-lead route returned it just fine, and the guide announced the forcing as a given for the whole connector. export_campaign_leads carries the default state="all", verified live on 2026-08-31: we take the surface that has the guard rather than rebuild one.

Read the unified inbox, write drafts, manage labels. Sends nothing — sending is lemlist_act.

Conversations are keyed by CONTACT, all channels merged.

Args by op:

• list: user_id (required — an inbox belongs to a person), page, limit.

• messages: contact_id + optional user_id, limit, skip. ⚠️ mark_as_read=True MUTATES on a read call. ⚠️ One HTML email can weigh 300 000+ characters (images pasted as base64): to read what was SAID, pass text_only=True (HTML turned to plain text, inline images dropped) and max_chars (each text cut there). The answer then carries truncated_fields, the number of texts that were cut — 0 means you have them whole.

• labels / label_get (label_id) / label_create (label_name).

• labels_attach: contact_id + label_ids; append=False REPLACES the conversation's labels. labels_remove: same minus append.

• drafts / draft_get / draft_delete: contact_id + draft_owner (a user id — a draft belongs to a person) + draft_id where relevant.

• draft_create: contact_id, draft_owner, channel (email, linkedin, whatsapp, sms), content, optional subject, cc, attachments, reply_to_activity_id (answer a specific message), source_metadata.

• draft_update: same ids + draft (the fields to change).

Launch a lead held for manual review.

Only relevant for a campaign with review-before-send enabled — such a campaign holds a newly created lead in review until launched (counted in the campaign's reviewedCount; the lead's isPaused stays false). Returns {"ok": true} on success; raises with a lemlist error code if it can't launch (already launched, paused, no sender available, invalid AI variable, campaign step errors…).

Lead lifecycle inside a campaign — read, edit, pause, qualify, remove. oto_guide op=read slug="lemlist-playbook": build order, where each id comes from, and the doc↔API gaps.

A LEAD is a person's copy inside ONE campaign (its sending state, its variables); the person themself is a contact (lemlist_contact). Creating a lead is lemlist_create_lead; releasing one held for review is lemlist_launch_lead.

Args by op:

• get: lead_id or email. list: campaign_id + optional state (sent, replied, paused…) and limit. ⚠️ state defaults to "all" HERE, which is NOT lemlist's own default: without it the API filters everything out and returns an empty list that reads as "no leads on this campaign". Pass a state only to narrow deliberately.

• update: campaign_id + lead_id + fields (firstName, lastName, companyName, jobTitle, preferredContactMethod).

• delete: campaign_id + lead_id/email — really removes it. unsubscribe: same arguments, but the lead STAYS on the campaign, marked unsubscribed. One lemlist route serves both, and its default is the soft one; here the two are named apart so neither is a surprise.

• pause: lead_id; WITHOUT campaign_id it pauses the lead in EVERY campaign, not one. resume: lead_id — undoes a pause, so lemlist starts sending to that lead again (it does not skip a review; that is lemlist_launch_lead).

• interested / not_interested: lead_id or email; with campaign_id it applies to that campaign, without it to all.

• vars_update: lead_id + variables. vars_delete: lead_id + variable_names (the values are erased).

• import_crm: campaign_id + crm + user_id + filter_id (from lemlist_team(op="crm_filters")), optional filter_type, deduplicate.

• upload_audio: lead_id + step_id + audio — the audio of a linkedinVoiceNote step. audio is a source dict: {"kind": "url", "url": …}, {"kind": "drive", "file_id": …}, {"kind": "gmail", "message_id": …, "filename": …}, {"kind": "project_file", "project_id": …, "file_id": …} or a recording's source as read ({"kind": "transit", "ref": …}). The server fetches it (≤ 20 MB) and forwards the bytes.

List the campaigns of the workspace.

Returns {campaigns: [{id, name, status, senders, emoji, labels, timezone, created_at, created_by, has_error, errors}], count, truncated}. truncated: true means the ceiling was hit and the list is INCOMPLETE — do not conclude a campaign is absent from it.

Mailboxes: connect/disconnect/test, and lemwarm (deliverability warm-up).

Args by op:

• connect: smtp_imap — one dict carrying sender_name, sender_email, smtp_host, smtp_port, smtp_login, smtp_password, imap_host, imap_port, imap_login, imap_password (all required), plus smtp_secure, imap_secure, user_id. ⚠️ MAILBOX CREDENTIALS travel here.

• disconnect / test: email_account_id. Disconnecting stops the campaigns sending from it.

• lemwarm / lemwarm_update (settings: warmEmailMax, warmEmailRampup, answerPercentage…) / lemwarm_start / lemwarm_pause: mailbox_id.

lemwarm_start DOES send — inside the warm-up network (other lemlist mailboxes), never to a prospect. That is why it sits in a visible tool while the prospect-facing sends do not.

Create lemlist leads FROM DATASTORE ROWS — the bulk way; nothing personal goes through this call.

Name the rows (row_ids, or a filter); oto reads them, creates one lead per row in the campaign, and writes back id_column (the lead id) and status_column (pushed | duplicate | failed) on each row. The answer is counts plus errors: [{row_id, code}] — never a value read from a row.

By filter, only rows whose status_column is empty are taken: call again with the same filter until remaining is 0. A row already treated is not picked again — name it in row_ids to retry it. A row with id_column already set is skipped (already_pushed); one reserved by another run is skipped (row_locked) before anything is sent. dry_run reads and checks the mapping, sends nothing. Like lemlist_create_lead, this sends no email: a lead waits for review until lemlist_launch_lead.

Manage sending windows (schedules) — days, hours, timezone, pacing.

A schedule belongs to the TEAM, not to a campaign: several campaigns can share one, and a campaign can carry several. Creating a campaign auto-creates one and returns its id in scheduleIds.

Args by op:

• list: optional limit, offset/page, newest_first — the route is paginated, so a team with many windows needs them.

• get / delete: schedule_id.

• create: name (required) + timezone (IANA, default Europe/Paris), start/end (HH:mm, default 09:00-18:00), weekdays (1 = Monday … 7 = Sunday, default Mon-Fri), seconds_to_wait (pacing between two sends), public (offer it as a team template).

• update: schedule_id + any of the same fields; only what is sent changes.

• for_campaign: campaign_id. The schedules attached to a campaign.

• associate: campaign_id + schedule_id. Attaches an existing window to a campaign.

Read and edit the steps of a campaign sequence, and its A/B tests.

A campaign owns a sequence (seq_…, returned by create) whose steps (stp_…) are the emails, LinkedIn actions and conditions it runs.

Args by op:

• get: campaign_id. Every sequence of the campaign with its steps — conditional steps branch into further sequences, so a campaign can hold several.

• add_step: sequence_id + step. step.type is required, one of email, manual, phone, api, linkedinVisit, linkedinInvite, linkedinSend, linkedinVoiceNote, linkedinFollow, linkedinLikeLastPost, linkedinCommentLastPost, linkedinEndorse, linkedinWithdrawInvitation, sendToAnotherCampaign, conditional, whatsappMessage, sms. Common fields: index (insert position, appended when omitted), delay (days), subject + message (email), title (manual), method + url (api), conditionKey + delayType (conditional), campaignId (sendToAnotherCampaign).

• update_step: sequence_id + step_id + step. step.type is required and must MATCH the existing step — it identifies the shape, it does not convert it. images/videos REPLACE what is there.

• delete_step: sequence_id + step_id. Refused by lemlist while the campaign is running — pause it first.

• ab_create: sequence_id + step_id (an EMAIL step). Creates variant B prefilled from A and STARTS the split. Email Pro plan.

• ab_get / ab_update (step = the B fields: subject, message, altMessage, cc, plainText).

• ab_delete: optional variant (default B). A promotes B to A.

• ab_winner: variant (A or B) — the winner's template is then sent to every remaining lead.

Workspace status (account, credits, plan).

Never raises on a dead/invalid key — check connected first: {"connected": true, "campaigns_count", "campaigns_capped"} on success, {"connected": false, "error": "<message>"} on failure. A 200 response with connected: false IS the failure — don't treat a non-empty result as automatically working.

Manual tasks assigned to a user (call, LinkedIn touch, follow-up).

A task is a REMINDER for a human: creating one sends nothing.

Args by op:

• list: page, filters (list of {filterId, …}).

• create: task_type (email, manual, phone, linkedin), assigned_to (user id), due_date AND record_id (the contact ctc_… or lead lea_… the task hangs off) — all four required, the last one despite lemlist documenting it optional; then title, message, priority (0 high … 2 low), images/videos (public HTTPS URLs).

• update: task_id + any of title, message, priority, due_date, assigned_to, done, images, videos.

• ignore: ids — dismiss without completing.

The workspace itself: team, credits, senders, users, CRM link, fields.

Where the ids other tools ask for come from.

Args by op:

• team / credits: no argument (credits are what enrichment spends).

• senders: optional state (campaign status) — members and the campaigns they send from.

• user: user_id. user_channels: no argument — the mailboxes, LinkedIn and WhatsApp accounts the key's user can send on, i.e. the ids lemlist_inbox_send requires.

• crm_users: the users connected to a CRM. crm_filters: crm (hubspot, salesforce…) + user_id, optional filter_type (lead, contact, report) — the selection lemlist_lead(op="import_crm") imports from.

• fields: optional entity (contact/company) and source (default/custom/crm_synced) — which custom fields exist.

Manage who must not be contacted. THREE lists, not one.

They do not hold the same objects, and writing to one does not write to the others:

• v1 list/get/add/delete/export — emails and whole DOMAINS.

• v2 var_* — any identifying value (email, domain, LinkedIn URL, phone), with var_bulk for up to 10 000 at once.

• v2 contact_* — the do-not-contact flag on a CRM contact, which rides the CONTACT rather than one of its values.

To check ONE value, use get (v1) or var_get (v2): a listing can hold thousands of rows. list and var_list are paged: 100 rows when limit is omitted (lemlist caps var_list at 100 anyway), and next_offset says where the next page starts (null on the last one).

Args: email (v1), value / values (variables), contact_id (contacts), limit/offset on the two listings. The *_export ops return CSV text.

Watch lists: standing alerts on buying signals (hiring, funding, job change, tech move, website visit…), and the signals they catch. oto_guide op=read slug="lemlist-playbook": build order, where each id comes from, and the doc↔API gaps.

⚠️ A list created with signal_processing_type="push_to_campaign" and activate=True feeds a campaign ON ITS OWN — the one configuration here that can end in messages being sent without a further call.

Args by op:

• list: watch_type, status, page, limit.

• create: name + watch_type (companyIsHiring, companyRaisedFunds, jobChange, newHire, technologyChange, buyingIntent, companyEmployeeVisitedMyWebsite…), then filters. Read op="filters" for that type FIRST: each type has its own REQUIRED filters (companyIsHiring needs title, location and maxIdentificationsPerDay), the values must be the canonical ones op="filter_values" returns — a free string is rejected — and numbers travel as STRINGS ({"filterId": "maxIdentificationsPerDay", "in": ["5"]}). Optional emoji, signal_processing_type (manual, create_opportunity, push_to_campaign), activate (default False — the list is created as a draft), segment_type, opportunity_template (what create_opportunity builds: owner, channel, priority), and with push_to_campaign only: campaign_id (the campaign fed) and persona_id (pdp_…, from lemlist_database op="personas": who to push when a signal names a company and no person).

• update: watch_list_id + settings (raw PATCH body). delete: watch_list_id.

• filters (optional watch_type) / filter_values (filter_id, optional query) / library: what a list can be built from.

• history: watch_list_id. signals: the catches, filterable by watch_list_id, watch_type, status, received_from/received_to (ISO bounds), and sorted by sort_by/sort_order.

• push_signals: watch_list_id + contact (needs linkedinUrl) + company (needs domain and name), optional custom_fields — feed a signal detected OUTSIDE lemlist.

Website visitors (companyEmployeeVisitedMyWebsite), lemlist's own visitor identification:

• Needs lemlist's tracking script on the site, installed from the lemlist app (Signal agents ▸ Create ▸ Website visitors) — no API call installs it.

• ⚠️ An ACTIVE list spends 20 lemlist credits per visit caught: set the maxIdentificationsPerDay filter, and confirm before activate.

• Filters: website, pagesTracked, minVisitDuration, minPageViewed, visitLocation, internalTraffic, excludedVisitorIps, maxIdentificationsPerDay.

• Each signal carries company (name, domain, linkedinUrl, industry) and signalData (websiteVisited = the page, visitorWebsite, visitorCountry, visitorDuration in seconds); contact only when lemlist could name the visitor (some US traffic).

• Read them on a schedule: op="signals", watch_type="companyEmployeeVisitedMyWebsite", received_from. Or on each visit: lemlist_webhook op="add" with event_type="signalRegistered" (fires for EVERY watch list — check the type).

Webhooks — push lemlist events to a URL of yours (/hooks).

Args by op:

• list: no argument.

• add: target_url + optional event_type (ONE event: emailsReplied, linkedinInviteAccepted, enrichmentDone, signalRegistered… ~70 of them; omit to subscribe to all), secret, campaign_id (narrow to one campaign), is_first (first occurrence per lead only), zap_id (tag the hook as coming from a given Zap).

• delete: hook_id.

Remaining AI Ark credits for the resolved account ({"total": <int>}).

⚠️ On the PLATFORM key (credits paid by oto), the balance is not yours to read — the call is refused rather than showing someone else's pool. Bring your own AI Ark key to see a balance.

Resolve ONE person through AI Ark (bought data, per-credit).

op:

• "export" (default): the person WITH their email (synchronous email finder). Give id (from linkedin_aiark_search(op="people")) OR url (a LinkedIn profile URL).

• "reverse": find the person FROM a contact detail (search = an email, a phone number…).

• "mobile": their mobile phone number(s). Give linkedin (profile URL) alone, OR domain AND name together.

Every op returns {"found": false} rather than an error when nothing matches — an absence is a result, not a failure.

The converse matters more, and is the whole point of this note: a FAILURE is never an absence. When AI Ark does not answer at all (read timeout — it comes in bursts on op="export" while search stays healthy in the same minutes), the call is retried ONCE, then raised as an error carrying retryable: true. Nobody was looked up: retry it, and never record a not-found from it — the person may well have an e-mail nobody has asked for yet. ⚠️ That retry can bill a second credit if AI Ark had already processed the first attempt and only the answer was lost.

Search LinkedIn-sourced B2B data through AI Ark (bought data, per-credit).

Not interchangeable with linkedin_unipile_search: that one drives YOUR connected LinkedIn session (and is rate-limited by LinkedIn); this one queries AI Ark's index and BILLS CREDITS per returned record.

op:

• "people" (default): people by company + contact filters. Results do NOT include emails — use linkedin_aiark_person(op="export") for one.

• "companies": companies by firmographics.

Returns the AI Ark page: content[], totalElements, totalPages.

A read timeout is retried ONCE and then raised with retryable: true — a failure, never an empty page (⚠️ the retry can bill a second time if AI Ark had already processed the first attempt).

Reads LinkedIn messaging (DM) via Unipile. Sending, reacting and changing a thread — like every act on LinkedIn — is linkedin_unipile_act.

op:

• "list" (default): the conversations, paginated (limit + cursor) — 25 at most per page (LinkedIn's limit): beyond that, paginate by cursor. Each 1-to-1 thread is enriched with attendee_name/attendee_headline/ attendee_profile_url (resolved in batch — the raw name of 1-to-1 threads is null and attendee_provider_id is opaque). with_names=False turns off this enrichment (raw payload, one API call fewer). ⚠️ The enrichment may not happen, and the response SAYS so: an attendee_names field then appears, with its status and its reason. An absent attendee_name on a thread therefore does NOT mean "no counterpart" — read attendee_names before concluding, and fall back on name or last_message.sender. ⚠️ Do NOT use last_message.is_sender to know whether YOU wrote last. Observed as false on all of an account's threads on 03/09/2026 — including the 22 whose last message came from the account itself, exactly like the threads where the counterpart had replied. The field distinguishes nothing: relying on it leads to concluding a reply on every thread, or the opposite. Compare last_message.sender_id (or last_message.sender.display_name) with the account's identity.

• "read": the messages of a thread (chat_id). Each attachment carries a source: pass it to oto_import (target="project_file") to file it, or to any tool taking a source — the server fetches the file.

• "attendees": participants of a thread (chat_id).

• "contacts": your messaging contact book (counterparts). Paginated.

A page of threads with their full last message is heavy (~100,000 characters for 20): for a sweep, slim it with fields (e.g. ["id", "name", "timestamp", "last_message.sender_id", "last_message.text"]) and text_max_chars (e.g. 200) — op="list" and op="read".

The connected LinkedIn account: its STATE (op="status"), and its premium Recruiter / Sales Navigator slate (the three other ops).

• "status" — "is my LinkedIn connected?": connected, account_id, account_name, and alive (the session may be DEAD while the account stays linked — checkpoint, rotated cookie). Always answers; connected:false carries next_step, the missing step. This is the op to use to verify a messaging onboarding (#452: an agent had invented it, got an invalid_arguments and wrongly concluded that the channel was not connected). Right after a connection flow, pass account_id = the account_id=… value from the return page's address: this is what proves WHICH account to link; without it, the linking is refused (binding.reason = "ambiguous_candidates") if several connections happened at the same time on the shared key.

• "contracts" (default): the available premium contracts — the id to pass to op="select".

• "select": activates a contract for the premium calls that follow.

• "inmail_balance": InMail credit balance (premium messages).

The three premium ops require the matching subscription ON the connected account and the premium seat activated at connect (unipile_connect_start(premium=…)) — otherwise the premium APIs answer 403 "out of your scope". op="status", for its part, requires nothing.

⚠️ ACTS on LinkedIn from the person's own account — the other members see it, at once, with no draft: a message, a post, a comment, a reaction, an invitation, an endorsement. Reading is linkedin_unipile (messaging), linkedin_unipile_post, linkedin_unipile_network, linkedin_unipile_profile.

op — messaging (DM):

• "send" (default): sends text. chat_id → replies in an existing thread; otherwise recipient_id (the recipient's provider id) → opens a new thread.

• "react_message": reacts to a MESSAGE with a native emoji (reaction, e.g. '👍') — the counterpart sees it. message_id = id of a message from linkedin_unipile(op="read"); chat_id is required on the v2 API, ignored in v1.

• "update": changes a thread's state — action ∈ setReadStatus | setMuteStatus | setArchiveStatus | setPinnedStatus | setLabel | getInviteLink; value = boolean for the statuses, string for setLabel, omitted for getInviteLink. ⚠️ setReadStatus can show the counterpart that you read them.

op — posts, published publicly in the person's name:

• "publish_post": publishes a post (text).

• "comment_post": comments on a post (post_id, text).

• "react_post": reacts to a POST (post_id) — value: LIKE (default) | PRAISE | EMPATHY | INTEREST | APPRECIATION | ENTERTAINMENT. post_id = social_id (urn:li:…) from linkedin_unipile_post or linkedin_unipile_profile(op="posts").

op — invitations:

• "invite": sends a connection request. provider_id = the provider_id of a linkedin_unipile_search / linkedin_unipile_profile result; message = note ≤300 characters.

• "accept_invitation" / "decline_invitation": answers a RECEIVED invitation — invitation_id AND shared_secret from the SAME item of linkedin_unipile_network(op="invitations", direction="received").

• "cancel_invitation": withdraws a SENT invitation (invitation_id of a direction="sent" item).

op — a member (identifier = public slug or URN):

• "endorse": endorses a skill (skill_endorsement_id = endorsement_id of a skill from linkedin_unipile_profile(op="person")).

• "update_member": premium action — api = 'sales_navigator' (action 'saveLead', optional list_id) or 'recruiter' (action 'addCandidateToPipeline' | 'addApplicantToPipeline' | 'changeCandidatePipeline' | 'rejectApplicant', hiring_project_id, stage 'UNCONTACTED' | 'CONTACTED' | 'REPLIED').

Resolve a LinkedIn filter NAME into {id, name} candidates to pass to linkedin_unipile_search. To be used BEFORE a structured search as soon as a criterion is not a simple keyword (skill, industry, location, employer…).

Choosing the right candidate is YOUR job: a single input often returns several facets ("Microsoft Excel" → Excel, Microsoft Office, …) — read the names and keep the relevant id. Then pass it to linkedin_unipile_search (location/company/industry already accept ids; the other facets are coming — see guide linkedin-search).

Returns {facet_type, candidates: [{id, name}]}. Resolution INDEPENDENT of the product/contract (works even outside Recruiter/Sales Nav).

Job postings and candidates of the LinkedIn Recruiter account (reads).

op:

• "postings" (default): the recruiter account's job postings. Paginated.

• "posting": detail of a posting (job_id from op="postings").

• "applicants": candidates of a posting. Paginated.

• "applicant": detail of a candidate (applicant_id from op="applicants").

• "projects": hiring projects. The hiring_project_id feeds linkedin_unipile_profile(op="action") (pipeline). Paginated.

Your LinkedIn network: 1st-degree connections and invitations. Inviting, answering or withdrawing an invitation is linkedin_unipile_act.

op:

• "relations" (default): your 1st-degree connections — to target/export your direct network. Paginated (cursor). Returns {items, cursor, …} — a single list. fields = PROJECTION: keeps only those fields on each item (e.g. ["name","headline","public_identifier","created_at"]), plus member_id always kept — reduces an export's payload. A key that no connection on the page carries is REFUSED, with the keys present. ⚠️ Pagination is NOT reliable for an EXHAUSTIVE export: the cursor encodes a volatile offset (duplicates in the offset space, overestimated total) and a limit=100 page returns 90-100 items, not 100. To load a whole network: deduplicate by member_id (NEVER the offset), keep ≤6 pages in parallel, ~20 s between two salvos (measured: 8 in parallel → 429 "We only allow 10 requests" on 3 of them; beyond that, cascading 502s), prove exhaustion with 2 staggered passes. ⚠️ These six precautions are ALL there is to know: they live here, there is no page to go read. The bulk-load guide deals with something else — delegating a big load to a sub-agent — and says nothing about the pagination traps above. ⚠️ An incomplete load does NOT RAISE, it returns fewer people: a process that reads the absence as "not a connection" will then act on a wrong answer.

• "invitations": the connection invitations. direction='received' (received, to accept) or 'sent' (sent, pending). Paginated — limit (default 50, MAX 100: beyond that upstream returns "Invalid querystring"; and with no limit the whole backlog exceeds the token limit). For the next page, pass the cursor RETURNED by the previous call — and only that: a hand-made cursor is refused. No more returned cursor = end of the backlog (a SHORT page is not the end), unless pagination_note is present: it then says why pagination stopped there, and there is nothing more to ask for. direction is repeated on each page, it cannot be deduced from the cursor.

LinkedIn posts: your home feed, a post, its engagement. Publishing, commenting and reacting is linkedin_unipile_act (op="publish_post" / "comment_post" / "react_post").

op:

• "feed" (default): your LinkedIn home, read LIVE — one page per call, sorted by publication date (most recent first), nothing stored. Sponsored/promo inserts are excluded. The choice of posts follows your LinkedIn home setting. Next page: pass the returned cursor again (None = end of the stream). Returns {items, cursor, count}. Served as a TRIAGE VIEW: each post returns enough to rank it (author + headline, date, traction, link, urn) and its text cut at 600 characters (text_truncated: true marks the cut) — a page of 40 raw posts exceeds the size of a tool result, and sorting a feed is done on the header. Nothing is lost: fields=["*"] returns all the post's fields, text_max_chars=None the full text, and a whole post is read with op="get" (post_id=<urn>).

• "get": a post — post_id = social_id (urn:li:…) from a linkedin_unipile_profile(op="posts") result.

• "engagement": who reacted/commented — kind='comments' or 'reactions'. Follows the pages up to limit people (default 100, max 500); returns {items, count, truncated, next_offset, stopped} — truncated: true says that the list is PARTIAL, resume with offset=next_offset. comment_id targets a comment's replies (comments) or reactions (reactions). An Unipile 429 is the unipile_rate_limited refusal (delay in retry_after_seconds); after a first page, it returns the partial result.

A LinkedIn member or company: read their profile and their activity. Acting on a member (endorsing a skill, a Sales Navigator / Recruiter action) is linkedin_unipile_act (op="endorse" / "update_member").

identifier = public slug (marie-dupont; a full linkedin.com/in/… or /company/… URL is brought back to it) or URN (ACoAA…). NOT the numeric member_id from linkedin_unipile_search: the v2 API rejects it (400 Invalid User ID) — go through the slug, which these ops resolve for you.

op:

• "person" (default): full profile (dated career, schools, network). ⚠️ LinkedIn may throttle a section (often experience): the response then carries throttled_sections=[…] with the section empty despite a *_total_count > 0. This is an UPSTREAM rate-limit, not an absence of data: retry later (minutes), reduce concurrency (≤8 in parallel), and in a batch handle these targets in a deferred catch-up pass. Also CHECK that the returned public_identifier/id == the requested one before writing (reject + retry otherwise).

• "company": company profile. Cached 6h per account (~static profiles) — the same company looked up again does not consume the upstream quota (~100 profiles/12h per account).

• "me": profile of the connected account itself (the "me" under which the other ops act). No identifier.

• "posts" / "comments": what a member publishes / comments — to spot a post to comment on/like, or what a prospect engages with. Each item's text is served as an EXCERPT (600 characters, cut marked text_truncated: true): the raw is 55-75 KB for 10 posts, and triage is done on the header. text_max_chars=None returns the full text, op="get" of linkedin_unipile_post a specific post. To slim further, fields (e.g. ["text","posted_at","social_id"]) keeps only those fields — id/ social_id are always kept so you can chain.

• "reactions": posts a member has liked.

• "followers" / "following": followers of the connected account, or of a member via identifier. Paginated.

LinkedIn search via Unipile.

⚠️ Recruiter / Sales Navigator faceted search (skills, industry, location, employer): first read the guide oto_guide(op=read, slug="linkedin-search"). Four traps that SKEW results silently: (1) a facet requires a resolved ID — pass the term through linkedin_unipile_facets and give the chosen id; a raw term does NOT filter; (2) the url= mode is capped at 25 without pagination — prefer the structured one to control the filters, not for volume: it is the PRODUCT (api=) that decides on pagination (classic does not paginate, whatever the mode); (3) a facet may be NOT applied by the chosen product, without an error (measured: same employer → 0 in sales_navigator, 10 in classic) — a 0 on a faceted search does not prove an empty pool, cross-check; (4) pagination is CURSOR-ONLY: the filters passed alongside the cursor are not re-applied, and page 2 sometimes loses the employer filter — check the employer of the items of a paginated page.

The return: always items + cursor. total_count only when upstream announces one — the ordinary tier (api="classic") carries none: no population count by this route. When it is there, returned + truncated: true say that the page returns less; truncated without cursor = the rest is UNREACHABLE (product cap, e.g. 25 out of 86). Without a total, neither returned nor truncated: the absence of cursor then does NOT prove a complete sweep, and a warnings says so. Read warnings before reporting "empty pool" or "population swept".

⚠️ Cadence: LinkedIn rate-limits per account. Chaining dozens of calls in a burst triggers a 429, then DEGRADES and ends up DISCONNECTING the account. The requested backoff FOLLOWS your recent cadence: a few seconds after a light burst, up to ~1h after a sustained chain — read the returned delay, do not assume it is short. Space out your calls; on a 429, respect THAT delay and SLOW DOWN — do not insist. For volume, delegate the pagination to a sub-agent (guide bulk-load).

company/location/industry accept NAMES (automatically resolved into LinkedIn facets) or numeric facet ids. ⚠️ The LinkedIn company page is NOT a valid employer facet id for people search — pass the name and let the client resolve.

⚠️ COMPANY fields missing from the result (size, description, industry): enrich them per DISTINCT company, never per profile. Deduplicate the employers of your results (far fewer than the people), then linkedin_unipile_profile(op="company", identifier=<name or slug>) for each — the profile is CACHED 6h, a re-looked-up company does not consume quota again. For French companies, fr_search gives the headcount (= the size) FOR FREE, with no LinkedIn quota. Do NOT query each person one by one for these company fields (that is the "844 calls" trap: counting per profile what is done per employer).

An article of a French consolidated code (LEGI) — its text as in force at a given date, its version timeline, or finding it by concept.

THE tool for citing law: exact text + verifiable Légifrance URL.

op:

• "get" (default): consolidated text of a French code article (code + num), as in force at a given date.

• "versions": full version timeline of a code article (code + num) — every rewriting with dates and statuses. Use to see WHEN an article changed before picking a date for op="get".

• "search": full-text search across French consolidated codes (LEGI). Find the article when you know the concept but not the number ("période d'essai CDD", "clause de non-concurrence").

List the 22 French consolidated codes covered (alias → LEGITEXT + label). Discovery helper for loi_article — both its code argument and its op="search" filter.

Mailpool workspace: subscription slots and warmup.

Ops:

• slots — mailboxes used vs paid, per type, and warmup slots. A new mailbox needs a free slot (buying slots is not served here).

• warmup — inboxes enrolled in Mailpool warmup, with status.

• warmup_inbox — one enrolled inbox (warmup_id): settings, counters.

• warmup_available — active mailboxes not enrolled yet.

Edit a Mailpool domain's DNS records — preview first, then apply.

dry_run=True (the default) reads the current records and returns the exact diff (added, removed) without writing anything. Re-call with dry_run=False to apply. Nothing is sent when there is no difference.

Changes, combinable:

• spf_hard_fail=True — end the apex SPF record in -all instead of ~all. Only once every service sending as this domain is listed.

• dmarc_report_email — where DMARC reports go. The record is also normalised: fo, rf, ri are dropped, policy and alignment kept. Mailpool always publishes the address as rua AND ruf. ⚠️ A domain without _dmarc gets one with p=quarantine; sp=quarantine; pct=100.

• tracking_host + tracking_target — a custom tracking domain, e.g. track → custom.lemlist.com (the target comes from the sending tool). Replaces any CNAME already on that host.

• add_records — NEW records next to the existing ones, e.g. a verification TXT a sending tool asks for. Never a second SPF: to change SPF, use spf_hard_fail or remove the old record and add the new one in the same call.

• remove_records — records to delete, matched exactly.

Safety: a change that would add an audit error (second SPF or _dmarc, MX, SPF or DKIM gone, CNAME next to other records) is refused, preview included. A DNS write replaces the WHOLE record set, so the full set is always sent, read back, and the previous set restored if a record went missing. Public DNS follows within ~5 minutes. After dry_run=False, an error whose reason is dns_outcome_unknown, dns_not_kept or partially_applied means records may have changed: re-read them with mailpool_domains(op="dns") before calling again.

Mailpool domains: read them, audit their deliverability setup, look up a new name.

Ops:

• list — the workspace's domains (type google/outlook/shared/private, status, expiry, redirect). limit (1-100) / offset paginate.

• get — one domain (domain_id).

• dns — the DNS records Mailpool holds for a domain (domain_id), as {type, key, value, priority}; key is the host label, null = apex.

• audit — findings on SPF, DKIM, DMARC, MX, CNAME conflicts and custom tracking domain, worst first, for one domain (domain_id) or a page of domains (at most 20 per call: total and next_offset say what is left). Read from Mailpool's stored configuration, not a live DNS lookup. Fix what it finds with mailpool_domain_fix.

• availability — can domain be registered, and at what price. Nothing is bought (registration is not served by this connector).

• suggestions — available names close to domain, with price.

• google_workspace_check / microsoft_365_check — is domain already used by a Google Workspace / Microsoft 365 account (enabled per Mailpool workspace, otherwise refused).

• owners — saved registrant contacts (company and country only).

Mailpool mailboxes: address, name, type, status, domain, IMAP/SMTP hosts.

Credentials (mailbox, IMAP/SMTP and admin passwords) are never returned; they stay in the Mailpool dashboard.

Ops:

• list — the workspace's mailboxes, optionally of one domain_id. limit (1-100) / offset paginate.

• get — one mailbox (mailbox_id).

Mailpool spam checks: send a test email from a mailbox and score it.

Ops:

• run — check mailbox_id. Free. With wait=True (default) waits up to ~20 s for the result (usually a few seconds); a check still pending after that is returned as is, to read later with op="get". Some mailbox types are refused by Mailpool (404).

• get — one check (spam_check_id) with its detailed results.

• list — past checks with score and per-check status.

• delete — remove one check (spam_check_id) from the history.

Results: score (0-100) and checks — SPF, DKIM, DMARK (DMARC), domainAge, reverseDNS, ipBlackList, domainBlackList, spamAssassin, shortUrls, brokenLinks — each passed / warning / error.

Aggregated calling metrics — answer "what's our connect rate" with one call instead of downloading and summing calls yourself.

DEFAULT WINDOWS DIFFER, and getting this wrong silently returns the wrong period: "overview" and "users" default to TODAY; "objections" defaults to the LAST 7 DAYS. Always pass start_date and end_date together when you mean a specific range. Analytics are day-granular, and the resolved window comes back in period next to the data.

Rates are percentages (0-100) and are null when their denominator is 0. The per-user rows sum to the overview totals for the same filters.

"lists" is the all-sources view of list progress (CSV, HubSpot, …) — use it, not minari_list, to answer "which lists are stalled".

Calls made and received in Minari, with AI summaries and objections.

Covers ALL sources (CSV imports and CRM-synced contacts alike), unlike minari_list.

"get" deliberately OMITS the transcript and reports transcript_utterances instead — a 45-minute call would otherwise bury the summary and objections you asked for. Use "transcript" for the text.

Search two different ways: search matches the contact (name, company, phone number); transcript_search matches what was SAID. Transcript search is a literal substring match, words AND-ed, never semantic and never translated — so a French call will not match English terms. Each row carries language; re-issue in that language (or scope with language="fr") to search across locales. Both need 3+ characters.

"recording" returns availability and size, NOT the audio — an MP3 has no useful form in a tool result. For something a human can open, a call carries public_call_link, a shareable page needing no key — but it is null when the company has external call sharing switched off, so check it rather than promising someone a link.

Add contacts to, or remove them from, an existing Minari list.

Same CSV-only scope as minari_list.

"add" tops up a list a rep is already working. Up to 1500 per request, and a list caps at 1500 total: contacts beyond the cap are SILENTLY skipped and counted in skippedCount — the request still succeeds, so read that number rather than assuming everything landed.

"remove" takes contacts out of the list by contact id (the contactId of minari_list(op="get")). Minari refuses to empty a list this way — that is minari_list(op="delete").

Custom contact fields — the metadata keys an import may carry.

A key must be registered here BEFORE it can be used in the customFields of an imported contact. The contract states the requirement but not how a breach fails (rejected request? key dropped? contact skipped?) — so register first rather than relying on the error.

"delete" removes the field from future imports and from the UI.

Contact lists — the call lists reps work through.

SCOPE WARNING: these endpoints see the CSV-import source ONLY. A company whose contacts come from HubSpot or Salesforce has real lists that never appear here, so an empty result means "no CSV list", not "no list". The all-sources view is minari_analytics(op="lists").

"create" is how you push a prospecting list into the dialer: build the contacts elsewhere, assign the list to a rep, and it appears in their Minari. A contact already known to the account is ADDED to the list rather than duplicated; its stored fields stay untouched unless update_existing_contacts=True (a blank value never overwrites).

A list holds at most 1500 contacts, and at most 1500 can be sent per request.

"delete" is PERMANENT and takes the list's contacts out of the rep's queue. It cannot be undone from this tool or from Minari.

Active team members of the Minari company.

Their id is what every user_id filter expects, and what minari_list(op="create") needs as assigned_to. Only members who accepted their invitation appear.

Mux Video, read-only: the videos (assets) of the token's environment, and the direct uploads that make them.

op:

• list_assets — newest first: id, status, duration (seconds), resolution, playback ids, passthrough, title. limit 1-100 (default 25), next_cursor in the answer goes into cursor. With upload_id: the asset that upload made. Tightened by default (tracks, rendition and master-file settings, input diagnostics), the answer's projection naming what was removed: full=true returns the raw records.

• get_asset — one asset (asset_id). status is preparing until Mux has processed the file (about the film's length), then ready or errored (with errors).

• get_ingest — one direct upload made by mux_act op='create_upload' (upload_id): status is waiting until the file is PUT, then asset_created with its asset_id (or errored, cancelled, timed_out).

Every PUBLIC playback id carries its stream_url (https://stream.mux.com/<id>.m3u8, HLS), the address a player takes.

Get a video into Mux. Each call makes a new upload or asset (never retried, no deduplication): Mux bills storage and delivery per video.

op:

• create_upload — a direct upload address. The answer's data.url takes the video file in ONE HTTP PUT, with no credential (the address is the authorisation), from wherever the file is: e.g. curl -X PUT --upload-file film.mp4 -H "Content-Type: video/mp4" "<url>". The file never passes through this tool. Then mux op='get_ingest' gives the asset_id, and op='get_asset' says when it is ready. The address expires after timeout seconds (60 to 604800, default 3600).

• create_asset — a video from a file Mux fetches itself at input_url (https, public or pre-signed). The answer's data.id is the asset.

Playback is public unless playback_policy="signed" (a signed playback needs tokens this connector does not make). test=true makes a free 10-second watermarked video, deleted after a day: for trying the flow.

Ask Origami's agent to DRAFT a campaign on a table (WRITE — creates the campaign and its per-person sequences; sends NOTHING — launching is a separate, explicit tool).

The call is agentic: instructions (1–10 000 chars: audience, channels, tone, offer, follow-ups…) is handed to the Origami agent, which answers 202 {agent: {id}, run: {id}, table}. Poll origami_run_get(agent_id, run_id) until status != "running"; the drafted campaign then appears in origami_campaigns(op="list_for_table", table_id=…). Review it (get, people) BEFORE origami_campaign_launch.

⚠️ These two settings govern a campaign this call CREATES — not one the agent enrols into. If your brief makes the Origami agent add people to a campaign that already exists, that campaign's own settings apply and yours have NO effect, even though they are echoed back to you. Nothing in this connector updates an existing campaign's settings: read what actually governs with origami_campaigns(op="get") → settings, and if it is wrong the change is a human action in Origami.

⚠️ Check the result, do not trust the run's prose. The agent answers in words; those words are not a measurement. A run can end completed having done NOTHING, with prose that names a campaign and a slug that were never created (measured 2026-09-09: three times in a row on one table) — or report people added while its action list is empty. origami_run_get REFUSES such a run (error aucune_action, nothing reachable was created: verify the table with origami_campaigns(op="list_for_table"), then relaunch ONCE — such a run may still leave a draft shell visible only in the Origami interface, invisible to every verb here, and each relaunch adds one; tell the human to check the campaign list in Origami). The state that settles it is the campaign itself: if found rises while contacted does not, the new sequences have no recipient and nothing will ever send to them.

Settings — REQUESTED, not guaranteed: Origami has been measured ignoring them on a campaign this call created (2026-09-13, reproduced). Always read what governs with origami_campaigns(op="get") → settings once the run is done; stating the setting in words in instructions as well has made it stick in practice. If it is still wrong, the fix is a human toggle in Origami:

• block_prior_contacts=True (default): auto-cancels every person who was EVER enrolled in a previous campaign — INCLUDING people who sat in a deleted, never-sent draft. Pass False ONLY when the prior enrolments were drafts that never actually sent to anyone; keep True to protect real past recipients from a second cold approach.

• block_active_duplicates=True (default): auto-cancels people who are currently active in another campaign.

dry_run=True validates and returns {dry_run: true, would_create: {...}} without calling Origami. Errors: 402 INSUFFICIENT_CREDITS, 409 AGENT_BUSY (an agent run is already going on that table — poll it), 429 CONCURRENT_LIMIT_EXCEEDED (plan cap on concurrent agent runs).

Delete an Origami campaign — TWO-STEP, and verified. WRITE.

Step 1 (confirm=False, default): Origami returns the impact preview {id, name, confirmationRequired: true, status}; nothing is removed. Step 2 (confirm=True, dry_run=False): soft-deletes the campaign (its picker halts instantly) and cancels its orphaned sequences. Because the second step can answer 200 WITHOUT deleting, the tool re-reads the campaign afterwards: really_deleted: true only if the re-read is a 404; otherwise really_deleted: false + the current status — do not report it as deleted. dry_run=True forces the preview even with confirm=True.

LAUNCH an Origami campaign — this SENDS emails and LinkedIn messages to the enrolled people. IRREVERSIBLE once messages leave.

dry_run is True by default: the tool then reads the campaign (status, channels, settings) and asks Origami's own ?dryRun=true preview ({dryRun: true, campaignId, wouldLaunch}) — nothing is sent. To actually launch you MUST pass dry_run=False, after reviewing the people (origami_campaigns(op="people")) and the drafted copy.

The real launch marks the campaign active and runs the launch pipeline (sender gate, duplicate auto-cancel, per-account scheduling); it is idempotent on an already-active campaign. Read the result: launched = drafts scheduled; result.launch.{scheduled, firstScheduledAt, missingRecipientCount, duplicateActiveCancelledCount, duplicatePriorCancelledCount}. If result.launch.blocked is present (blocked.missingChannels, echoed as blocked_missing_channels), NO sending account is connected for those channels and NOTHING was sent — connect the email / LinkedIn account in Origami, then relaunch. There are no override knobs: send windows, daily caps and spacing are the campaign's own settings, set through the agent.

Pause an active Origami campaign — halts further sends (idempotent: pausing a paused campaign is a no-op). WRITE.

dry_run=True asks Origami's ?dryRun=true → {dryRun: true, campaignId, wouldPause}, no writes. The real call returns the transition with pause: {stoppedSequences, haltedSteps, inFlightSending, alreadyPaused} — inFlightSending messages already handed to the provider still go out.

Resume a paused Origami campaign from where its sequences stopped (idempotent) — this SENDS again. WRITE.

dry_run=True asks Origami's ?dryRun=true → {dryRun: true, campaignId, wouldResume}, no writes. The real call returns the transition with resume: {resumedSequences, noAccountSequences, missingChannels} — missingChannels non-empty means those channels have no connected sending account and their sequences did not resume.

Read Origami campaigns — an email + LinkedIn campaign is a set of sequences (one per enrolled person) that send from a table.

op:

• "list_for_table": the campaigns sending from table_id — {items: [{id, slug, name, status, peopleCount}]}. There is NO global campaign list: list per table, or see every sequence of a workspace with origami_sequences(workspace_id=…).

• "get": one campaign — {id, name, status: draft|active|paused, workspaceId, tableId, channels: {email, linkedin}, settings: {blockPriorContacts, blockActiveDuplicates, autoTopUpEnabled}, brief}.

• "stats": {found, contacted, connectSent, connectAccepted, connectionRate, replied, replyRate, hasEmail, hasLinkedin}.

• "people": the enrolled people — {items: [{sequenceId, rowId, recipient, sendStatus, stopReason, fitScore, fitExplanation, profile, addedAt}], total, nextCursor}; status = CSV of send-status buckets, search = substring; pass nextCursor back as cursor.

Rows of an Origami table — read them (flat {slug: value} rows, following the cursor) or upsert them (the ONLY write path for rows).

op:

• "list": {count, total, pages_fetched, cursor, truncated, items}. Pages are 50 rows (limit ≤ 200); the server follows nextCursor up to max_pages (cap 20). truncated: true + cursor = there is more — call again with that cursor.

• "upsert" (WRITE): rows (1–100 dicts keyed by input-column SLUG) matched on match_columns — a row whose match values all equal an existing row UPDATES it, otherwise it is INSERTED. Slugs come from origami_tables(op="columns") (items[].slug, hyphenated); only kind == "input" columns are writable. The tool reads the columns first and refuses unknown / non-input slugs with the list of valid ones (the API would answer 400 UNKNOWN_FIELDS). dry_run=True runs the same validation and returns {dry_run: true, would_upsert: {rows, match_columns, enrich, keys, sample}, check} — nothing written. The real call returns the enrichment_run receipt {id, counts: {inserted, updated, skipped}}.

Poll an Origami agent run — the follow-up of origami_campaign_create (which returns agent_id + run_id).

GET /agents/{agent_id}/runs/{run_id} — there is NO GET /runs/{id}, the run lives under its agent. Returns the run object: status ("running" until terminal), steps, response (tables touched, transcript with include="transcript", economics with include="stats"). Poll until status != "running", then read the drafted campaign with origami_campaigns. A terminal run whose action list is EMPTY is REFUSED (error aucune_action): it created nothing reachable, whatever its prose says — verify with origami_campaigns(op="list_for_table"), then relaunch origami_campaign_create ONCE (a refused run may leave a draft shell visible only in the Origami interface; each relaunch adds one).

Origami sequences — one sequence = one enrolled person in a campaign.

Pass exactly one of:

• workspace_id → GET /sequences?workspaceId=: EVERY sequence of the workspace, each with its campaignId, status, sendStatus, stopReason, tableId, rowId — the only view that sees all campaigns of a workspace at once (there is no global campaign list). Pages are 50; the tool follows nextCursor server-side up to max_pages (default 10 = 500 sequences) and returns campaign_ids, the DISTINCT campaigns seen, plus truncated/cursor when more remain — pass cursor back to continue. Filters status / channel (email|linkedin) / recipient.

• sequence_id → the sequence with its steps inline (message copy per step; provider internals redacted).

Origami tables (lead lists) — list them, read one, or read its columns.

op:

• "list" (default): every table of the org, or of workspace_id if given — {items: [{id, workspaceId, name, leadCount, columns, credits, url}], nextCursor} (50 per page; pass nextCursor back as cursor).

• "get": one table by table_id — name, leadCount, columns, credits consumed (credits.lifetimeUsed); include_stats=True adds the economics block (creditsPerLead, qualification, funnel).

• "columns": {items: [{id, name, slug, kind, autoTrigger}]} — READ THIS BEFORE ANY UPSERT: row keys and match_columns are the slug values (hyphenated, e.g. first-name) of kind == "input" columns, never the display names. Enrichment / score / sequence columns are not writable.

Create an Origami TABLE from a CSV — the ingest verb POST /workspaces/{id}/documents, JSON with the file base64-encoded (never multipart). WRITE.

mode="table" (default): the CSV becomes a NEW table in workspace_id, its header row = the input columns. mode="append" is REFUSED: Origami does not bind the CSV header to the table's columns and creates new ones on every call — rows go into an existing table with origami_rows(op="upsert", table_id=…, match_columns=[…]), which checks the column slugs. dry_run=True parses the CSV and returns {dry_run: true, would_upload: {filename, mode, columns, rows, preview}} (first rows) without uploading. The real call returns the per-file results[] (an entry may be kind: "error"); the new table then appears in origami_tables(op="list", workspace_id=…).

Origami workspaces — the containers of tables, documents and campaigns.

op:

• "list" (default): {items: [{id, name, url, createdAt}], nextCursor}. search filters by name substring; pass nextCursor back as cursor.

• "create": creates a workspace named name (WRITE — needed before an upload-first flow). dry_run=True validates and returns {dry_run: true, would_create: {name}} without creating.

Exhaustive OpenStreetMap POIs carrying a tag over an area (Overpass).

Returns EVERY OSM object matching selector in the area, in ONE call — no result cap or pagination (unlike Maps APIs). Ideal for counting/listing infrastructure or businesses of a type for site analysis.

selector: an OSM tag "key=value" (e.g. "shop=laundry", "amenity=parking", "amenity=school") or a bare key ("shop"). Area: give EXACTLY one of commune (5-digit INSEE code, e.g. "13055" = Marseille), departement (2-3 chars, e.g. "13"), or bbox = "south,west,north,east" lat/lon.

Returns count + pois (each: osm_type, osm_id, name, lat, lon, postcode, tags). ⚠️ Coverage varies by tag: infrastructure (parking, schools, transport) is well mapped in OSM; consumer businesses less so (shops list on Google, not OSM) — for a full business census, cross with serper_maps_census.

Shared connector accounts (#55) — who may OPERATE your connected messaging accounts, acting as you. op=list (grants you gave + grants you received) / grant (channel linkedin|whatsapp|…, grantee=email or sub — even outside your orgs; owner-only, audited) / revoke (immediate effect). Deny-by-default: no grant = nobody but the owner.

[platform admin] L7 shadow window (ADR 0053): during the double-read window the grant CHAIN computes alongside while the legacy cascade decides; every pair of verdicts is compared and filed under a closed set of classes. op=read (days, default 7; optional connector, classe) → one row per day x connector x org x class, with the first sample of the day (sub is hashed, never in clear), plus a verdict block. These divergence classes are EXPECTED and named by the ADR — elargissement_equipe (the chain reads every team of the caller, the cascade only the ACTIVE one; counted per org because it changes served behaviour), free_tier_hors_modele (an open platform key has no grantee in 0053 — the everyone-edge exists now (grants_chain.EVERYONE, the platform scope), so this counts what is LEFT to migrate and reaches zero once the seeding command has run), partage_hors_modele (its sibling: a platform key CLOSED on an allowlist that no edge accounts for — the NOMINAL edges are missing, L5 only seeded the switched connectors), perso_cross_org (the cascade follows a personal key across orgs). Only inconnu must stay at zero: verdict.porte_ouverte is true when there is no unknown divergence AND the denominator is non-zero, for the origin it names; verdict.origine_inconnue counts observations left out because they predate the origin column. Read-only — the counter is fed by the resolution path and switched off by the OTO_L7_SHADOW env, never from here.

Pause an account without deleting anything. op=suspend (target = the account's sub — NOT an email; reason required) → the account can no longer do anything, on any face, from its very next request: a token issued before the pause stops working immediately. NOTHING is deleted or detached — org memberships, projects, documents, datastore rows, vault credentials and journal entries all stay, and still name this account as their author. The account keeps its seat in member lists, flagged as paused. What it LENT (connector accounts, keys lent to peers) stops with it — borrowers get a named lender_suspended refusal — and comes back unchanged on resume. op=resume (target) → lifts the pause; it is the only way back, no automatic mechanism can revive a paused account. Super platform admin on anyone; a tenant admin on accounts of their OWN tenant, with no platform role. Not an org admin: an account is not owned by an org, and pausing it would cut spaces that admin has no title over — to act on ONE org only, remove the member with oto_admin_org_member.

[platform admin] Failure EPISODES of hosted agents, across every org, and the closed list of repairs allowed on them. An episode = an enabled agent's dead jobs since its last success; the background loop opens it at the first dead job, classifies it (classe; cote = who can fix it: plateforme | proprietaire | inconnu), re-runs transient platform failures by itself, and closes it on the next success. op=list (statut, default vivants; org_id, cote, limit) / get (episode_id → the episode, the agent, and its last dead job: status, attempts, last_error — never its result nor its per-attempt log) / rerun (re-queue the last dead job — refused, with the reason in refus, when the episode is closed, the agent is off, the fault is the owner's, the job was already re-run, it is older than 24 h, an occurrence is already waiting or running, or 2 re-runs were already spent; it re-queues the job as it was, reading none of the agent's content. ⚠️ No guard knows whether the dead run already wrote or sent something: a re-run redoes it) / diagnose (diagnostic, and/or a corrected classe/cote — kept: the loop no longer reclassifies that episode) / escalate (hand it to a human, with your diagnostic) / close (resolution). Nothing here touches a key, an identity, a procedure, a schedule or any data: those fixes belong to the agent's owner — say what they are in diagnostic.

Connector properties that the DATABASE may override, per platform or per org — the registry constant is only the default. op=list / set (connector, key, value; org_id omitted = platform-wide) / clear / reload. Keys: cardinality (mono|multi): how many accounts one entity may hold for that connector; platform.ops on forager, platform-wide: what the shared key serves, comma-separated tool:op or tool (default forager_person:phone_numbers, read at each call); the same key on elevenlabs (default elevenlabs_act:create_speech). ⚠️ Overrides are held in MEMORY, so a row takes effect only after reload — and reload is PER-PROCESS: reloading preprod does not reload prod.

Déprécié : utilisez oto_admin_guide (retrait le 30/11/2026). [ADMIN] Another org's guide, by org_id (cross-org = platform admin). op=get (slug = one skill, none = base+index; scope=group) / list (named guides incl. base) / set (write: omit slug = base; from_version restores; slots = required entities ADR 0035) / delete (exact slug, drops history).

[ADMIN] Another org's guide, by org_id (cross-org = platform admin). op=get (slug = one skill, none = base+index; scope=group) / list (named guides incl. base) / set (write: omit slug = base; from_version restores; slots = required entities ADR 0035) / delete (exact slug, drops history).

[platform admin] Instance health for PLATFORM GUIDES: what this server's boot did with the repo files oto_mcp/guides/*.md — seeded, updated, unchanged, and the three defects that need a human: guides_non_semes (the seed failed for that slug), guide_divergent (the DB copy was edited since its last seed, so it is KEPT and the repo file is NOT served — ADR 0042), guides_sans_empreinte (rows written before the seed started fingerprinting; run scripts/aligner_guides_plateforme.py once). fait: false means this process seeded nothing — that is a defect, not silence. A served guide that lags the repo makes every agent apply gestures that no longer exist. Read-only.

[platform admin] Is a THIRD PARTY's connector session still alive? Runs the login probe the connector itself declares, against that instance's stored browser context, and returns a verdict — connected / rejected upstream / probe unavailable — with the reason and whether logging in again would help. Answers the support question 'must they reconnect, or is it something else?' without an SSH session and a throwaway script. ⚠️ It runs ONLY the declared probe, never a request you choose: no business data is read, nothing is written, and the browser session it opens is ephemeral. connected: null means the probe gave NO verdict — that is 'unknown', not 'logged out'; telling someone to log in again on that basis is how a whole morning was lost.

Invite users to the oto platform (feature cascade, platform tier). op=create (optional email + org_id to attach directly to an org with role org_member|org_admin — omit org_id for pure onboarding; send_email=false returns the link only) / list (pending platform invitations) / revoke (invite_id). Platform admin.

Platform keys as a RIGHT — never reveals the secret. op=list (which vendors oto contracts: provider, label; optional provider filter; platform admin) / grant|revoke (by provider, super admin) · scope=user (target email|sub) | group (group_id, the team's members while it is their active one) | org (org_id); grant takes optional daily_quota (per day, in the unit the key's tool meters). daily_quota is REQUIRED (> 0) for elevenlabs (ElevenLabs credits), higgsfield (micro-dollars (US$ 0.000001) of job price), counted in that unit — absent or 0 (unlimited) is refused with grant_quota_required. To POSE a raw key/secret, use the dashboard.

[platform admin] The PROOF that someone accepted a legal document: every acceptance in the journal, newest first, with what situates it — date, IP, user agent, context (access|purchase) and the org that was paying. Use it when an acceptance is disputed; me.legal.get answers 'is he up to date?' and keeps only the latest row per document, which is not a proof. ⚠️ total counts the WHOLE set, not the page returned. ⚠️ A null ip / user_agent / context means NO TRACE WAS RECORDED — never 'no trace existed'; the origin of a row cannot be deduced. ⚠️ url is served only when the accepted version is the current one: the registry keeps no past texts, so an old acceptance cannot be tied to what it accepted.

[platform admin] Reconciles one UTC day (default: yesterday), in TOKENS, of what ANTHROPIC counted on this instance's platform anthropic keys — its own usage report — against what the units budget settled for model calls on the platform rung (anthropic.messages:<model>). Per unit (input, output, cache write, cache read): per platform key its Anthropic tokens, the totals, gap_tokens (positive = tokens no settlement carries), by_model (the same per model, snapshot date dropped), other_keys (tokens on any other key of the Anthropic organization: unmetered by construction; null id = Console) and unmatched_platform_rows. No tariff, no money. Platform keys are matched to Anthropic's by partial_key_hint. Cannot attribute a gap to an org; tenant keys are out of scope. Read-only.

Platform observability console (platform admin). ⚠️ TWO journals, never one: summary/calls cover AGENT (MCP) calls ONLY — what a person does from the dashboard or the API is NOT there, it is in op=rest. An account at zero calls is therefore NOT an idle account: check op=rest before saying so. ⚠️ A filter an op does not read is REFUSED (error param_not_read_by_op), never silently ignored. op=summary (aggregates: totals, by tool w/ avg+p95 latency, by user, by day; optional days, org_id, sub email|sub) / calls (raw MCP call log, newest first; filters sub, tool, errors, days, org_id, run_id, session_id, min_duration_ms slow calls, error_contains) / call (call_id → full record incl. truncated args + correlation ids) / run (run_id → timeline; content_archived = body in cold archive, bounds kept) / runs (recent runs) / rest (REST lens by route — days, org_id, sub, and route (prefix match) for an EXACT count/errors/last_call_at on one route — by_route is capped at the top 100, so a low-volume route can be invisible there without saying so; by_status splits the errors by HTTP code over the same window and filters, so an expected 4xx is not read as an outage — status: null means NO response went through the log: an unhandled exception (the 500 is served above it — that is what a crash looks like) or a client that left; ⚠️ org_id here is the consultation org claimed by a header (best-effort): a request without it carries none and drops out of the filter, so a 0 does not prove an idle org — cross-check with sub) / rest_calls (raw REST call log, newest first, same filters as rest — route is a prefix of METHOD /route, e.g. GET /api/orgs — plus limit (max 200); the ONLY lens that serves view_as_sub: the account a platform operator's view-as was actually APPLIED to (operator verified, existing target other than themself), null otherwise — a refused or no-op X-Oto-View-As header leaves it null. Rows logged before 2026-09-21 carry the header as claimed, unverified) / connectors (credential resolution failures; optional org_id) / transport (MCP transport refusals by cause, plus rate_limit: the app rate limiter per env/class/mode — would_refuse is what enforce would cut, peak_pct the fullest bucket; and rate_limit_top: per day, env and limiter (debit | platform_rate | the process bounds), the top hashed keys enforce would cut — and under credits, the units-budget SIGNALS unpriced:<connector.function> / unreported:<tool>, not refusals; days) / funnel (accounts vs real usage) / gaps · tool_quality (aggregated usage signals) / agents_en_echec (hosted agents whose JOBS are dying, grouped by agent AND by reason — days (default 1), optional org_id; each row carries travaux, tentatives, depuis, dernier). ⚠️ This is the one nobody asks for: a triggered agent breaks SILENTLY — its queue empties because dead jobs stop waiting, its screen says active, and its last run can be green. Grouped by reason because three times the same fault is a bug to fix, while three different ones is a misconfigured agent — one count would read them alike. This is the lens a nightly report reads to say it in one line. / connecteurs_orphelins (no filter): the rows that NAME a connector absent from the served catalog — member installations, removals, activations, credentials, settings, live instances, org kits — per table and per name (lignes). Such a row resolves nothing: an installation that mounts no tool, a key nobody reads. Every table is listed, an empty one included, so a zero reads as checked; total = 0 is the healthy state. Read only: nothing is moved or deleted here. For raw signals use oto_admin_signal.