Core concepts

Applications

The container everything else belongs to, and the two hostnames it gets.

An application is a single product. It owns its end users, its keys, its bundles and its model names, and it is the thing a base URL points at. A customer with two products has two applications and no shared end users between them.

Create one

Creating an application assigns both hostnames at once. You do not configure DNS, and you do not choose the shape.

seams apps create acmechat --name "Acme Chat"

# slug     acmechat
# gateway  https://acmechat.gw.ourseams.com/v1
# portal   https://acmechat.portal.ourseams.com

import { Seams } from "@ourseams/sdk"

const seams = new Seams({ apiKey: process.env.SEAMS_API_KEY! })
const app = await seams.apps.create("acmechat", { name: "Acme Chat" })
// app.gateway · app.portal

import os
from seams import Seams

seams = Seams(api_key=os.environ["SEAMS_API_KEY"])
app = seams.apps.create("acmechat", name="Acme Chat")
# app.gateway · app.portal

Clients point at that gateway hostname. The slug in the Host header is how the call finds this application; there is no default app.

cli

curl https://acmechat.gw.ourseams.com/v1/chat/completions \
  -H "Authorization: Bearer ak_acmechat_…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "acme/smart",
    "messages": [{ "role": "user", "content": "Say hello" }]
  }'

Custom domains are not offered. Every surface is a subdomain of ours, which keeps certificate issuance, application resolution and the portal's cookie scope out of your operations.

Switch and inspect

use records the active application for later calls. Locally the CLI also writes ~/.seams/config.json; the API use is what the SDKs share.

seams apps list
seams apps use acme-chat
seams apps current
seams apps show acme-chat

await seams.apps.list()
await seams.apps.use("acme-chat")
const current = await seams.apps.current()
const one = await seams.apps.show("acme-chat")

seams.apps.list()
seams.apps.use("acme-chat")
current = seams.apps.current()
one = seams.apps.show("acme-chat")

A sk_ token is scoped to its organization, not to the active application. Switching changes which application your commands read; it does not widen or narrow the token.

What one holds

Field	Means
`slug`	The name in both hostnames; immutable once created
`gateway`	Your gateway host (what clients call)
`portal`	Where an end user lands from a portal session
`endUsers` · `keys`	How many of each the application has
`bundles` · `models`	What is on offer and what it resolves to
`costUsd`	Provider cost attributed to this application

Applications

Create one

Switch and inspect

Archive

What one holds