norbelys.com/developers/ is the one page that lists everything a developer or an AI agent can use to drive Norbelys without touching the dashboard. It’s not a marketing page dressed up as documentation — every link on it goes somewhere real: a live spec, a published package, a working server. This is a walk through what’s actually there, and a short answer to the question most people land on that page actually asking: where do I start?

What’s on the page

Eight resources, each pointing at something concrete rather than a promise of one:

The REST API — base URL https://api.norbelys.com/v1. Bearer auth, cursor pagination, typed errors. This is the thing every other surface on the page is a projection of.

The OpenAPI 3.1 spec — https://api.norbelys.com/openapi.json, 83 operations as of this writing. It’s generated straight from the same typed contract the API worker implements, not a hand-maintained file someone updates when they remember to. A full tour of what’s in it is worth reading if you plan to import it into Postman, Insomnia, or a code generator.

The API documentation at docs.norbelys.com — guides, a quickstart, and the full reference with code samples, for reading prose instead of a raw spec.

Four official SDKs — @norbelys/sdk on npm, norbelys on PyPI, plus Go and Ruby. All generated from the OpenAPI spec above, which means the method names and field names match the API documentation exactly, with no translation layer to drift out of sync over time.

The norbelys CLI — npm i -g norbelys, or curl -fsSL https://cli.norbelys.com/install | sh if you’d rather skip npm entirely. Generated from the same contract as the API, so every resource command exists because the endpoint exists.

The MCP server at mcp.norbelys.com/mcp — Streamable HTTP, roughly 82 tools, for driving Norbelys from Claude, Cursor, or an agent you built yourself. The full mechanics — auth, tool annotations, what it deliberately doesn’t do are covered elsewhere; this page is just where you find the URL.

Agent authentication at norbelys.com/auth.md — API keys for headless and CI callers, OAuth 2.1 discovery (via /.well-known/oauth-protected-resource) for interactive agents that can complete a sign-in flow. One document, both paths explained.

The agent kit on GitHub (norbelys-com/agents) — AGENTS.md, agent skills, and Cursor rules for how an AI agent should actually use Norbelys, so building an agent against the platform starts from a template instead of a blank file.

The page also has a search box wired for both humans and in-browser AI agents (it’s exposed via WebMCP with a described tool, search_norbelys) — worth knowing about if you’re testing how discoverable the site itself is to an agent poking around it. It’s a small detail, but it’s consistent with the rest of the portal’s philosophy: the developer surface isn’t only for people typing into a terminal by hand, it’s also built to be legible to the agents that increasingly do the typing on a developer’s behalf.

None of the eight resources duplicates another — that’s worth noticing, because plenty of developer portals pad themselves out with three different pages that all describe the same auth flow in slightly different words. Here, the docs site explains concepts, the OpenAPI spec is the machine-readable ground truth, the SDKs are how you consume it in application code, the CLI is how you consume it from a terminal, the MCP server is how an agent consumes it, and auth.md plus the agent kit cover the two things that don’t fit neatly into any of the others: how credentials actually work, and how to structure an agent that behaves well once it has one.

Authentication, in one paragraph

Two paths, covered once instead of once per surface. Headless and CI callers use an org-scoped API key (ak_...) created in the app, sent as Authorization: Bearer ak_.... Interactive agents — the kind that can complete a browser-based consent flow — register through OAuth 2.1 using the metadata at /.well-known/oauth-protected-resource. Whichever path you use, it’s the same credential the CLI, the SDKs, and the MCP server all authenticate with — there’s no separate auth system per surface to learn.

Where to start, based on what you’re building

The portal lists eight things at once, which is useful as a reference and slightly overwhelming as a starting point. In practice, what you’re building narrows it to one or two resources immediately:

Building an internal tool or a one-off script
Start with an SDK — @norbelys/sdk (npm) or norbelys (PyPI), or the Go/Ruby packages. Typed methods, pagination handled, generated from the OpenAPI spec so the field names match the docs exactly. This is the fastest path if you're writing application code.
Automating something from your terminal or CI pipeline
Install the norbelys CLI (npm i -g norbelys or the curl installer) and authenticate with norbelys login --api-key. Good fit for scheduled checks, pre-deploy gates, and anything that's currently a manual dashboard click on a recurring schedule — see the full case for why a CLI exists at all.
Wiring up an AI agent — Claude, Cursor, or your own
Point the client at mcp.norbelys.com/mcp with your API key or an OAuth sign-in. The agent gets the platform as callable tools immediately, with the same guardrails the dashboard enforces. The agent kit on GitHub is worth cloning first if you're building a custom agent rather than using an off-the-shelf client.
You're not sure yet, or want to see everything raw
Fetch the OpenAPI spec directly and read the paths object, or import it into Postman/Insomnia. It's the one document every other surface is generated from, so reading it tells you what's possible before you've picked a client language.
You're an agency building tooling for multiple clients
Read the agency-specific case for what the MCP server opens up beyond a single-workspace integration — client-scoped agents, not just a client-scoped dashboard login.

What the API itself looks like, briefly

It’s worth knowing the shape of the REST API before you pick a surface to build on, since every other resource on the portal is a projection of it. Requests use bearer auth, list endpoints use cursor pagination rather than page numbers (so results stay stable while your data changes underneath a long-running export), and errors come back typed and specific rather than a generic 400 with a vague message. None of that is unusual for a modern API on its own, but it’s worth confirming before you commit to building against something, and the fastest way to confirm it is to read a few operations in the spec directly rather than take a docs page’s word for it.

Reading the portal like a developer, not a visitor

The page reads differently depending on what you already know. A visitor sees eight links and a search box. A developer evaluating whether to build on the platform should treat it as a checklist to verify, not a page to skim: does the OpenAPI spec actually match what the REST API returns (it does, because one generates the other); does the CLI’s install command actually work without a support ticket (curl -fsSL https://cli.norbelys.com/install | sh, no signup required to try it); is the MCP server’s tool count consistent with the number of operations in the spec (it should track closely, since both are generated from the same source). Treating the portal this way — as a set of claims you can check in under ten minutes — is a more useful first visit than reading the page top to bottom and moving on.

Why one page is enough

The portal works as a single entry point because everything it links to comes from the same place underneath — one typed contract, generating every surface, rather than five separately maintained products that happen to share a homepage. That’s why the page doesn’t need a “getting started” wizard or a decision tree beyond the five paths above: whichever surface fits your workflow, the operations available, the field names, and the authentication model are identical. Pick based on how you like to work, not based on which surface happens to support the feature you need this week.

If you’re a technical founder deciding whether to build your outbound operation this way at all, that’s a longer, persona-specific case. If you’ve already decided and just want the numbers, pricing is the last page you need before creating an API key.