accounted/scripts/api-skill/overlays/quickstart.md at main

Files

T

Jakob Wennberg 11b82cbb91 feat(api): installable accounted-api agent skill + openapi-to-skill generator (#1516 )

* feat(api): installable accounted-api agent skill + openapi-to-skill generator

Three layers, per the July/August 2026 agent-skills ecosystem (skills.sh /
npx skills add, as used by Stripe/Cloudflare/Supabase for their APIs):

- skills/openapi-to-skill/: generic, installable skill that turns any
  OpenAPI spec into a consumer-side integration skill, with a portable
  stdlib-only inventory/condenser tool and an output template + quality
  checklist encoding the distill-not-restate methodology.
- skills/accounted-api/: the installable skill for our own API, rendered
  deterministically by scripts/api-skill/generate.ts from the v1 endpoint
  registry + hand-authored overlays (auth, conventions, domain gotchas).
  CI gate: npm run apiskill:check (core-build.yml).
- lib/api/v1/registry.ts: generateOpenApiSpec now emits requestBody (incl.
  multipart binary parts) and path parameters, and the Zod converter learned
  .default()/z.record()/.pipe()/.transform(), so the public spec carries
  request contracts instead of prose-only.

Docs: /docs/api landing + /llms.txt now point agents at the skill install;
corrected the stale test-key description in the landing (test keys read
real data and force dry-run writes; they are not sandbox-company bound).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(skills): escape backslashes in markdown table cells (CodeQL js/incomplete-sanitization)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

2026-08-11 12:45:19 +02:00

1.3 KiB

Raw Permalink Blame History

Auth and base URL

Every request sends a bearer key:

curl https://app.gnubok.se/api/v1/companies \
  -H "Authorization: Bearer gnubok_sk_live_..."

Base URL: https://app.gnubok.se/api/v1 (legacy machine host, permanent). https://app.accounted.se/api/v1 serves the identical API.
Keys are created in the Accounted dashboard under Settings -> API (/settings/api). Two prefixes:
- gnubok_sk_live_* commits real writes.
- gnubok_sk_test_* reads real company data but forces every write into dry-run (responses carry X-Gnubok-Mode: test). Develop and run evals with a test key; switch to live last.
Each key carries scopes (invoices:read, invoices:write, payroll:write, webhooks:manage, ...). Every endpoint in the index below is annotated with its required scope; a missing scope returns 403.
Rate limit: 100 requests/minute per key. On 429, honor Retry-After.
URLs carry the company id explicitly (/api/v1/companies/{companyId}/invoices). A key can act on any company its user is a member of; start every session with GET /api/v1/companies to discover ids. There is no implicit "current company".

First calls, in order: GET /api/v1/health (no auth, connectivity), then GET /api/v1/companies (auth works, discover companyId).

1.3 KiB Raw Permalink Blame History

Auth and base URL

1.3 KiB

Raw Permalink Blame History