> ## Documentation Index
> Fetch the complete documentation index at: https://docs.floral.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate and read briefings

> List, filter, generate, and retrieve meeting briefings through Floral's public API.

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:

```bash theme={null}
export FLORAL_BASE_URL="https://app.floral.so/api/v1"
export FLORAL_WORKSPACE="your-workspace"
export FLORAL_TOKEN="floral_pat_..."
```

Use a personal access token created for this workspace. The examples use synthetic IDs and values; replace them with values returned by your workspace.

<Warning>
  Keep `FLORAL_TOKEN` in a secret manager outside local development. Never commit it to source control or include it in logs.
</Warning>

## List and filter briefings

Briefing collections use opaque cursor pagination and support company, status, and creation-time filters.

```bash theme={null}
curl --get --fail-with-body \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/briefings" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --data-urlencode "companyId=1842" \
  --data-urlencode "status=COMPLETE" \
  --data-urlencode "createdAfter=2026-08-01T00:00:00.000Z" \
  --data-urlencode "createdBefore=2026-08-31T23:59:59.000Z" \
  --data-urlencode "limit=20"
```

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.

```bash theme={null}
export BRIEFING_CREATE_KEY="01J5C5F1R8N3M7K2Q0D6T4V9WX"

curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/briefings" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $BRIEFING_CREATE_KEY" \
  --data '{
    "companyId": 1842,
    "additionalContext": "Focus on the expansion into Sweden and the new operations team."
  }'
```

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`.

```bash theme={null}
curl --request GET --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/briefings/512" \
  --header "Authorization: Bearer $FLORAL_TOKEN"
```

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:

```bash theme={null}
curl --request POST --fail-with-body --include \
  --url "$FLORAL_BASE_URL/workspaces/$FLORAL_WORKSPACE/briefings" \
  --header "Authorization: Bearer $FLORAL_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $BRIEFING_CREATE_KEY" \
  --data '{
    "companyId": 1842,
    "additionalContext": "Focus on the expansion into Sweden and the new operations team."
  }'
```

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](/developers/api/reliability) for the complete retry rules.