Building on the Norbelys API with Claude Code: a practical guide

This is a guide to using Claude Code as the pair programmer for a real integration against the Norbelys API — not asking it to write a snippet, but handing it a small, well-scoped task and letting it plan, write, and run the code. The interesting part isn’t Claude Code itself; it’s the ten minutes of setup beforehand that decide whether the agent is grounded in your actual API or quietly improvising one that sounds plausible.

The problem with a cold start

Point any coding agent at an unfamiliar REST API with nothing but “build me a thing that uses it” and it will do exactly what a competent developer would do without documentation: pattern-match against APIs it has seen before. For Norbelys that goes wrong in specific, predictable ways — because our surface deliberately isn’t the generic REST API a training set is full of. It uses cursor pagination, never ?page= (why, in detail). Bulk operations are a job resource you create and poll, not a bespoke /import endpoint (the pattern, explained). Every non-CRUD action is POST /v1/<resource>/:id:<verb> — a colon, not a sub-route. Field names follow Schema.org (givenName, not first_name). None of that is exotic once you know it, and all of it is exactly the kind of detail an agent gets wrong by default and gets right immediately once told.

That’s what the Norbelys agent kit is for: an AGENTS.md plus topic skills that hand Claude Code this context up front, so you’re not re-explaining pagination or the action convention in every new session.

Set up once

Terminal

$ git clone https://github.com/norbelys-com/agents$ export NORBELYS_API_KEY="ak_test_..."$ claudeClaude Code v… — reading AGENTS.md…

A realistic task, start to finish

Here’s a task sized right for a single Claude Code session: write a script that finds every person with a bounced message in the last seven days and adds them to the suppression list, so a stale address can’t get re-sent to by accident next campaign. It’s small, it has an obvious success condition, and it touches three resources — messages, people, and suppressions — which is enough to exercise the conventions worth learning.

A reasonable opening prompt:

“Write a Node script using @norbelys/sdk. List messages from the last 7 days where the status indicates a bounce, resolve each to its person, and create a suppression entry for that email if one doesn’t already exist. Read the API key from NORBELYS_API_KEY. Log a summary at the end: how many suppressed, how many already present.”

With the agent kit in context, this is where the payoff shows up. Claude Code already knows list endpoints take ?cursor= and ?limit=, not a page number, so it writes a loop that drains the full result set correctly on the first try instead of silently stopping after one page. It knows a messages row already carries the fields it needs rather than reaching for a separate “get bounce details” endpoint that doesn’t exist. And because suppressions follows the same resource pattern as everything else, it doesn’t need a special explanation to know POST /v1/suppressions is the create call.

What to actually check in the diff

Grounding in the agent kit gets the shape of the API calls right; it doesn’t replace reading what the agent wrote. Three things worth checking specifically on a task like this one:

• Idempotency. A script that runs on a schedule will be re-run with overlapping windows sooner or later. Confirm it either checks for an existing suppression first or relies on the API rejecting the duplicate gracefully — don’t assume the agent got this right just because the happy path works once.
• Error handling on the write, not just the read. It’s easy for a generated script to handle a failed list call and forget that the suppression create can also fail (rate limit, validation error) — and fail silently is worse here than fail loud, because a person who should have been suppressed and wasn’t is a real, recurring send.
• What it logs. If you told it not to print the API key, verify it didn’t anyway — a debug console.log(process.env) slipped into a script “just to check the connection worked” is a common, easy-to-miss mistake, and it’s exactly the failure mode the auth guide is about.

Why the kit changes the outcome, not just the vibes

It’s worth being concrete about what actually improves when the agent kit is loaded, versus a session without it. Ask Claude Code to write the same script cold, with no AGENTS.md in context, and a common result is a script that works on the happy path in a demo and breaks the first time it meets a list with more than one page — because nothing told the agent that pagination here is cursor-based, so it wrote the offset loop it’s seen a thousand times elsewhere. That’s not a hypothetical; it’s the single most common gap between an agent’s prior and this specific API’s actual shape, and it’s exactly the kind of bug that passes a quick manual test and fails quietly in production a week later on a bigger dataset.

Iterate like you would with any pair programmer

Once the first version runs, the loop is ordinary software development, not anything specific to AI: run it against a small, low-stakes slice of data first, read the summary output, ask for the one thing that’s wrong, repeat. The agent kit’s job stops at “get the API calls right” — the judgment about whether the task is right (should this really auto-suppress, or should it flag for review first?) stays with you the whole way through.

Where to go from here

This pattern — kit loaded once, small well-scoped task, review the plan and the diff — scales to bigger builds. Building an internal ops dashboard walks a larger example end to end, and if you haven’t set up the scoped credential yet, the auth guide covers exactly how before your next session starts. For the reasoning behind why the kit exists in the first place, see the agent-kit overview.