# API Reference Overview

The public surface is small and shaped around one verb: ask the SDK a yes/no question about location, get back a `Verdict` with a signed proof.

## The full surface

```mermaid
flowchart TD
    A[Octet.start config] --> B[OctetSdk handle]
    B --> L[OctetSdk.loc]
    B --> S[OctetSdk.licenseStatus]
    L --> P1[isWithin region atTime]
    L --> P2[isOutside region atTime]
    L --> P3[contains center tol atTime]
    P1 --> V[OctetVerdict]
    P2 --> V
    P3 --> V
    V --> R[result YES NO INDETERMINATE]
    V --> RC[reason ReasonCode]
    V --> PR[proof LocationProof?]
    V --> VAL[validity Interval?]
    V --> C[confidence ConfidenceSummary]
```

## Per-symbol reference

| Symbol | What it is |
|---|---|
| [`Octet.start(...)`](/docs/api-reference/octet-start/) | The single bring-up call. Verifies license, activates, returns an `OctetSdk`. |
| [`OctetSdk`](/docs/api-reference/octet-sdk/) | The handle returned by `start`. Exposes `loc` and `licenseStatus`. |
| [Predicates](/docs/api-reference/predicates/) | `isWithin`, `isOutside`, `contains` on `sdk.loc`. |
| [`OctetRegion`](/docs/api-reference/octet-region/) | The shape you query against. Factories: `country`, `subdivision`, `usState`, `city`, `disc`, `ellipse`, `box3D`, `polygonSet`, `earth`. |
| [`OctetVerdict`](/docs/api-reference/octet-verdict/) | The answer. Carries `result`, `reason`, `proof`, `validity`, `confidence`. |
| [License Types](/docs/api-reference/license-types/) | `LicenseStatus`, `LicenseState`, `LicenseError`. |
| [Serialization](/docs/api-reference/serialization/) | `.toStr()`, `.toJson()`, `.toJsonl()` on every public type. |

## Platform asymmetry notes (v1)

| Surface | iOS | Android |
|---|---|---|
| `OctetRegion` factories | All | All |
| `RegionSpec` + `getRegion(spec)` | n/a | [x] |
| `buildRegion { ... }` DSL | n/a | [x] |
| `whatisRegion(r)` / `regionToStr(r)` free functions | (via `.toStr()` extension) | [x] (also `.toStr()`) |

Closing the gap is on the roadmap. iOS callers use the factories directly and `region.toStr()` for the human-readable form.

## Conventions used throughout

- **Code samples are shown in tabs**, Swift on the left, Kotlin on the right. Pick your platform once. The choice is remembered across the site.
- **Async**. `Octet.start` is `async throws` (Swift) / `suspend` (Kotlin). The predicates (`isWithin`, etc.) are `async` and do *not* throw. License or runtime problems become `INDETERMINATE` reasons on the verdict.
- **Validation is eager.** Region factories trap on malformed inputs at construction. The predicate API never sees an invalid region.
- **Time is `Date` on iOS, `java.time.Instant` on Android.** Both default to "now".
- **`Meters` is a `Double` typealias** on both platforms (a plain `Double`, not a wrapper type).
- **`LatLon(latitude:, longitude:)`** is the coordinate type. WGS84, pre-validated.

## Where to start

If you're integrating for the first time, go to the [iOS Quick Start](/docs/getting-started/ios-quickstart/) or [Android Quick Start](/docs/getting-started/android-quickstart/). They exercise every symbol on this page end-to-end.