SOURCE_ID: import_from_grain NAME: Import Grain Meetings CATEGORY: First-party Import Grain meeting data (transcripts, summaries, action items, and highlights) into Floqer, either as a one-time historical pull or as an ongoing source that re-syncs on a schedule. Imported records become available to your Floqer workflows for CRM enrichment, follow-up automation, and the like. Grain is a meeting notetaker; this source works the same way as the Fireflies source, and its rows reuse the Fireflies event types and column names where the data matches. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_grain`. POST /api/v1/sources/import_from_grain/preview Scope: sources:read Returns a sample page of records (up to 5 rows in the app, up to 100 on the public API) without creating anything. Use this to validate the entity selection and inspect row shape before committing. POST /api/v1/sources/import_from_grain Scope: sources:write Creates the source, imports matching records immediately, and, for an active source, keeps re-syncing on a schedule. Returns `source_instance_id` (the new source's UUID). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? }. `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Source-agnostic. This source has no dynamic-options endpoint (see §6). Every endpoint first verifies the API-key user has an active Grain connection. Missing connection returns 424. 2. IMPORT TYPE (ONE-TIME VS ONGOING) `import_type` is optional and defaults to "static". Values: "static" One-time import. The source imports matching records once and stops, with no recurring schedule. "active" Ongoing source. Imports matching records initially AND keeps picking up new data on the cadence in `frequency` (a cron string) until `expiration_date`. Each scheduled pull re-reads the recordings that started since the earlier of 7 days ago and the last completed pull, never before the list's `start_date` when one is set. Rows that already exist (matched by `uid`) are updated, new rows are added, and only the new rows are pushed to connected workflows. Rows still on the list are never pushed again. Recordings whose transcript row already exists are not re-fetched. This catches summaries, action items, and highlights that Grain finishes producing a few days after the meeting. `frequency` is required when `import_type: active` on create. Otherwise it is ignored. 3. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400. The body is strict. Preview accepts: entities required: non-empty array of entity slugs (see §5) start_date ISO date; optional (earliest meetings to pull) import_type "static" | "active"; optional (defaults to "static") frequency cron string; required when import_type === "active" (create) expiration_date ISO date; optional (active source only) Create accepts all the preview fields plus: name required: display name for the new source 4. FIELD CATALOGUE entities (string[]) required Non-empty array of Grain entity slugs to import. See §5. You can select more than one (e.g. ["meeting_transcribed", "highlight"]). start_date (string) optional ISO date. Only meetings from this date forward are pulled. Ongoing syncs re-read at least the last 7 days but never before this date. Omit to pull all history the connected Grain token can see. An empty string is rejected by the public API. import_type (string) optional "static" (one-time) or "active" (ongoing). Defaults to "static". See §2. frequency (string) required on create when import_type === "active" Cron string for the re-sync cadence (e.g. "0 12 * * *"). expiration_date (string) optional, active only ISO date after which an active source stops re-syncing. name (string) required on create only Human-readable display name for the source. 5. ENTITIES `entities` must contain only these slugs: meeting_transcribed Meetings that have a transcript meeting_summarized Meetings that have a Grain summary action_item Action items extracted from meetings (one row each) highlight Highlights saved on meetings (one row each) Any other value is rejected with a 400. Each selected entity contributes its own rows. A `meeting_transcribed` row appears only once the recording has a transcript. If Grain is still processing, an ongoing list adds the transcript row on a later pull while the recording is in the re-read window; a one-time list keeps the recording without a transcript row. Rows you delete from an ongoing list come back on the next pull, and are sent to connected workflows again, while the meeting is still in the re-read window. Once a recording's transcript row is stored, later pulls do not rewrite it. Title, participant or transcript changes made in Grain after that are not picked up. The summary comes as its own Meeting Summaries row. Timing: a `meeting_transcribed` row can arrive before Grain finishes its AI summary. The summary comes later as its own `meeting_summarized` row, so workflows that need the summary should use Meeting Summaries rows. Each page of recordings has a time limit (about two minutes during an import). Once it passes, the remaining transcripts on that page are skipped for that run. A transcript that Grain fails to return (no answer, an unreadable response, a server error, or a refusal such as access denied) skips only that recording. In both cases the recording's other rows still land. An ongoing list's next pull retries skipped transcripts while they are in the re-read window. A one-time list keeps them without a transcript row. Errors that end an import (Grain rejecting the token, repeated rate limiting, a failed recordings list call) still show on the list. In the app, if Grain cannot return transcripts for the preview at all, the preview shows an error instead of an empty result. 6. DYNAMIC OPTIONS None. There is no `POST /api/v1/sources/import_from_grain/options/` endpoint: the only enumerated field, `entities`, has a fixed list (see §5), and the rest are free-form. A Grain connection is still required for preview and create (424 if missing). 7. ROW COLUMNS Rows are events. Each row has an `event_type` (one of the §5 slugs), a `timestamp` (the recording's start time, or its end time when Grain has no start, absent when Grain has neither), and `source` set to "grain". Column ids match the Fireflies source where the data matches, so a workflow built for Fireflies rows runs on Grain rows. Only the columns listed for an event type are filled on its rows. Every row: uid A unique id per event (see the end of this section) source Always "grain" event_type meeting_transcribed, meeting_summarized, action_item, or highlight meeting_id The Grain recording id text Main text of the row (see each event type below) timestamp Recording start time, or end time when Grain has no start (datetime, absent when Grain has neither) title Meeting title, when Grain has one meeting_transcribed (one row per recording that has a transcript): text First lines of the transcript, shortened to 200 characters organizer_email Email of the first recorder date_string Recording start time as text end_timestamp Recording end time duration_min Meeting length in minutes attendees Everyone on the meeting, each with name, email, `scope` (internal or external), and `confirmed_attendee` participants List of attendee emails external_participants List of emails of attendees whose scope is external speakers Distinct speaker names from the transcript sentences_count Number of transcript lines sentences Full transcript lines, each with index, speaker_name, speaker_id, text, start_time and end_time (seconds) transcript_url Grain's share link to the recording summary_overview Grain summary text, when it has one summary_action_items Action items as one newline-separated text recording_source Where the recording came from tags Recording tags teams Team names meeting_type Grain meeting type name thumbnail_url Recording thumbnail meeting_summarized (one row per recording that has a summary): text The summary, shortened to 200 characters summary_overview The full summary text action_item (one row per action item): text The action item text action_item_text The action item text action_item_index Position among the recording's action items action_item_status Status in Grain action_item_assignee Assignee name action_item_offset_ms Time in the recording, in milliseconds parent_meeting_id The Grain recording id highlight (one row per highlight): text The highlight text, or its transcript when it has none highlight_id The Grain highlight id highlight_transcript Transcript of the highlighted span highlight_speakers Speakers in the highlight highlight_offset_ms Start in the recording, in milliseconds highlight_duration_ms Length in milliseconds highlight_tags Highlight tags highlight_url Link to the highlight highlight_thumbnail_url Highlight thumbnail highlight_created_at When the highlight was created parent_meeting_id The Grain recording id Two action items with the same text in one recording become one row. If Grain changes an action item's text, a new row is added and the old one stays. Notes: - `participants` is a list of emails. Whether someone is internal or external is on `attendees[].scope`, and `external_participants` lists the external emails. - `meeting_link` is not set. Grain's `url` is a recording share link, so it is in `transcript_url`. - A `meeting_transcribed` row only appears once the recording has a transcript. - Ids that match Fireflies: `uid` for the three meeting events (`meeting_transcribed:`, `meeting_summarized:`, `action_item::`), plus the column ids shown above for the same data (for example `meeting_id`, `title`, `organizer_email`, `duration_min`, `participants`, `speakers`, `sentences`, `summary_overview`, `action_item_text`). Highlight rows and the `highlight_*` columns exist only on Grain. The `uid` is a unique id per event: `meeting_transcribed:`, `meeting_summarized:`, `action_item::`, and `highlight:`. This is why re-reading a recording never creates duplicate rows. 8. HOW TO CONFIGURE END-TO-END Typical flow for an AI agent building a Grain import source: Step 1: Preview before committing POST /api/v1/sources/import_from_grain/preview Body: { "entities": ["meeting_transcribed", "action_item"], "start_date": "2026-01-01" } Check the returned `data[]` row shape. Iterate the entity selection until you are happy. Preview never creates anything and returns at most 5 sample rows in the app, 100 on the public API. Step 2: Create the source POST /api/v1/sources/import_from_grain Body: + the create-only fields: "name": "", "import_type": "static" | "active", "frequency": "0 12 * * *", // only when import_type=active "expiration_date": "2027-01-01" // optional, active only Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 2b: (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 2) `total_count` grows until the import finishes. Step 3: Sync the source into a workflow (so its records flow downstream) POST /api/v1/sources//sync ( = UUID from Step 2 ) First build `field_mapping`: a. GET /api/v1/workflows and pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs Each input has a `reference` like `{{input.title}}`. c. Map each workflow input (reference WITHOUT braces) to a source field. The source fields are the keys on the preview `data[]` rows. Body: { "workflow_id": "", "field_mapping": { "input.title": "" }, "push_existing": true, "run": "all" } See concepts.txt §10 for the full sync semantics (source-agnostic). The initial import runs asynchronously. The create call returns as soon as the source is created and the import has started, not when records have finished arriving. 9. KEY NOTES - Grain connection is mandatory. The connection slug is `grain`. The user connects it on the Connections page by pasting a Grain API token, either a personal token (sees the meetings that user can see) or a workspace token (Grain admins on Business or Enterprise plans; sees the whole workspace). Floqer checks the token with Grain when it is saved and stores it encrypted. If the API-key user has no active Grain connection, preview and create return 424 ("User is not connected to 'grain'."). Surface this as a "connect Grain first" call to action. - `entities` is required and must contain only the slugs in §5. Selecting several entities imports rows for each. - `import_type` defaults to "static" (one-time). For an ongoing source set it to "active" and supply `frequency`. - Preview returns up to 5 sample rows in the app and up to 100 on the public API. In the app the preview may come back empty (for example only Highlights picked and none exist yet); the user can still create the list. - `start_date` bounds how far back meetings are pulled. With no `start_date`, the import pages back through all history the token can see. - Importing is free. This source uses no credits. - Meetings deleted in Grain later do not remove rows that were already imported. - There are no other filters. To narrow by internal or external attendees, filter on `attendees[].scope` or `external_participants` in the workflow. 10. WHERE IT FITS UPSTREAM (in Grain) Meeting recordings, transcripts, summaries, action items, and highlights live in the user's Grain account. THIS SOURCE Creates a Grain import source. On creation it imports matching records; an active source keeps picking up new data on the `frequency` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported records become available to your Floqer workflows. Wire the source into a workflow to push meeting notes or action items into a CRM, trigger follow-ups, or enrich attendees. 11. WHEN TO USE - One-time pull of meeting transcripts, action items, or highlights for CRM enrichment: `import_type: static`. - Keep new meetings flowing into a Floqer workflow on a schedule (for example, auto-log call notes and follow-up tasks): `import_type: active`, `frequency: "0 12 * * *"`. If the team uses Fireflies instead of Grain, see import_from_fireflies.txt. Last updated: 2026-11-11. Reference: https://floqer.com/docs/reference