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

# API overview

> Understand Floral's public API base URL, resources, versioning, and limits.

The Floral Public API is a JSON HTTP API served from:

```text theme={null}
https://app.floral.so/api/v1
```

The `v1` prefix identifies the current public contract. Every operation also has a stable `operationId` in the OpenAPI document for generated clients and integration telemetry.

## Versioning and deprecation

Changes within `v1` remain backward compatible. Floral can add optional response fields, operations, and non-breaking capabilities without changing the URL version. Clients should ignore response fields they do not use.

A breaking request or response change requires a new API version. When an operation is deprecated, Floral marks it in the published contract and provides a replacement and retirement timeline. A deprecated operation remains documented until that timeline ends; it is not removed silently from `v1`.

## Request lifecycle

Every request to a public endpoint must:

1. use HTTPS;
2. send a valid bearer token;
3. address the workspace slug pinned to that token;
4. satisfy the scopes listed on the operation.

The required scopes appear on every operation in the API reference.

## Available operations

* Companies: list, retrieve, create, partially update, archive, and restore company profiles.
* People: list, retrieve, create, partially update, archive, and restore person profiles and company links.
* Discovery: search companies and people, query the Danish company registry, and list public custom-field definitions.
* Briefings: list, retrieve, and generate structured company briefings.
* Summaries: list, retrieve, replace summary notes, and approve eligible summaries.

The API reference is generated from the public operation registry. Each operation documents its exact method, path, request and response schemas, required scopes, headers, filters, errors, and reliability profile.

## Pagination and filters

Company, person, custom-field-definition, briefing, and summary collections use opaque cursor pagination. Set `limit` from 1 to 50; the default is 20. When `nextCursor` is non-null, pass it unchanged as the next request's `cursor`. A null value means the collection is exhausted.

Collection filters are operation-specific:

* companies: `status`, `lifecycleStage`, and `sort`;
* people: `status`, `lifecycleStage`, `sort`, and `companyId`;
* custom-field definitions: required `entityType`;
* briefings: `status`, `companyId`, `createdAfter`, and `createdBefore`;
* summaries: `status`, `companyId`, `appointmentAfter`, `appointmentBefore`, and `evidenceAudience`.

Relationship search uses `q` and a limit of at most 20. Registry search uses an exact CVR or a company name. Date ranges are inclusive and must use ISO 8601 timestamps with the start no later than the end.

## Response headers

Every response includes `X-Request-ID` and `X-Content-Type-Options`. Responses evaluated against an operation's rate limit also include `X-RateLimit-Limit` and `X-RateLimit-Remaining`. Detail reads and successful writes for mutable resources can include `ETag`; creates can also include a canonical `Location`.

Read [Reliability and retries](/api/reliability) before implementing rate-limit handling, idempotent retries, or optimistic concurrency.