Build against the platform

This path is for a developer or integrator wiring Sencai into something else - a deployment script, an internal dashboard, a pipeline, or an AI assistant that needs to know what your organization is running.

By the end you will have made one authenticated request that returns your own organization’s record, you will know how a request gets scoped and what the versioning guarantees actually are, and you will have a map of the hosted developer tooling that sits next to the API: repositories, pipelines, and the container registry.

It assumes you already have an account, belong to an organization, and recognize the object model well enough to read a response. If any of that is shaky, read Core concepts first.

One of the eight steps ends at a wall - you can register a webhook endpoint, but the platform will not call it yet. It stays in the path because knowing where the edge is beats discovering it in production.

Before you start

Two things must be true before step 2 works at all, and everything after it depends on step 2.

• Your organization is on a paid plan. Issuing an API token of any scope - including a read-only one - is refused on the Free plan with a payment-required error. The Generate key button is visible either way, so the refusal only shows up once you click it. See Organization plans.
• You are an Owner or an Admin. Creating and revoking tokens are restricted to those two roles. Auditor is a read-oriented role that sits below Admin and does not qualify. See Roles & permissions.

Worth knowing up front: a token belongs to one organization and scopes every request to it automatically - you never pass an organization ID. If you work across several organizations, that means one token each. And if you want an AI client to take actions rather than only read, an Owner or Admin has to turn on the organization’s AI-agent write access separately from the token’s own scope.

The SDKs are not the way in

Sencai has Go, Python, and TypeScript clients, but none of them is published to a package registry and there is no public repository to install from - you have to ask your account team for a build. They were also generated from an older description of the API and do not cover the token-scoped endpoints this path uses. Start with direct HTTP calls; read SDKs only once you have a specific reason to.

The path

The order follows the dependencies. Conventions come first, because the response envelope and error format are what you will be parsing at every later step. The token comes second, because nothing else authenticates without it - and the AI-client step uses that same token rather than a credential of its own. Versioning lands before you write client code, since the cheapest moment to pin a version is before there is anything to migrate. The three developer-tooling pages are a block in dependency order: repositories hold the workflow files and secrets, pipelines run them, the registry receives what they build. Webhooks come last on purpose.

0 of 8 read

1. 1 Learn the API conventions Base URL, the two authentication methods, the response envelope, and the error format. Open →
2. 2 Create a scoped token Name it, scope it, set an expiry, and know the conditions a write request has to satisfy. Tokens of any scope require a paid organization plan. A Free organization is refused. Open →
3. 3 Understand versioning Deprecation and sunset signaling, so an integration fails loudly and early rather than silently and late. Open →
4. 4 Connect an AI client Point an MCP-capable client at the server with a bearer token and use the read tools. Open →
5. 5 Use the hosted repositories Create a repository in your organization's namespace, clone it, and add deploy keys and secrets. Open →
6. 6 Run pipelines Workflow files, where they live, and how runs are reported back. Open →
7. 7 Use the container registry Curated public images, your own private packages, and how external registries fit in. Open →
8. 8 Register webhook endpoints Create an endpoint, verify the signature on what arrives, and fire a test delivery. The platform does not yet call your endpoint when events happen. Only the Test button generates traffic today. Open →

What to watch out for

The resource table on the API overview is an orientation map, not a promise. It lists path prefixes for a dozen resource families, and most of them need the same signed-in browser session the web app itself uses - which is not a credential you can put in an unattended script. A personal access token reaches a much narrower surface: your organization’s own information, cloud instances, fleet agents, and compliance score for reading, plus three gated write actions. Confirm what a token actually reaches on API tokens before you design around a prefix in that table.

A write-scoped token still cannot write on its own. Three conditions are checked server-side on every mutating call: the token carries the read_write scope, an Owner or Admin has turned on AI-agent write access for the organization, and the organization is on a paid plan. All three, every time. Write actions are also being enabled gradually, so a specific one may be unavailable even with everything switched on.

Webhook delivery is not wired up yet. You can register an endpoint, choose event types, and save it - and the platform will not call you when one of those events happens. The Test button on the endpoint’s row is the only thing that generates traffic today. Replay on a failed delivery marks it replayed and updates its attempt count for your own tracking rather than being a reliable way to re-send. Verify your receiver against Test by all means, but do not put a webhook on the critical path of anything.

A webhook signing secret is shown once and cannot be rotated. Copy it at creation. If it leaks, your only move is deleting that endpoint and registering a new one, then pointing your receiver at the new secret. The signature carries no timestamp either, so replay protection is yours to build. Verify the HMAC over the raw bytes you received, not over a re-serialized copy of the parsed JSON.

A 404 can mean “not yours” rather than “not there”. The API deliberately does not distinguish a resource that does not exist from one you cannot see, so do not write repair or retry logic that reads 404 as absence. Handle 402 separately as well: it means your plan does not include what you asked for, and retrying never fixes it.

Repository access is organization membership, nothing finer. Any member of the owning organization can browse, clone, and manage every repository in it. There is no per-repository permission model, so a repository only part of your team should reach needs its own organization.

Mirrored repositories do not trigger pipeline runs. A mirror syncs by pulling, so no push event fires. Use a schedule trigger inside the workflow file, or trigger the run manually.

Sencai does not store your pipeline logs. The run list is metadata - status, workflow, repository, ref, duration - and reading what a step printed means following the link out to the underlying Git host. Do not build alerting that expects log text from Sencai’s own run records.

No CI runner status means “ready for jobs”. A runner reports provisioning, compute-up-but-not-bootstrapped, awaiting-registration, failed, or terminated - and the list only turns green once a runner has been torn down. If one has been awaiting registration for a long time, delete it and create another rather than waiting it out. Provisioning a runner also needs a connected cloud provider account first.

Registry scanning is not a pre-deploy gate. Vulnerability findings cover the images your running instances are using, and scanning has to be turned on for your environment before anything appears at all. An image sitting in the registry unused is not checked.

There is one API version and no published notice period. /api/v1 is all there is today, and Sencai has not committed to a fixed window between marking a version deprecated and switching it off. Call /api/v1 explicitly instead of relying on a default, and treat the deprecation and sunset dates on Settings → API Versions (/gravity/settings/api-versions) as the source of truth rather than assuming you will get a quarter’s warning.

What’s next

• SDKs - the generated clients, what they cover, and how to get hold of one
• Toolbox & code review - automated review of a pull request in a repository you host here
• Marketplace - publish something deployable instead of only consuming the API
• Audit log - where every write your integration makes is recorded
• Learning paths - the other five routes through this documentation