> ## Documentation Index > Fetch the complete documentation index at: https://docs.formo.so/llms.txt > Use this file to discover all available pages before exploring further. # Create Segment > Create a new audience segment by defining filter rules based on wallet properties, onchain behavior, and user demographics via the Formo API. ## OpenAPI ````yaml POST /v0/segments openapi: 3.1.0 info: title: Formo Public API description: >- REST API for managing Formo projects, analytics, alerts, boards, charts, contracts, segments, and AI chat. **Auth.** All endpoints require a workspace API key with the appropriate scopes (see `x-api-scopes`). **Response shape.** Successful responses return the resource directly (or `{ data: [...], total, page, size, has_more }` for paginated lists). HTTP status carries success/failure; there is no envelope wrapping success bodies. **Errors.** Every non-2xx response uses the `Error` envelope: `{ error: { code, message, doc_url, param?, details? } }`. Branch on the machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the matching section of the [errors reference](https://docs.formo.so/api/errors). **Idempotency.** Pass an `Idempotency-Key` header on POST/PUT/PATCH/DELETE to make retries safe; the response is cached for 24 h and replayed on duplicate keys. version: 0.1.0 contact: name: Formo url: https://formo.so servers: - url: https://api.formo.so description: API Server (boards, alerts, contracts, segments, profiles, query, import) - url: https://events.formo.so description: Events Server (event ingestion) security: - WorkspaceApiKey: [] tags: - name: Alerts description: Manage project alerts and notifications - name: Boards description: Manage dashboard boards - name: Charts description: Manage charts within boards - name: Contracts description: Manage blockchain contract monitoring - name: Segments description: Manage user segments - name: Profiles description: Wallet profiles and import - name: Query description: >- Execute SQL queries and call pre-built analytics endpoints (KPIs, top pages, lifecycle, retention, revenue). Requires the query:read scope. - name: Events description: Event ingestion API (events.formo.so) paths: /v0/segments: post: tags: - Segments summary: Create segment operationId: createSegment requestBody: required: true content: application/json: schema: type: object properties: title: type: string minLength: 1 filterSets: type: array items: type: string minItems: 1 required: - title - filterSets examples: highValueMobileUsers: summary: High-value mobile users from paid campaigns value: title: High-value mobile users filterSets: - device::equals::mobile - net_worth_usd::greaterOrEqual::10000 - utm_source::equals::paid_ads multiDeviceChromeSafari: summary: Chrome or Safari users (multi-value filter) value: title: Chrome/Safari users filterSets: - browser::in::Chrome|Safari excludeUSUsers: summary: All users except from the US value: title: Non-US users filterSets: - location::notEquals::US powerUsers: summary: Power users with high net worth from organic traffic value: title: Organic power users filterSets: - net_worth_usd::greater::1000 - utm_source::notIn::google_ads|facebook_ads - lifecycle::equals::power multiChainWhaleUsers: summary: Users active on 3+ chains with high net worth value: title: Multi-chain whales filterSets: - chains::greaterOrEqual::3 - net_worth_usd::greater::100000 - apps::greater::5 behavioralFilterSimple: summary: >- Users who performed 'signature' event at least once in last 30 days description: >- Behavioural filters use the 'events' filter key with a base64-encoded JSON array as the value. The JSON contains event name, frequency operator (greater/greaterOrEqual/equals/lessOrEqual/less), times count, and date range. value: title: Recent signers filterSets: - >- events::equals::W3siZXZlbnQiOiAic2lnbmF0dXJlIiwgIm9wZXJhdG9yIjogImdyZWF0ZXJPckVxdWFsIiwgInRpbWVzIjogMSwgInByZXNldCI6ICJsYXN0XzMwZCIsICJkYXRlX2Zyb20iOiAiMjAyNS0wOS0xOSIsICJkYXRlX3RvIjogIjIwMjUtMTAtMTkifV0= behavioralFilterWithProperties: summary: >- Users who connected via MetaMask on Ethereum mainnet + from India description: >- Combines a behavioural filter (type=connect event with property filters) and a demographic filter (location). The 'event' field uses the event type key (e.g. 'connect', 'signature', 'transaction', 'page'), not the display label. Event property filters use {op, value} objects as additional keys. value: title: Indian MetaMask users filterSets: - >- events::equals::W3siZXZlbnQiOiAiY29ubmVjdCIsICJvcGVyYXRvciI6ICJncmVhdGVyT3JFcXVhbCIsICJ0aW1lcyI6IDEsICJwcmVzZXQiOiAibGFzdF8zMGQiLCAiZGF0ZV9mcm9tIjogIjIwMjUtMDktMTkiLCAiZGF0ZV90byI6ICIyMDI1LTEwLTE5IiwgInJkbnMiOiB7Im9wIjogImVxdWFscyIsICJ2YWx1ZSI6ICJpby5tZXRhbWFzayJ9LCAiY2hhaW5faWQiOiB7Im9wIjogImVxdWFscyIsICJ2YWx1ZSI6ICIxIn19XQ== - location::equals::IN behavioralFilterMultipleEvents: summary: >- Users with 5+ page views last week AND at least 1 transaction last month description: >- Multiple behavioural events in a single filter. All conditions in the array must be met (AND logic). Valid event types: page, connect, disconnect, chain, signature, transaction, track, decoded_log, detect, identify. value: title: Active transactors filterSets: - >- events::equals::W3siZXZlbnQiOiAicGFnZSIsICJvcGVyYXRvciI6ICJncmVhdGVyT3JFcXVhbCIsICJ0aW1lcyI6IDUsICJwcmVzZXQiOiAibGFzdF83ZCIsICJkYXRlX2Zyb20iOiAiMjAyNS0xMC0xMiIsICJkYXRlX3RvIjogIjIwMjUtMTAtMTkifSwgeyJldmVudCI6ICJ0cmFuc2FjdGlvbiIsICJvcGVyYXRvciI6ICJncmVhdGVyT3JFcXVhbCIsICJ0aW1lcyI6IDEsICJwcmVzZXQiOiAibGFzdF8zMGQiLCAiZGF0ZV9mcm9tIjogIjIwMjUtMDktMTkiLCAiZGF0ZV90byI6ICIyMDI1LTEwLTE5In1d - device::equals::desktop responses: '200': description: Segment created content: application/json: schema: $ref: '#/components/schemas/Segment' components: schemas: Segment: type: object properties: id: type: string title: type: string projectId: type: string filterSet: type: array items: type: string required: - id - title securitySchemes: WorkspaceApiKey: type: http scheme: bearer description: >- Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard under Team Settings > API Keys. ````