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

curl https://api.gavai.app/v1/me \
  -H "Authorization: Bearer gak_test_xxxxxxxxxxxxx"

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

Overview

Resources

API reference

A first request

The contract in one table

Read these first

Resources

Next

Authentication

​A first request

​The contract in one table

​Read these first

​Resources

​Next

Authentication

A first request

The contract in one table

Read these first

Resources

Next