---
name: ainative-api-reference
description: AINative platform API endpoint reference for Cody CLI. Use when (1) Making HTTP calls to api.ainative.studio, (2) Integrating new AINative backend features, (3) Working on auth/login/subscription logic, (4) Debugging API 401/404 errors, (5) Checking which endpoints exist on the gateway. Covers all OAuth, auth, subscription, credits, billing, profile, bootstrap, and LLM endpoints with their auth requirements and response formats.
---

# AINative API Reference for Cody CLI

## Gateway

- **Base URL:** `https://api.ainative.studio`
- **Client ID:** `ainative-cody-cli-001`
- **Full docs:** `docs/AINATIVE_API_REFERENCE.md`

## Authentication

| Method | Header | Format | Use Case |
|--------|--------|--------|----------|
| API Key | `x-api-key` | `sk_...` or platform token | LLM calls, subscription, credits |
| JWT Bearer | `Authorization: Bearer {jwt}` | JWT from `/api/v1/auth/login` | User profile, settings |
| OAuth | `Authorization: Bearer {access_token}` | From `/v1/oauth/token` | CLI `/login` flow |

**CRITICAL:** `sk-ant-` prefixed keys are Anthropic format and DO NOT work on the AINative gateway. Only `sk_` prefixed keys and platform tokens are valid.

## Subscription & Plan Check

**Primary endpoint:** `GET /api/v1/public/subscription`
- Auth: `x-api-key` or `Authorization: Bearer`
- Returns: `{success, data: {subscription: {status, plan: {id, name, price, is_active}}}}`
- Plan IDs: `free`, `starter`, `pro`, `business`, `Enterprise`
- Active check: `status === "active" && plan.is_active === true`

**Credit balance:** `GET /api/v1/credits/balance`
- Returns: `{total_credits, used_credits, remaining_credits, plan, usage_percentage}`

## User Identity

| Endpoint | Method | Auth | Returns |
|----------|--------|------|---------|
| `GET /api/v1/auth/me` | GET | Key/JWT | `{id, email, name, email_verified, created_at}` |
| `GET /api/v1/auth/verify` | GET | Key/JWT | `{authenticated, user_id, email, role, method}` |
| `POST /api/v1/auth/login` | POST | None | `{access_token, refresh_token, user: {...}}` |
| `POST /api/v1/auth/refresh` | POST | JWT | `{access_token, token_type, expires_in}` |

## API Key Management

| Endpoint | Method | Auth | Returns |
|----------|--------|------|---------|
| `GET /api/v1/api-keys/` | GET | Key/JWT | `{total, keys: [{id, name, key_preview, is_active}]}` |
| `POST /api/v1/api-keys/` | POST | Key/JWT | `{id, name, api_key, key_preview}` (full key shown once) |
| `PATCH /api/v1/api-keys/{id}/revoke` | PATCH | Key/JWT | `{message, key_id}` |

## Pricing (Public)

| Endpoint | Method | Auth | Returns |
|----------|--------|------|---------|
| `GET /api/v1/public/pricing/plans` | GET | None | `{success, data: {plans: [{id, name, tier, price, features[]}]}}` |
| `GET /api/v1/public/subscription/plans` | GET | None | Available plan list |

## CLI Bootstrap

| Endpoint | Method | Auth | Returns |
|----------|--------|------|---------|
| `GET /api/cody/bootstrap` | GET | x-api-key | `{status, provider, api_base_url, features}` (LEGACY) |
| `GET /api/v1/cli/bootstrap` | GET | Key/JWT | `{client_data, additional_model_options[], user_plan, user}` (PREFERRED) |

**Note:** `/api/cody/bootstrap` is the legacy endpoint currently used by the CLI. `/api/v1/cli/bootstrap` is the newer endpoint with richer data (model catalog with `plan_required` per model, `user_plan`, feature flags, `user` info). Should replace the legacy endpoint.

## Credits & Usage

| Endpoint | Method | Auth | Returns |
|----------|--------|------|---------|
| `GET /api/v1/public/credits/balance` | GET | Key/JWT | `{total_credits, used_credits, remaining_credits, plan, usage_percentage}` |
| `GET /api/v1/public/credits/usage/current` | GET | Key/JWT | `{summary: {total_requests, total_credits_used, total_tokens_processed}, daily_usage[]}` |
| `GET /api/v1/public/subscription/usage` | GET | Key/JWT | `{total_credits_used, total_requests, active_days, monthly_credits_used}` |
| `GET /api/v1/public/credits/transactions` | GET | Key/JWT | `{transactions[], total_records, total_cost}` |
| `GET /api/v1/public/credits/packages` | GET | Key/JWT | Available credit packages for purchase |
| `GET /api/v1/public/credits/auto-refill-settings` | GET | Key/JWT | Auto-refill configuration |

## Endpoints That DO NOT Exist on AINative Gateway

These legacy endpoints return 404 and must be skipped:

| Endpoint | Status | CLI Must Skip |
|----------|--------|---------------|
| `/api/oauth/create_api_key` | 404 | Yes — use `/api/v1/api-keys/` instead |
| `/api/oauth/roles` | 404 | Yes — use `/api/v1/auth/me` for role |
| `/api/cody/profile` | 404 | Yes — use `/api/v1/auth/me` for user info |
| `/api/oauth/profile` | 500 (DB error) | Yes — use `/api/v1/auth/me` for user info |

## LLM Chat Completions

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/v1/messages` | POST | x-api-key | SDK message format, proxied to LLM backend |

Gateway translates SDK message format to OpenAI chat completions internally.

## Plan Tiers

| Plan ID | Name | Price/mo | API Credits | LLM Tokens |
|---------|------|----------|-------------|------------|
| `free` | Free | $0 | 1,000 | 10K |
| `starter` | Starter | $0 | 1,000 | 10K |
| `pro` | Pro | $49 | 50,000 | 1M |
| `business` | Business | $149 | 150,000 | 5M |
| `Enterprise` | Enterprise | $699 | 200,000 | 10M |

## Integration Checklist

When adding a new AINative API call to the CLI:

1. **Check this reference first** — the endpoint may not exist on the gateway
2. **Use `x-api-key` header** for API key auth (what the SDK sends)
3. **Use `Authorization: Bearer` header** for JWT/OAuth auth
4. **Handle 404 gracefully** — Legacy endpoints don't exist
5. **Handle 500 gracefully** — some OAuth endpoints have DB issues
6. **Test against production** before committing: `curl -s https://api.ainative.studio/your/endpoint -H "x-api-key: $AINATIVE_API_TOKEN"`
7. **Update this skill** and `docs/AINATIVE_API_REFERENCE.md` when adding new endpoints

## Codebase Search & Indexing

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `POST /api/v1/zerodb/projects/ensure` | POST | Key/JWT | Create or get project by git repo hash |
| `POST /api/v1/codebase/index` | POST | Key/JWT | Batch index code fragments (up to 100/batch) |
| `GET /api/v1/codebase/index/status?repo_hash=` | GET | Key/JWT | Index status, fragment count, languages |
| `DELETE /api/v1/codebase/index` | DELETE | Key/JWT | Remove fragments for a specific file |
| `POST /api/v1/codebase/search` | POST | Key/JWT | Semantic search over indexed codebase |

## Security Scan

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `POST /api/v1/public/security/scan` | POST | Key/JWT | Scan MCP/settings/hooks for vulnerabilities. Returns score 0-100. |

## Skills Catalog

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `GET /api/v1/public/skills/catalog` | GET | Key/JWT | Browse skills with filters |
| `GET /api/v1/public/skills/{id}` | GET | Key/JWT | Skill detail |
| `POST /api/v1/public/skills/install` | POST | Key/JWT | Track skill installation |
| `POST /api/v1/public/skills/publish` | POST | Key/JWT | Publish org-private skill |
| `POST /api/v1/public/skills/learned` | POST | Key/JWT | Store session-learned skill |
| `GET /api/v1/public/skills/installed` | GET | Key/JWT | List installed skills |

## Usage & Billing

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `GET /api/v1/usage/summary` | GET | Key/JWT | Plan, usage metrics, rate limits |

## Agent Cloud

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `POST /api/v1/cloud/agents/register` | POST | Key/JWT | Register agent in registry |
| `POST /api/v1/cloud/deployments` | POST | Key/JWT | Deploy agent to managed infra |
| `POST /api/v1/cloud/a2a/{agent_id}/message` | POST | Key/JWT | Send A2A message |
| `POST /api/v1/cloud/a2a/route` | POST | Key/JWT | Route message by capability |
| `POST /api/v1/agent/sessions` | POST | Key/JWT | Create remote agent session |
| `GET/POST /v1/code/triggers` | GET/POST | Key/JWT | CRUD remote agent triggers |

## Audio / Voice

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `POST /v1/audio/transcriptions` | POST | Key/JWT | Whisper STT (file upload, max 25MB) |
| `WS /api/ws/speech_to_text/voice_stream` | WebSocket | Key/JWT | Real-time streaming STT |

## Notifications

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `POST /api/v1/public/notifications` | POST | Key/JWT | Send push notification (type: INFO/SUCCESS/WARNING/ERROR) |

## Model Registry

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `GET /api/v1/models/catalog/available` | GET | Key/JWT | Full model catalog with tiers |
| `GET /api/v1/public/models/available` | GET | None | Public model list (no auth) |