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

# gavai public-api

> Make an authenticated request to the gavAI public API from the command line.

export const ErrorTable = ({errors}) => <div className="gv-error-table" role="table" aria-label="Errors and fixes">
    <div className="gv-error-table__head" role="row">
      <span className="gv-error-table__col-head" role="columnheader">Error</span>
      <span className="gv-error-table__col-head" role="columnheader">Cause</span>
      <span className="gv-error-table__col-head" role="columnheader">Fix</span>
    </div>
    {errors.map((err, i) => <div className="gv-error-table__row" role="row" key={i}>
        <code className="gv-error-table__code" role="cell">{err.code}</code>
        <div className="gv-error-table__cause" role="cell">{err.cause}</div>
        <div className="gv-error-table__fix" role="cell">{err.fix}</div>
      </div>)}
  </div>;

export const Def = ({term, type, defaultValue, required, children}) => <>
    <dt className="gv-def-list__term">
      <span className="gv-def-list__name">{term}</span>
      {type && <span className="gv-def-list__type">{type}</span>}
      {required && <span className="gv-def-list__required">required</span>}
      {defaultValue !== undefined && <span className="gv-def-list__default">
          default <code>{defaultValue}</code>
        </span>}
    </dt>
    <dd className="gv-def-list__description">{children}</dd>
  </>;

export const DefList = ({children}) => <dl className="gv-def-list">{children}</dl>;

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="CLI" />

Make an authenticated request to `api.gavai.app` using the stored credentials, and print the JSON response to stdout. This page covers the synopsis, the arguments, and where to draw the line between an ad-hoc CLI call and a script written against the SDK.

## Synopsis

```bash theme={null}
gavai public-api <method> <path> [--body <json>]
```

## Arguments

<DefList>
  <Def term="<method>" type="string" required>
    HTTP method or shorthand resource name. The CLI accepts standard verbs (`GET`, `POST`, `PATCH`, `DELETE`) and resource shortcuts (`me`, `workspaces`) for common reads.
  </Def>

  <Def term="<path>" type="string">
    Path under `/v1`. Required when sending a verb. Omit when using a shortcut.
  </Def>
</DefList>

## Flags

<DefList>
  <Def term="--body" type="json">
    Inline JSON body for `POST` / `PATCH` requests.
  </Def>
</DefList>

<Note>
  Run `gavai public-api --help` for the authoritative flag list, including the exact shape of `--body` and any `--header` / `--query` flags in your CLI version.
</Note>

## Behavior

The command signs the request with the access token from `~/.config/gavai/credentials.json` and sends it to `https://api.gavai.app`. The response body is printed to stdout as JSON; HTTP errors map to the standard CLI exit codes below.

This is appropriate for inspecting a workspace, checking a single resource, or testing an endpoint before wiring it into a script. For multi-step workflows, retries, pagination, or any logic beyond a single request, reach for the [TypeScript SDK](/sdks/typescript-sdk) instead.

## Examples

Fetch the current identity:

```bash theme={null}
gavai public-api me
```

List workspaces accessible to your account:

```bash theme={null}
gavai public-api workspaces
```

Send a verb explicitly with a body:

```bash theme={null}
gavai public-api POST /v1/workspaces/acme/pages \
  --body '{"slug":"pricing","title":"Pricing"}'
```

Pipe through `jq`:

```bash theme={null}
gavai public-api GET /v1/workspaces/acme/pages | jq '.data | length'
```

## Exit codes

<ErrorTable
  errors={[
{ code: "0", cause: "Response printed (2xx from the API).", fix: "—" },
{ code: "2", cause: "Invalid arguments or malformed `--body`.", fix: "Validate the JSON. Run `gavai public-api --help` for the expected shape." },
{ code: "3", cause: "Not authenticated.", fix: "Run `gavai login`." },
{ code: "4", cause: "Authorization denied (403 / insufficient scope).", fix: "Mint a token with the required scope." },
{ code: "5", cause: "Resource not found (404).", fix: "Verify the path and the active workspace with `gavai whoami`." },
{ code: "6", cause: "Conflict (409).", fix: "Re-fetch the resource, re-apply your change, retry." },
{ code: "7", cause: "Network or API server error (5xx, DNS, timeout).", fix: "Retry with backoff." },
]}
/>

See [CLI overview — exit codes](/cli/overview#exit-codes) for the full table.

<BrandCard eyebrow="SDK" title="TypeScript SDK" href="/sdks/typescript-sdk">
  For anything more than a single request, prefer the SDK over one-off CLI calls.
</BrandCard>