---
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 Anthropic/Claude-specific 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 | Anthropic SDK format, proxied to LLM backend |

Gateway translates Anthropic 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 Anthropic SDK sends)
3. **Use `Authorization: Bearer` header** for JWT/OAuth auth
4. **Handle 404 gracefully** — Anthropic-specific 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
