Research & records

A mission promotes a subject on social media. When the goal is instead to gather and track structured data — property prices, competitor pricing, leads, listings — use a research initiative rather than a mission.

Research sits on the same base layers as missions:

  Project (the container)
    ├─ records   ── the structured rows (a Notion/Airtable-style table)
    └─ knowledge ── the unstructured reference material

A record is one row in a project dataset. Columns are defined per project; values are typed (number, text, checkbox, date, …). Records are searchable and deduplicated, and they stay off the task kanban — they're a dataset, not cards.

How it fits together

  1. research.start creates the research project (the dataset container), optional columns, and a default table view.
  2. The agent builds a scheduled workflow that searches/scrapes, then calls records.upsert once per finding.
  3. records.query reads the dataset back with column predicates, filtered and paged in the database.

Because records.upsert dedups on sourceUrl, re-running the workflow updates existing rows (e.g. a new price) instead of piling up duplicates.

Use with AI

  • research_start — bootstrap the project + columns + table view.
  • records_upsert — add/update one row. Pass fields keyed by column name (missing columns are created automatically) and a sourceUrl for dedup.
  • records_query — filter by column predicate, e.g. where: [{ field: "priceUsd", op: "<", value: 150000 }, { field: "sqft", op: ">", value: 1000 }, { field: "beachfront", op: "is_true" }].

Example: "research beachfront homes over 1000 sqft under $150k in Baja." The agent calls research.start, defines priceUsd / sqft / beachfront / location columns, schedules a scraping workflow that records.upserts each listing, and the project's table view becomes the live, self-updating answer.

Use the API

# 1. Start the dataset
curl -X POST https://<host>/api/invoke/research.start \
  -H "Authorization: Bearer $NIHMBUS_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Baja beachfront < $150k",
        "fields": [{"name":"priceUsd","type":"number"},{"name":"sqft","type":"number"},{"name":"beachfront","type":"checkbox"}] }'
 
# 2. Add a finding (dedups on sourceUrl)
curl -X POST https://<host>/api/invoke/records.upsert \
  -H "Authorization: Bearer $NIHMBUS_API_KEY" -H "Content-Type: application/json" \
  -d '{ "projectId": "prj-…", "sourceUrl": "https://…/listing/123", "title": "3BR Rosarito",
        "fields": { "priceUsd": 142000, "sqft": 1100, "beachfront": true } }'
 
# 3. Query the dataset
curl -X POST https://<host>/api/invoke/records.query \
  -H "Authorization: Bearer $NIHMBUS_API_KEY" -H "Content-Type: application/json" \
  -d '{ "projectId": "prj-…", "where": [{"field":"priceUsd","op":"<","value":150000}] }'

Reference