import { CardGrid, LinkCard, TabItem, Tabs } from '@astrojs/starlight/components';
import Faq from '@components/Faq.astro';

The **public API** (`/public/v1`) is a curated REST surface of 5 resources — leads, contacts, conversations,
appointments and tickets — authenticated with an API key, available on the **Pro** and **Enterprise** plans.

<CardGrid>
  <LinkCard title="Get started with the API" href="/en/api/getting-started/" description="Create your key and make your first call in under 10 minutes." />
  <LinkCard title="Authentication" href="/en/api/authentication/" description="The X-API-Key header, scopes per resource and per action." />
</CardGrid>

## Your first request

`GET /me` doesn't require any scope of its own — just a valid key from a tenant on an eligible plan — so
it's the fastest way to check your key works:

<Tabs>
  <TabItem label="curl">
    ```bash
    curl https://api.aymaragents.com/public/v1/me \
      -H "X-API-Key: aa_YOUR_FULL_KEY"
    ```
  </TabItem>
  <TabItem label="Python">
    ```python
    import requests

    res = requests.get(
        "https://api.aymaragents.com/public/v1/me",
        headers={"X-API-Key": "aa_YOUR_FULL_KEY"},
    )
    res.raise_for_status()
    print(res.json())
    ```
  </TabItem>
  <TabItem label="JavaScript">
    ```javascript
    const res = await fetch("https://api.aymaragents.com/public/v1/me", {
      headers: { "X-API-Key": "aa_YOUR_FULL_KEY" },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    console.log(await res.json());
    ```
  </TabItem>
</Tabs>

## Guides

<CardGrid>
  <LinkCard title="Plans and limits" href="/en/api/plans-and-limits/" description="Which plan you need and how many requests you can make." />
  <LinkCard title="Errors" href="/en/api/errors/" description="Error format and codes the API can return." />
  <LinkCard title="Versioning" href="/en/api/versioning/" description="How /public/v1 evolves without breaking your integration." />
  <LinkCard title="API use cases" href="/en/api/use-cases/" description="Real integration scenarios." />
</CardGrid>

## Generated reference

<LinkCard title="Endpoints" href="/api/reference/" description="Every /public/v1 operation, generated from the same OpenAPI definition the MCP server uses." />

## Related tools

<CardGrid>
  <LinkCard title="MCP server" href="/en/mcp/" description="Connect your AI assistant to the same API." />
  <LinkCard title="llms.txt" href="/llms.txt" description="An index of the whole portal in plain text." />
</CardGrid>

## Frequently asked questions

<Faq items={[
  { question: 'What plan do I need to use the public API?', answer: 'Pro or Enterprise. On the Starter plan, any call to <code>/public/v1/*</code> returns <code>403 PLAN_NOT_ELIGIBLE</code>, even if the key exists and has the right scope. See <a href="/en/api/plans-and-limits/">Plans and limits</a>.' },
  { question: "What happens if my key doesn't have the exact scope an endpoint requires?", answer: 'You get <code>403 PERMISSION_DENIED</code>, even with the rest of its permissions intact. Every resource has two independent scopes — read and manage. See <a href="/en/api/authentication/">Authentication</a>.' },
  { question: 'How do I rotate a key without breaking my integration?', answer: "There's no atomic rotation endpoint today: create a new key with the same scopes, update the secret in your integration, then revoke the old one — there's a brief window with both active." },
  { question: "What does the API return if I ask for another tenant's resource?", answer: "<code>404</code>, exactly as if the resource didn't exist — never <code>403</code>, which would confirm the data exists on another account." },
  { question: 'How many requests can I make per minute?', answer: '180/minute and 50,000/day on Pro; 600/minute and 200,000/day on Enterprise. The quota is counted per key, not per IP. See <a href="/en/api/plans-and-limits/">Plans and limits</a>.' },
  { question: 'Can I delete a lead, a contact, or any other resource through the API?', answer: 'No — <code>/public/v1</code> has no <code>DELETE</code> endpoint at all. See <a href="/en/api/use-cases/">API use cases</a>.' },
  { question: 'What happens if I send a WhatsApp message outside the 24-hour window?', answer: 'You get <code>409 WHATSAPP_SESSION_WINDOW_CLOSED</code> — use <code>POST /conversations/start</code> with an approved template instead. See <a href="/en/api/errors/">Errors</a>.' },
]} />

## Up next

<LinkCard title="MCP server" href="/en/mcp/" description="Connect Claude, Cursor or another AI assistant to your account." />