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

# Build with the Bily API

> Connect trusted services to scoped Bily stores, analytics, integrations, and supported actions.

The Bily API gives trusted services a stable, versioned way to work with Bily. Every endpoint requires authentication, and every store request stays within the caller's organization access.

With the API, you can:

* Discover the organizations and stores available to a key.
* Query advertising, attribution, product, customer, and cohort analytics.
* Inspect store readiness, connected accounts, assets, and tracking connections.
* Run read-only store commerce queries.
* Synchronize supported connections and perform explicit platform actions.

## Base URL

Start every stable customer endpoint with this base URL:

```text theme={null}
https://app.bily.ai/api/customer/v1
```

Keep the `/v1` segment. It is part of the API contract.

## Discover access first

If you do not know the organization and store, start with one request:

1. Call `GET /context` to get the authenticated user, accessible organizations, and each organization's nested stores.
2. Copy an exact `organizations[].stores[].url` value into store-scoped endpoints.
3. Add the optional `organizationId` query only when the identity can access multiple organizations and the workload deliberately selects one. Omit it for a store-scoped API key.

Use `GET /me`, `GET /organizations`, or `GET /stores` when your workload needs only one part of the discovery response.

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/rest-api/authentication">
    Create, store, send, and revoke an API key safely.
  </Card>

  <Card title="Scoping" icon="building" href="/rest-api/scoping">
    Understand organization and store access boundaries.
  </Card>

  <Card title="API quickstart" icon="rocket" href="/rest-api/quickstart">
    Make a request and list your first store.
  </Card>

  <Card title="Errors and request IDs" icon="triangle-exclamation" href="/rest-api/errors">
    Handle failures and preserve diagnostic context.
  </Card>
</CardGroup>

## Read every response consistently

Successful responses use JSON. Resource collections use a named object when the contract needs context, such as `{ "stores": [...] }`. Analytics rows can use an array.

Every response includes an `x-request-id` header. Keep it in your logs and include it in support requests.

<Info>
  Bily generates the endpoint reference from its OpenAPI specification. Use that specification as the source of truth for paths, parameters, request bodies, and stable response fields.
</Info>

<Card title="Choose the API or MCP" icon="arrows-split-up-and-left" href="/guides/api-mcp-selection">
  Compare deterministic server workflows with interactive AI-client work.
</Card>