A briefing is structured preparation for a company meeting. Generation is asynchronous: create a pending briefing, then read its status until Floral returns completed content or a failure state.
Prerequisites
You need meetings:read to list and retrieve briefings. Generating one requires both meetings:write and contacts:read, because the request refers to an existing active company in the same workspace.
Set these values once in your shell before running the examples:
Use a personal access token created for this workspace. The examples use synthetic IDs and values; replace them with values returned by your workspace.
Keep FLORAL_TOKEN in a secret manager outside local development. Never commit it to source control or include it in logs.
List and filter briefings
Briefing collections use opaque cursor pagination and support company, status, and creation-time filters.
The supported states are PENDING, IN_PROGRESS, COMPLETE, and FAILED. Pass a non-null nextCursor as cursor for the next page.
Generate a briefing
Use a unique idempotency key and an active company ID. additionalContext is optional and can contain up to 10,000 characters of bounded context for this briefing.
A successful request returns 202, a Location, and a briefing with PENDING or IN_PROGRESS status. Save its id and ETag.
Poll for completion
Retrieve the briefing at a measured interval. The detail response includes structured content after the status becomes COMPLETE.
Use exponential backoff between reads and stop when the status is COMPLETE or FAILED. The detail response’s ETag is an opaque version for cache and change detection.
Retry an interrupted create
If the connection closes before you receive the create response, retry the identical path and body with the same key:
Floral replays the original accepted result instead of starting another generation. Changing the company or context while reusing the key returns 409 IDEMPOTENCY_CONFLICT.
Floral protects writes with two opaque values:
- Send a unique
Idempotency-Key when an operation requires one. Retrying the identical request with the same key replays its result for 24 hours. Within that operation, reusing the key with different canonical input returns 409 IDEMPOTENCY_CONFLICT.
- Send the latest strong
ETag as If-Match when an operation changes an existing resource. A stale value returns 412 VERSION_CONFLICT; a missing value returns 428 PRECONDITION_REQUIRED.
Keep the quote characters around an ETag, and replace your saved value after every successful write. See Reliability and retries for the complete retry rules. 