Home › CodeGoLive › › Creating Your First Company

Creating Your First Company

POST /api/companies, required fields (name, timezone), the company_id boundary that scopes all downstream data, and viewing the new company in the dashboard.

Creating Your First AI Company

What you'll learn

By the end of this lesson you will have created a company record in Paperclip AI, understand what a "company" represents in the data model, and be ready to hire your first agent.

What is a "Company"?

In Paperclip AI a company is the top-level organizational boundary. Everything — agents, tasks, issues, approvals, cost events — belongs to exactly one company. The company_id column appears on every table and every query filters by it, giving you hard multi-tenancy in a single database.

companies
├── agents        (the workers)
├── issues        (the work queue)
├── heartbeat_runs (execution log)
├── approvals     (human sign-off)
└── cost_events   (spending ledger)

Think of it like a Stripe account: the boundary is conceptual but the enforcement is real.

Creating a Company via the UI

  1. Start Paperclip AI (pnpm dev from the repo root — both API and frontend start together).
  2. Open http://localhost:5173 in your browser.
  3. Click "New Company" in the top nav.
  4. Fill in:
  5. Name — e.g. Acme Automations
  6. Slug — auto-generated from name; must be URL-safe
  7. Monthly budget — set a safe ceiling like $10.00 for now
  8. Click Create.

The UI redirects you to the company dashboard. The URL contains the company id — keep it handy.

Creating a Company via the API

curl -X POST http://localhost:3100/api/companies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Automations",
    "slug": "acme-automations",
    "monthly_budget_usd": 10.00
  }'

Response:

{
  "id": "01929f3a-...",
  "name": "Acme Automations",
  "slug": "acme-automations",
  "monthly_budget_usd": "10.00",
  "created_at": "2024-01-15T10:30:00Z"
}

Save the id — you'll reference it when hiring agents and seeding tasks.

Creating a Company in SQL (seed scripts)

For repeatable environments, use an upsert:

INSERT INTO public.companies (name, slug, monthly_budget_usd)
VALUES ('Acme Automations', 'acme-automations', 10.00)
ON CONFLICT (slug) DO UPDATE SET
  name = EXCLUDED.name,
  monthly_budget_usd = EXCLUDED.monthly_budget_usd
RETURNING id;

The Company Schema At a Glance

Column Type Purpose
id uuid Primary key, auto-generated
name text Display name
slug text URL-safe identifier (unique)
monthly_budget_usd numeric Spending cap; triggers auto-pause
paused boolean Set by circuit-breaker when budget exceeded
created_at timestamptz Record creation time

Checkpoint ✓

Sign in for progress tracking & Q&A →