Project layout

The tree

my-api-tests/
├── users.yaml                    # a collection
├── orders.yaml                   # another collection
└── .tinspec/
    ├── chains/<name>.yaml        # one file per chain
    ├── auth/<name>.yaml          # auth provider definitions
    ├── providers/<stem>.yaml     # API providers (spec bindings)
    ├── route-matchers/<name>.yaml
    ├── overlays/<provider-id>.yaml
    ├── themes/<name>.json
    ├── sync.yaml                 # per-document synced versions (cloud tier)
    └── tinspec.db                # SQLite: run history + spec cache

What each holds

Path	Contents	Commit?
*.yaml (root)	Collections: requests, environments, defaults, spec sources, auth providers, route matchers	Yes
.tinspec/chains/	One chain per file, formatVersion: 3	Yes
.tinspec/auth/	Auth provider definitions — config and secret names, never values	Yes
.tinspec/providers/	API providers: spec location, poll interval, gateway binding	Yes
.tinspec/route-matchers/	Gateway configs stored inline	Yes
.tinspec/overlays/	Your persistent edits to spec-generated endpoints	Yes
.tinspec/themes/	User-authored themes	Your call
.tinspec/sync.yaml	Per-document synced versions. Non-secret; safe to delete	Optional
.tinspec/tinspec.db	Run history, spec cache, search index	No

.gitignore

.tinspec/tinspec.db
.tinspec/tinspec.db-*

That is all that needs excluding. Everything else in the folder is meant to be reviewed in a merge request.

The rules that govern this layout

Files are the source of truth. Collections, chains, auth definitions, providers, route matchers, and overlays are authoritative. Nothing about your API tests exists only in a database.

SQLite is a rebuildable cache. tinspec.db holds run history, the cached OpenAPI documents, and search indexes. Delete it and everything is rebuilt by re-reading the files. The only thing genuinely lost is run history. This is why it is the one entry in .gitignore — it is derived, machine-local, and large.

Secrets are in neither. Not in the YAML, not in the database. They live in your OS keychain or a machine-local encrypted store, chosen in Settings → Security, and the files reference them by name. Committing this folder does not commit a credential.

The spec cache

Each provider’s last successfully fetched OpenAPI document is cached in tinspec.db. It backs three things: endpoints that keep working when the service is offline, the copy a spec subset action, and the field-by-field explanation in Spec Changes.

Folderless projects

A project without a folder writes nothing. Requests live in memory for the session, and run history, the spec cache, and endpoint overlays are unavailable — there is nowhere to put them.

Fine for a scratch session. Not where real work should live.

Where machine-local state goes instead

Some state is deliberately not in your project folder, because it should not travel with the repository:

• Secrets — OS keychain or the machine-local encrypted store.
• The cloud device token — the encrypted store, so signing in never triggers a keychain prompt.
• Your Anthropic API key, if AI assist is on — the encrypted store.
• The agent-access token and port — the encrypted store and app settings.
• App settings, the recent-project list, keybinding overrides, the active theme — an app settings store, not the project.