@ainative/cody-cli 0.7.14 → 0.7.16

package/.ainative/skills/ainative-api-reference/SKILL.md

@@ -0,0 +1,118 @@
+---
+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