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

# API reference

> REST API at api.gavai.app/v1 — token-based auth, JSON in / JSON out, idempotent writes.

export const ExpectedOutput = ({caption = "Expected output", children}) => <div className="gv-output">
    <div className="gv-output__label">
      <svg className="gv-output__icon" viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <polyline points="15 10 20 15 15 20" />
        <path d="M4 4v7a4 4 0 0 0 4 4h12" />
      </svg>
      <span>{caption}</span>
    </div>
    <div className="gv-output__body">{children}</div>
  </div>;

export const APIBadge = ({method = "GET", path, scope}) => {
  const m = method.toUpperCase();
  return <span className="gv-api-badge">
      <span className={`gv-api-badge__method gv-api-badge__method--${m.toLowerCase()}`}>
        {m}
      </span>
      <code className="gv-api-badge__path">{path}</code>
      {scope && <span className="gv-api-badge__scope">
          <span className="gv-api-badge__scope-label">scope</span>
          <code>{scope}</code>
        </span>}
    </span>;
};

export const BrandCard = ({eyebrow, title, href, icon, badge, cta, featured = false, horizontal = false, children}) => {
  const classes = ["gv-card", featured && "gv-card--featured", horizontal && "gv-card--horizontal"].filter(Boolean).join(" ");
  const inner = <>
      {icon && <span className="gv-card__icon" aria-hidden="true">
          <Icon icon={icon} />
        </span>}
      <div className="gv-card__main">
        {(eyebrow || badge) && <div className="gv-card__meta">
            {eyebrow && <Eyebrow label={eyebrow} tone="muted" />}
            {badge && <span className="gv-card__badge">{badge}</span>}
          </div>}
        <h3 className="gv-card__title">{title}</h3>
        {children && <div className="gv-card__body">{children}</div>}
        {cta && <span className="gv-card__cta">
            {cta}
            <svg className="gv-card__cta-arrow" viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
              <line x1="7" y1="17" x2="17" y2="7" />
              <polyline points="7 7 17 7 17 17" />
            </svg>
          </span>}
      </div>
    </>;
  return href ? <a className={classes} href={href}>
      {inner}
    </a> : <div className={classes}>{inner}</div>;
};

export const Eyebrow = ({label, tone = "default"}) => <div className={`gv-eyebrow gv-eyebrow--${tone}`}>
    <span className="gv-eyebrow__bar" aria-hidden="true" />
    <span className="gv-eyebrow__label">{label}</span>
  </div>;

<Eyebrow label="API REFERENCE" />

Every operation in gavAI is reachable over HTTPS at `https://api.gavai.app/v1`. The CLI, SDKs, and MCP servers all wrap this API — they add no capability of their own. Anything they can do, you can do with a plain `curl`. By the end of this section you will know how the API authenticates, what its errors look like, how writes stay idempotent across retries, how to walk paginated lists, and where to find every resource.

## A first request

<APIBadge method="GET" path="/v1/me" scope="me:read" />

```bash theme={null}
curl https://api.gavai.app/v1/me \
  -H "Authorization: Bearer gak_test_xxxxxxxxxxxxx"
```

<ExpectedOutput>
  ```json theme={null}
  {
    "user":  { "id": "usr_01H...", "email": "you@example.com" },
    "token": { "id": "tok_01H...", "scopes": ["me:read"], "mode": "test" },
    "workspace": { "slug": "acme" }
  }
  ```
</ExpectedOutput>

That call is the smallest legal request the API accepts. The bearer token authenticates you, the JSON body identifies the principal behind that token, and the workspace tells you which tenant the token resolves to. Every other endpoint follows the same shape.

## The contract in one table

| What                      | Value                                                                             |
| ------------------------- | --------------------------------------------------------------------------------- |
| Base URL                  | `https://api.gavai.app/v1`                                                        |
| Request and response body | `application/json`                                                                |
| Authentication            | `Authorization: Bearer <token>` on every request                                  |
| Token types               | Workspace API keys (`gak_live_*`, `gak_test_*`) or OAuth session tokens (`gst_*`) |
| Error envelope            | `{ "error": { "code": string, "message": string, "details"?: object } }`          |
| Idempotency window        | 24 hours, keyed by `Idempotency-Key` header                                       |
| Pagination                | Cursor-based, `next_cursor` on list responses                                     |
| Rate limits               | Per-token, surfaced via `X-RateLimit-*` headers                                   |

Every overview page in this section unpacks one row of that table.

## Read these first

<Columns cols={2}>
  <BrandCard eyebrow="OVERVIEW" title="Authentication" href="/api-reference/authentication">
    Bearer tokens, the two token types, scopes, and the OAuth 2.1 + PKCE flow.
  </BrandCard>

  <BrandCard eyebrow="OVERVIEW" title="Errors" href="/api-reference/errors">
    Status codes, the error envelope, validation field errors, and what is safe to retry.
  </BrandCard>

  <BrandCard eyebrow="OVERVIEW" title="Idempotency" href="/api-reference/idempotency">
    The `Idempotency-Key` header, the 24-hour cache window, and `Idempotent-Replayed`.
  </BrandCard>

  <BrandCard eyebrow="OVERVIEW" title="Pagination" href="/api-reference/pagination">
    Cursor-based listing, the `next_cursor` field, and the absent-cursor termination rule.
  </BrandCard>

  <BrandCard eyebrow="OVERVIEW" title="Rate limits" href="/api-reference/rate-limits">
    Per-token limits, the `X-RateLimit-*` headers, and the `Retry-After` contract.
  </BrandCard>
</Columns>

## Resources

<Columns cols={2}>
  <BrandCard eyebrow="RESOURCE" title="Me & identity" href="/api-reference/resources/me">
    The current principal — user, token, scopes, and active workspace.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="OAuth" href="/api-reference/resources/oauth">
    PKCE code exchange and refresh-token rotation for interactive callers.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Workspaces" href="/api-reference/resources/workspaces">
    Enumerate the workspaces a token can reach and switch the active context.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Tokens" href="/api-reference/resources/tokens">
    Mint, inspect, rotate, and revoke workspace API keys.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Pages" href="/api-reference/resources/pages">
    Read, patch (RFC 6902), publish, and roll back page documents.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Theme" href="/api-reference/resources/theme">
    Color tokens, typography, and spacing that apply across every page.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Forms" href="/api-reference/resources/forms">
    Read form definitions and walk paginated submission records.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Agents" href="/api-reference/resources/agents">
    Workspace automations — create, activate, deactivate, and inspect runs.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Secrets" href="/api-reference/resources/secrets">
    Write-only encrypted store for third-party API keys and signing secrets.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Domains" href="/api-reference/resources/domains">
    Attach custom hostnames and complete DNS verification.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Logs" href="/api-reference/resources/logs">
    List, search, and tail workspace runtime logs.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Deployments" href="/api-reference/resources/deployments">
    Inspect deployment status, cancel in-flight builds, and promote to live.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Billing" href="/api-reference/resources/billing">
    The plan gavAI charges you against — usage, invoices, payment method.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Monetization" href="/api-reference/resources/monetization">
    Stripe Connect onboarding so your workspace can charge its end users.
  </BrandCard>

  <BrandCard eyebrow="RESOURCE" title="Approvals" href="/api-reference/resources/approvals">
    Human-in-the-loop queue for actions an agent paused to confirm.
  </BrandCard>
</Columns>

## Next

<Card title="Authentication" icon="key" href="/api-reference/authentication">
  Pick a token type, mint a key, and make your first authenticated call.
</Card>