--- name: flock-model-api-platform description: >- Agent skill for fully operating the FLock Model API Platform. Install the CLI with npm install -g @flock-io/api, authenticate, and manage models, API keys, teams, billing, and chat completions from the terminal. --- # FLock Model API Platform — Agent Skill Everything an AI agent needs to operate FLock. Install the CLI, authenticate, start calling. ```bash npm install -g @flock-io/api ``` **Production Endpoints:** | Service | URL | Auth | |---------|-----|------| | LLM Inference (OpenAI-compatible) | `https://api.flock.io/v1` | `x-litellm-api-key: sk-...` | | Platform Management API | `https://platform.flock.io/api` | `Authorization: Bearer ` | | Platform UI (signup, dashboard) | `https://platform.flock.io` | Browser | | This skill file (raw) | `https://platform.flock.io/api/agents/skill` | None | | npm package | `@flock-io/api` | None | --- ## 1. Quick Start (4 commands) ```bash # Install npm install -g @flock-io/api # Authenticate flock auth login --email you@yourorg.com --password '...' # Browse models flock models list --json # Call an LLM (requires a platform API key from the dashboard) flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-your-key "Hello!" --json ``` **Don't have an account?** Sign up at [platform.flock.io](https://platform.flock.io), create a team, create an API key, and purchase credits. See [Getting Started](https://docs.flock.io/flock-products/api-platform/getting-started). --- ## 2. Two APIs — Know the Difference | API | Base URL | Auth | Use For | |-----|----------|------|---------| | **LLM Inference** | `https://api.flock.io/v1` | `x-litellm-api-key: sk-...` | Chat completions, image generation (OpenAI-compatible) | | **Platform Management** | `https://platform.flock.io/api` | `Authorization: Bearer ` | Account, API keys, teams, billing, usage logs | The `flock` CLI talks to the **Platform Management API**. For LLM inference, use your API key directly with `api.flock.io/v1` or via `flock chat`. --- ## 3. CLI Reference ### 3.1 Configuration ```bash # Default points to https://platform.flock.io — override if needed: flock config set api-url https://platform.flock.io flock config show --json ``` | Env Variable | Purpose | Default | |-------------|---------|---------| | `FLOCK_API_BASE_URL` | Platform base URL | `https://platform.flock.io` | | `FLOCK_API_TOKEN` | Bearer JWT (skips login) | — | | `FLOCK_LLM_API_KEY` | Default API key for `flock chat` | — | Credentials stored in `~/.flock/credentials.json` (mode `0600`). ### 3.2 Auth ```bash # Sign in (non-interactive, agent-friendly) flock auth login --email you@yourorg.com --password '...' --json # → { "token": "eyJ...", "expiresAt": "...", "email": "..." } # Or skip login entirely with env vars: export FLOCK_API_TOKEN="eyJ..." # Check who you are flock auth whoami --json # → { "user": { "id": 1, "email": "...", "name": "...", "role": "user" } } # Print raw token (for piping) flock auth token # Sign out flock auth logout ``` ### 3.3 Models ```bash # List all models flock models list --json # Search and filter flock models list --search qwen --type chat --json # Get a specific model flock models get --json # List providers flock models providers --json ``` ### 3.4 API Keys ```bash # List your keys flock api-keys list --json # Create a key (requires team ID) flock api-keys create --name "my-agent" --team-id --json # Rename a key flock api-keys update --token sk-... --name "renamed" --json # Delete a key flock api-keys remove --token sk-... ``` ### 3.5 Organizations Organizations are auto-created when you sign up. Use the CLI to list and inspect them. ```bash # List orgs flock orgs list --json # List members flock orgs members --org-id --json ``` ### 3.6 Teams ```bash # List teams flock teams list --json # Create team (uses your active org; --org-id is passed to the CLI but org is resolved from session) flock teams create --name "Engineering" --org-id --json # Get team details flock teams get --json # Invite a member flock teams invite --team-id --email dev@yourorg.com --role member # Remove a member flock teams remove-member --team-id --user-id ``` ### 3.7 Billing & Usage ```bash # Check credit balance (amount in nano-USD; divide by 1e9 for USD) flock balance --json # Query usage logs flock usage --start-date 2026-04-01 --end-date 2026-04-07 --json # Filter by API key flock usage --api-key sk-... --json ``` ### 3.8 Chat (LLM Completion) ```bash # Basic completion flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-... "What is 2+2?" --json # → { "content": "2 + 2 equals 4." } # Stream to stdout flock chat --model qwen3-30b-a3b-instruct-2507 --api-key sk-... "Write a haiku" --stream # Use env var for API key export FLOCK_LLM_API_KEY="sk-..." flock chat --model qwen3-30b-a3b-instruct-2507 "Hello!" --json ``` ### 3.9 Admin (admin role only) ```bash flock admin users list --page 1 --json flock admin users get --json flock admin users delete flock admin models create --name "Model" --provider qwen --litellm-id my-model --json ``` ### 3.10 REPL Run `flock` with no arguments to enter an interactive REPL: ``` $ flock flock> models list --json flock> balance --json flock> exit ``` --- ## 4. Direct HTTP API (Alternative to CLI) All CLI commands map to HTTP calls. Use these when the CLI is not available. ### 4.1 Get a Bearer Token ```bash curl -s -X POST 'https://platform.flock.io/api/auth/token' \ -H 'Content-Type: application/json' \ -d '{"email":"you@yourorg.com","password":"your-password"}' # → { "token": "eyJ...", "expiresAt": "..." } ``` ### 4.2 Use the Token ```bash TOKEN="eyJ..." curl -s 'https://platform.flock.io/api/models' -H "Authorization: Bearer $TOKEN" curl -s 'https://platform.flock.io/api/api-keys' -H "Authorization: Bearer $TOKEN" curl -s 'https://platform.flock.io/api/balance' -H "Authorization: Bearer $TOKEN" ``` ### 4.3 Call the LLM API Directly ```bash curl -X POST 'https://api.flock.io/v1/chat/completions' \ -H 'Content-Type: application/json' \ -H 'x-litellm-api-key: sk-your-api-key' \ -d '{ "model": "qwen3-30b-a3b-instruct-2507", "messages": [{"role": "user", "content": "Hello!"}] }' ``` Or use the **OpenAI Python SDK**: ```python from openai import OpenAI client = OpenAI( base_url="https://api.flock.io/v1", api_key="sk-your-api-key", ) response = client.chat.completions.create( model="qwen3-30b-a3b-instruct-2507", messages=[{"role": "user", "content": "Hello!"}], ) print(response.choices[0].message.content) ``` ### 4.4 Full HTTP Endpoint Table | Method | Path | Auth | Description | |--------|------|------|-------------| | POST | `/api/auth/token` | None | Exchange credentials for JWT | | POST | `/api/auth/token/refresh` | Bearer | Refresh JWT | | GET | `/api/auth/me` | Bearer | Current user | | GET | `/api/models` | None | List models | | GET | `/api/providers` | None | List providers | | GET | `/api/api-keys` | Bearer | List keys | | POST | `/api/lite-llm/api-keys` | Bearer | Create key `{ name, team_id }` | | POST | `/api/api-keys/update` | Bearer | Update key `{ token, name }` | | POST | `/api/api-keys/remove` | Bearer | Delete key `{ apiKey }` | | GET | `/api/lite-llm/organizations/list` | Bearer | List orgs | | PUT | `/api/lite-llm/organizations` | Bearer | Update org | | GET | `/api/lite-llm/teams` | Bearer | List teams | | POST | `/api/lite-llm/teams` | Bearer | Create team `{ name }` (uses active org from session) | | GET | `/api/lite-llm/teams/:id` | Bearer | Get team | | POST | `/api/lite-llm/teams/invite-member` | Bearer | Invite `{ teamId, teamName, email, role }` | | POST | `/api/lite-llm/teams/remove-member` | Bearer | Remove `{ teamId, memberId }` | | GET | `/api/balance` | Bearer | Credit balance | | GET | `/api/quota` | Bearer | Quota details | | GET | `/api/lite-llm/logs` | Bearer | Usage logs | | POST | `/api/lite-llm/messages` | Bearer | Chat completion (platform proxy) `{ model, messages, apiKey }` | LLM Inference (separate API, OpenAI-compatible): | Method | Path (base: `api.flock.io/v1`) | Auth Header | Description | |--------|-------------------------------|-------------|-------------| | POST | `/chat/completions` | `x-litellm-api-key` | Direct chat completion | --- ## 5. Response Formats ### Success (paginated) ```json { "data": [...], "meta": { "page": 1, "pageSize": 10, "total": 42, "totalPages": 5 } } ``` ### Error ```json { "error": "Human-readable message", "code": "MACHINE_CODE" } ``` Codes: `UNAUTHORIZED`, `FORBIDDEN`, `VALIDATION_ERROR`, `NOT_FOUND`, `QUOTA_EXCEEDED`, `TEAM_BLOCKED`, `SERVER_ERROR`, `DB_TIMEOUT`. ### CLI Error (with `--json`) ```json { "error": "Not logged in", "code": "UNAUTHORIZED", "status": 401 } ``` Without `--json`: red line to stderr, exit code `1`. --- ## 6. Common Agent Workflows ### A: Get started from zero ```bash npm install -g @flock-io/api flock auth login --email you@yourorg.com --password '...' --json flock orgs list --json # note your org ID flock teams create --name "Agents" --org-id --json # note team ID flock api-keys create --name "bot" --team-id --json # note the key flock chat --model qwen3-30b-a3b-instruct-2507 --api-key "Hello!" --json ``` ### B: Check billing ```bash flock balance --json flock usage --start-date 2026-04-01 --end-date 2026-04-07 --json ``` ### C: Rotate an API key ```bash flock api-keys list --json flock api-keys remove --token flock api-keys create --name "rotated" --team-id --json ``` ### D: Environment-only auth ```bash export FLOCK_API_TOKEN="eyJ..." flock models list --json flock balance --json ``` --- ## 7. Domain Concepts ### Entity Hierarchy ``` User → Organization → Team → APIKey → calls api.flock.io/v1 → OrganizationQuota (nano-USD balance) ``` ### Currency nano-USD: 1 USD = 1,000,000,000 nano-USD. Divide `amount` by `1e9` for USD. ### Credit Lifecycle Sign up → buy credits → create API key → call LLM → usage settled → quota decreases → negative = teams blocked → buy more = unblocked. --- ## 8. Troubleshooting | Symptom | Fix | |---------|-----| | `401` on `api.flock.io` | Use `x-litellm-api-key: sk-...` not `Authorization: Bearer` | | `401` on CLI commands | `flock auth login` or set `FLOCK_API_TOKEN` | | `QUOTA_EXCEEDED` / `TEAM_BLOCKED` | Buy credits at platform.flock.io > Settings > Billing | | Model not found | `flock models list --json` to see available models | | `403` on admin commands | Requires admin role | --- ## 9. Links - [npm: @flock-io/api](https://www.npmjs.com/package/@flock-io/api) - [Getting Started](https://docs.flock.io/flock-products/api-platform/getting-started) - [API Endpoint Docs](https://docs.flock.io/flock-products/api-platform/api-endpoint) - [Platform Dashboard](https://platform.flock.io)