---
title: "Early access and flags"
url: /definition/flags
---

# Early access and flags

> Turn a new feature, a Verb, a field or a plan, on for named Customer orgs or an early-access list, and leave it absent for everyone else.

A flag turns Verbs, fields or plans on for an early-access list or named Customer orgs; everyone else meets a product without them.

```mermaid title="A flag, from a few orgs to everyone"
stateDiagram-v2
  [*] --> listed: a deploy with flags
  listed --> widened: more orgs
  widened --> shipped: flag removed
  listed --> withdrawn: turned off
  widened --> withdrawn: turned off
```

## Outside a flag, and inside it
A Customer outside a flag meets the product as if the flagged parts were never written.

The Verb is absent from its OpenAPI document, its MCP tools, its SDK types and its docs. A call to it answers 404 [`no_route`](/reference.md#no_route), and a flagged field is absent from every reply.

A Customer inside sees each flagged Verb with `"early": true` in its tool list and a line on its docs page. Its agent reads the same mark.

## A flag, a rollout or a variant
Three tools put a change in front of some Customers first: a flag, a [rollout](/definition/rollout.md) and a [variant](/commerce/experiments.md). Each answers a different question.

| | A flag | A rollout | A variant |
| --- | --- | --- | --- |
| Who gets it | Orgs you name, or an early-access list | A random share of orgs, growing in steps | A random share of new Customers |
| What changes | Chosen Verbs, fields or plans | The whole [Version](/reference/platform.md#version) | A price, a plan or a trial |
| How long | Until you ship it to everyone or withdraw it | Hours, until every org is on it | Until the experiment concludes |
| Who decides | You, org by org | The rollout guards | The analysis, then you |

## A search for early orgs
The lookup by domain tries a search by sector on 50 orgs that ask for it, before anyone else can call it.

```ts title="definition.ts"
import { define, secret } from 'apis.dev'

/** Any company by its domain, with its headcount and sector, and search by sector for early orgs. */
export default define({
  name: 'companyfacts', domain: 'companyfacts.apis.dev',
  sources: {
    firms: { origin: 'https://firms.example.com', key: secret('FIRMS_KEY') },
  },
  Company: {
    domain:    { type: 'url!#',   from: 'firms', map: 'website' },
    employees: { type: 'number?', from: 'firms', map: 'headcount' },
    sector:    { type: 'string?', from: 'firms', map: 'industry' },
  },
  offer: {
    'Company.get': 0.002, 'Company.search': 0.005,
    free: { 'Company.get': 100 },
  },
  flags: { sectorSearch: { verbs: ['Company.search'], to: 'pilot' } },
  early: { pilot: { join: 'request', cap: 50, ask: ['useCase'] } },
})
```

A member's agent asks to join, and the request waits for your approval.

```http title="Response"
HTTP/1.1 202 Accepted
Content-Type: application/json
X-Cost: price=0, currency="USD"
X-Request-Id: req_a0c4e83f61d2b97e5c13

{
  "list": "pilot",
  "org": "org_acme",
  "state": "requested",
  "place": 12,
  "answers": { "useCase": "Find every fintech with over 200 people" }
}
```

Once granted, `Company.search` appears in that org's tools at its next call, priced as the Offer prices it. Removing the flag ships it to everyone in one deploy.

## Asking to join
An [early-access list](/definition/flags.md#lists) holds the orgs that asked or were invited, up to `cap`.

| `join` | How a Customer gets on |
| --- | --- |
| `request` | Asks in the portal, or with `requestEarlyAccess` over MCP, answering the fields in `ask`; you approve with `EarlyAccess.approve` |
| `invite` | You add the org with `Flag.grant`; it is told in the portal and by email |

A request is `requested`, then `granted` or `declined`. A Customer leaves a list at any time, and loses only the flagged parts, never its records.