Teams Catalog API

The teams catalog API is the control-plane surface behind catalog teams — the ready-made starter groups Paperclip ships with the app. A catalog team bundles a small set of agents, projects, tasks, and the skills they need, so you can drop a whole working unit into a company in one step. These endpoints let you browse the catalog, inspect a single team and its files, see what is already installed in a company, preview an import, and install a team.

For the user-facing concept and CLI workflow, see Teams Commands and the Team Catalog guide. This page documents the raw HTTP endpoints that those tools call.

All routes here are mounted under /api. The browsing routes need only an authenticated caller and no company context; the installed, preview, and install routes are company-scoped and check company access.

There are two kinds of catalog teams. Bundled teams ship inside the app and are the everyday starting points. Optional teams are extras, some of which pull in skills from external sources. The kind filter switches between the two.

Browse the catalog

GET /api/teams/catalog

Returns the catalog teams the caller can see. Browsing reads the catalog without writing anything and requires no company context.

Query parameters

Each catalog team in the response carries id, key, kind, category, slug, name, description, path, entrypoint, schema, defaultInstall, recommendedForCompanyTypes, tags, a counts object (agents, projects, tasks, routines, localSkills, catalogSkills, externalSkillSources), rootAgentSlugs, agentSlugs, projectSlugs, requiredSkills, envInputs, sourceRefs, files, trustLevel, compatibility, and contentHash. Optional teams sourced from a package also include packageName and packageVersion.

Inspect one catalog team

GET /api/teams/catalog/{catalogId}

Returns the full record for a single catalog team — the same shape as a list entry, including its agents, projects, tasks, required skills, and file manifest. Inspecting a team before you install it is the clearest way to see exactly what will land in the company.

The path segment {catalogId} is a catalog reference: a catalog team ID, key, or unique slug. You can also pass the reference explicitly with the ref query parameter, which takes precedence over the path segment.

Query parameters

Read a catalog team file

GET /api/teams/catalog/{catalogId}/files

Returns one file out of the catalog team package — for example TEAM.md. Use this to read a team's manifest or any referenced file without installing it.

Query parameters

The response carries catalogTeamId, path, kind, content, language, and markdown.

List installed catalog teams

GET /api/companies/{companyId}/teams/catalog/installed

Returns the catalog teams already installed in the given company. This is the company-lensed view: it tells you which teams are present and lets a client flag teams that have drifted out of date from the current catalog version. Company access is checked before the listing runs.

Preview an install

POST /api/companies/{companyId}/teams/catalog/{catalogId}/preview

Runs the import on the server and returns the plan without writing anything to the company. The preview reports what would be created, which skills the team needs and how they would be prepared, and any warnings or errors. Company access is checked before the preview runs.

All body fields are optional:

The {catalogId} path segment is a catalog reference, and the ref query parameter overrides it when present, exactly as on the browse routes.

curl -X POST "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetManagerSlug": "cto",
    "collisionStrategy": "rename"
  }'

const res = await fetch(
  "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      targetManagerSlug: "cto",
      collisionStrategy: "rename",
    }),
  },
);
const plan = await res.json();

import requests

res = requests.post(
    "http://localhost:3100/api/companies/company-1/teams/catalog/core-exec-team/preview",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "targetManagerSlug": "cto",
        "collisionStrategy": "rename",
    },
)
plan = res.json()

Install a team

POST /api/companies/{companyId}/teams/catalog/{catalogId}/install

Does what preview shows: imports the team into the company, creating its agents, projects, and tasks, and preparing its required skills. On success the route responds with 201. Because installing a team creates agents, the caller must be able to create agents in the company — board callers need the agents:create permission (local implicit and instance-admin board callers are exempt), and agent callers need an agents:create grant or the equivalent agent permission.

The install body accepts everything preview accepts, plus:

As with preview, {catalogId} is a catalog reference and the ref query parameter overrides it when present.

curl -X POST "http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "targetManagerSlug": "cto",
    "adapterOverrides": {
      "senior-coder": { "adapterType": "claude_local" }
    }
  }'

const res = await fetch(
  "http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      targetManagerSlug: "cto",
      adapterOverrides: {
        "senior-coder": { adapterType: "claude_local" },
      },
    }),
  },
);
const result = await res.json();

import requests

res = requests.post(
    "http://localhost:3100/api/companies/company-1/teams/catalog/product-engineering/install",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "targetManagerSlug": "cto",
        "adapterOverrides": {
            "senior-coder": {"adapterType": "claude_local"},
        },
    },
)
result = res.json()

Practical notes

• Catalog teams ship without a fixed adapter per agent on purpose. Use adapterOverrides to pin a specific agent to a runtime such as claude_local or codex_local; agents you do not override are resolved at import time.
• Browse, inspect, and file reads require only an authenticated caller. The installed, preview, and install routes check company access first.
• Preview writes nothing. Run it before install to confirm what will be created and how the team's skills will be prepared.
• The install route enforces the agents:create permission. If you lack it, the install is rejected before anything is created.