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

# Make your first API request

> Confirm your Bily API key and discover its user, organization, and store in one request.

This quickstart uses a server-side API key. Create and protect one with the [authentication guide](/rest-api/authentication).

<Steps>
  <Step title="Protect the key in your shell">
    Keep the value out of shell history. Use a local secret manager or a temporary protected environment variable when possible.

    ```bash theme={null}
    export BILY_API_KEY="<your-key>"
    ```
  </Step>

  <Step title="Confirm your access">
    ```bash theme={null}
    curl --fail-with-body \
      --url https://app.bily.ai/api/customer/v1/context \
      --header "x-api-key: $BILY_API_KEY"
    ```

    The response groups every visible store under its organization:

    ```json theme={null}
    {
      "user": {
        "id": "usr_01J8W6T2QF4M7Z9A3K5N1P0R8S",
        "email": "developer@example.com",
        "emailVerified": true,
        "name": "Bily Developer",
        "image": null
      },
      "organizations": [
        {
          "id": "org_01J8W7T9G3E6ZQ4M2K5N8P1R0S",
          "name": "Example organization",
          "slug": "example-organization",
          "createdAt": "2026-07-01T00:00:00.000Z",
          "stores": [
            {
              "id": "store_01J8W8D5GSPN3XQYF4K2A6M7RT",
              "url": "store.example.com",
              "type": "shopify",
              "currency": "USD",
              "createdAt": "2026-07-01T00:00:00.000Z",
              "updatedAt": "2026-07-14T00:00:00.000Z"
            }
          ]
        }
      ]
    }
    ```

    A standard settings-generated key is already store-scoped. Do not add an organization parameter.

    Copy the exact `organizations[].stores[].url` value into store-scoped endpoints.
  </Step>

  <Step title="Read the store profile">
    ```bash theme={null}
    curl --fail-with-body \
      --url https://app.bily.ai/api/customer/v1/store-data/store.example.com \
      --header "x-api-key: $BILY_API_KEY"
    ```
  </Step>
</Steps>

<Warning>
  If an older key from **Settings > MCP** returns `403` and requires store scope, select the intended store and create a replacement scoped key.
</Warning>

## Choose an organization when required

Use `organizationId` only when the authenticated identity can access multiple organizations and the workload deliberately selects one:

```bash theme={null}
curl --fail-with-body --get \
  --url https://app.bily.ai/api/customer/v1/context \
  --header "x-api-key: $BILY_API_KEY" \
  --data-urlencode "organizationId=org_01J8W7T9G3E6ZQ4M2K5N8P1R0S"
```

The organization must remain inside the credential's allowed scope. Omit this parameter for store-scoped keys.

## Reuse a safe JavaScript client

```typescript bily-api.ts theme={null}
const apiKey = process.env.BILY_API_KEY;

if (!apiKey) {
  throw new Error("BILY_API_KEY is required");
}

async function bilyRequest<T>(path: string, init: RequestInit = {}): Promise<T> {
  const response = await fetch(`https://app.bily.ai/api/customer/v1${path}`, {
    ...init,
    headers: {
      accept: "application/json",
      "x-api-key": apiKey,
      ...init.headers,
    },
  });

  if (!response.ok) {
    const requestId = response.headers.get("x-request-id");
    const detail = await response.text();
    throw new Error(`Bily request failed (${response.status}, request ${requestId}): ${detail}`);
  }

  return response.json() as Promise<T>;
}

const context = await bilyRequest<{
  user: { id: string; email: string; name: string };
  organizations: Array<{
    id: string;
    name: string;
    stores: Array<{ id: string; url: string }>;
  }>;
}>("/context");

const store = context.organizations[0]?.stores[0];
if (!store) {
  throw new Error("No accessible Bily store found");
}

const profile = await bilyRequest<Record<string, unknown>>(
  `/store-data/${encodeURIComponent(store.url)}`,
);

console.log({ user: context.user, store, profile });
```

<Card title="Browse all endpoints" icon="list" href="/rest-api/overview">
  Open the generated endpoint reference, including `GET /context`, in the **Bily API** tab.
</Card>