Connect your agent

Connect your agent to FLock. Explore models and manage the platform through the CLI or API.

Agent skill

Give your agent the skill file for platform commands and API workflows.

https://platform.flock.io/api/agents/skill
View skill file

CLI setup

Install the CLI, sign in, and list available models.

npm install -g @flock-io/api
flock auth login --email you@yourorg.com --password '...' --json
flock models list --json

CLI & API reference

Browse the full CLI & API reference

FLock Model API Platform — Agent Skill

Everything an AI agent needs to operate FLock. Install the CLI, authenticate, start calling.

npm install -g @flock-io/api

Production Endpoints:

ServiceURLAuth
LLM Inference (OpenAI-compatible)https://api.flock.io/v1x-litellm-api-key: sk-...
Platform Management APIhttps://platform.flock.io/apiAuthorization: Bearer <jwt>
Platform UI (signup, dashboard)https://platform.flock.ioBrowser
This skill file (raw)https://platform.flock.io/api/agents/skillNone
npm package@flock-io/apiNone

1. Quick Start (4 commands)

# 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, create a team, create an API key, and purchase credits. See Getting Started.

2. Two APIs — Know the Difference

APIBase URLAuthUse For
LLM Inferencehttps://api.flock.io/v1x-litellm-api-key: sk-...Chat completions, image generation (OpenAI-compatible)
Platform Managementhttps://platform.flock.io/apiAuthorization: Bearer <jwt>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

# Default points to https://platform.flock.io — override if needed:
flock config set api-url https://platform.flock.io
flock config show --json
Env VariablePurposeDefault
FLOCK_API_BASE_URLPlatform base URLhttps://platform.flock.io
FLOCK_API_TOKENBearer JWT (skips login)—
FLOCK_LLM_API_KEYDefault API key for flock chat—

Credentials stored in ~/.flock/credentials.json (mode 0600).

3.2 Auth

# 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

# 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 <model-id> --json

# List providers
flock models providers --json

3.4 API Keys

# List your keys
flock api-keys list --json

# Create a key (requires team ID)
flock api-keys create --name "my-agent" --team-id <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.

# List orgs
flock orgs list --json

# List members
flock orgs members --org-id <org-id> --json

3.6 Teams

# 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 <org-id> --json

# Get team details
flock teams get <team-id> --json

# Invite a member
flock teams invite --team-id <team-id> --email dev@yourorg.com --role member

# Remove a member
flock teams remove-member --team-id <team-id> --user-id <user-id>

3.7 Billing & Usage

# 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)

# 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)

flock admin users list --page 1 --json
flock admin users get <id> --json
flock admin users delete <id>
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

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

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

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:

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

MethodPathAuthDescription
POST/api/auth/tokenNoneExchange credentials for JWT
POST/api/auth/token/refreshBearerRefresh JWT
GET/api/auth/meBearerCurrent user
GET/api/modelsNoneList models
GET/api/providersNoneList providers
GET/api/api-keysBearerList keys
POST/api/lite-llm/api-keysBearerCreate key { name, team_id }
POST/api/api-keys/updateBearerUpdate key { token, name }
POST/api/api-keys/removeBearerDelete key { apiKey }
GET/api/lite-llm/organizations/listBearerList orgs
PUT/api/lite-llm/organizationsBearerUpdate org
GET/api/lite-llm/teamsBearerList teams
POST/api/lite-llm/teamsBearerCreate team { name } (uses active org from session)
GET/api/lite-llm/teams/:idBearerGet team
POST/api/lite-llm/teams/invite-memberBearerInvite { teamId, teamName, email, role }
POST/api/lite-llm/teams/remove-memberBearerRemove { teamId, memberId }
GET/api/balanceBearerCredit balance
GET/api/quotaBearerQuota details
GET/api/lite-llm/logsBearerUsage logs
POST/api/lite-llm/messagesBearerChat completion (platform proxy) { model, messages, apiKey }

LLM Inference (separate API, OpenAI-compatible):

MethodPath (base: api.flock.io/v1)Auth HeaderDescription
POST/chat/completionsx-litellm-api-keyDirect chat completion

5. Response Formats

Success (paginated)

{ "data": [...], "meta": { "page": 1, "pageSize": 10, "total": 42, "totalPages": 5 } }

Error

{ "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)

{ "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

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 <org_id> --json  # note team ID
flock api-keys create --name "bot" --team-id <team_id> --json # note the key
flock chat --model qwen3-30b-a3b-instruct-2507 --api-key <key> "Hello!" --json

B: Check billing

flock balance --json
flock usage --start-date 2026-04-01 --end-date 2026-04-07 --json

C: Rotate an API key

flock api-keys list --json
flock api-keys remove --token <old>
flock api-keys create --name "rotated" --team-id <team_id> --json

D: Environment-only auth

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

SymptomFix
401 on api.flock.ioUse x-litellm-api-key: sk-... not Authorization: Bearer
401 on CLI commandsflock auth login or set FLOCK_API_TOKEN
QUOTA_EXCEEDED / TEAM_BLOCKEDBuy credits at platform.flock.io > Settings > Billing
Model not foundflock models list --json to see available models
403 on admin commandsRequires admin role

9. Links