canonical: https://jentic.com/apis/northflankcom/northflank

# Northflankcom Northflank API

Jentic publishes the only available OpenAPI specification for Northflank API, keeping it validated and agent-ready. Northflank is a managed container platform that lets teams deploy services, jobs, and managed addons without operating their own Kubernetes cluster. The API exposes projects, services, jobs, addons (databases, caches, search), addon backups, builds, and platform health, scoped under a project ID. Engineering teams use it to script deployments, manage ephemeral preview environments, and integrate Northflank into CI/CD pipelines.

## For AI agents

Provision and manage Northflank projects, services, jobs, and managed addons such as databases and caches on behalf of engineering teams.

## Scope

Does not handle observability dashboards, billing, or DNS - use for project, service, job, and managed addon operations on the Northflank platform only.

## Capabilities

- List and inspect available addon types before provisioning a database or cache
- Create, update, and delete services within a Northflank project
- Trigger service builds via the API for CI/CD-driven deploys
- Provision managed addons such as PostgreSQL or Redis under a project
- Take and list backups of an addon for disaster recovery
- Create one-off jobs that run a container to completion and then terminate
- Check API health to confirm the platform is reachable before automation runs

## Use cases

### CI/CD-driven service deploys

Engineering teams using GitHub Actions or GitLab CI to deploy to Northflank trigger builds via the API on every merge to main. POST `/v1/projects/{projectId}/services/{serviceId}/builds` kicks the build, and PATCH `/v1/projects/{projectId}/services/{serviceId}` updates resource plans when scale changes. This replaces clicking through the Northflank UI and gives the team an auditable deploy history in CI logs.

Example prompt: POST `/v1/projects/alpha/services/api/builds` and poll until build status reaches succeeded, then return the deployed image tag

### Ephemeral preview environments

Teams running per-PR preview environments use the Northflank API to create a service per PR, run smoke tests, and tear it down on merge or close. POST `/v1/projects/{projectId}/services` creates the service in a project scoped to previews, and DELETE `/v1/projects/{projectId}/services/{serviceId}` removes it. This pattern keeps stale preview environments from accumulating across hundreds of PRs.

Example prompt: Create a service named 'pr-1234' in project previews with the PR's image tag, then delete it when the PR closes

### Managed database lifecycle

Teams using Northflank's managed addons need to back up, restore, and resize databases without manual ticket flow. POST `/v1/projects/{projectId}/addons` creates a managed addon, `/addons/{addonId}/backups` lists and creates backups, and PATCH on the addon resizes it. An agent can run nightly backup verification and resize during scheduled maintenance windows.

Example prompt: POST `/v1/projects/alpha/addons/db/backups` to take a backup, then list backups to confirm it succeeded

### AI agent for platform operations

An on-call engineer asking an AI agent to scale up the API service can have the agent use Jentic to find the matching Northflank operation, PATCH the service's resource plan, and confirm the change took effect. The agent never holds the bearer token directly; Jentic injects it from the encrypted vault.

Example prompt: Through Jentic, search 'update a Northflank service', load PATCH `/v1/projects/{projectId}/services/{serviceId}`, and execute with the new resource plan

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/` | API health check |
| GET | `/v1/addon-types` | List available addon types |
| POST | `/v1/projects/{projectId}/services` | Create a service in a project |
| PATCH | `/v1/projects/{projectId}/services/{serviceId}` | Update a service |
| POST | `/v1/projects/{projectId}/services/{serviceId}/builds` | Trigger a service build |
| POST | `/v1/projects/{projectId}/addons` | Create an addon in a project |
| POST | `/v1/projects/{projectId}/addons/{addonId}/backups` | Create an addon backup |
| DELETE | `/v1/projects/{projectId}/services/{serviceId}` | Delete a service |

## Key resources

- **Projects** — Top-level container for services, jobs, and addons
- **Services** — Long-running container deployments with builds and resource plans
- **Jobs** — One-off container runs that execute and terminate
- **Addons** — Managed databases, caches, and search engines
- **Addon Backups** — Snapshots taken on managed addons
- **Addon Types** — Catalog of available addon kinds before provisioning
- **Health** — Platform health endpoint for pre-flight checks

## Why Jentic

- **Setup:** Wiring Northflank by hand means setting up its bearer token against api.northflank.com and threading that header through project, service, and addon calls yourself. Through Jentic you install once, import the Northflank API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Northflank puts the project and service ids in the URL path (`/v1/projects/{projectId}/services/{serviceId}/...`), so a rule can pin your agent to one project. You choose the operations it may call, so a destructive DELETE on a service is not included unless you add it.
- **Credential handling:** Your Northflank bearer token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Northflank service' or 'trigger a build', and Jentic returns the matching operation with its input schema so the agent posts to `/v1/projects/{projectId}/services` without browsing the reference docs.

## Related APIs

- **Render API** — Render is a similar managed container platform with simpler pricing.
- **Vercel API** — Vercel is the dominant frontend hosting platform with serverless backends.
- **Kubernetes API** — Kubernetes is the underlying primitive that Northflank manages on your behalf.
- **DigitalOcean API** — DigitalOcean App Platform offers a similar managed container experience.

## FAQ

### Why is there no official OpenAPI spec for Northflank API?

Northflank does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Northflank API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Northflank API use?

Northflank uses HTTP bearer authentication. Generate an API token in the Northflank web app and pass it in the Authorization header. Through Jentic, the token is held in the encrypted vault and never enters the agent's prompt context.

### Can I trigger a service build through the Northflank API?

Yes. POST `/v1/projects/{projectId}/services/{serviceId}/builds` starts a build for the service. Use this in CI to deploy on merge - the response returns a build ID you can poll via the build read endpoints to track progress.

### What are the rate limits for the Northflank API?

Northflank does not encode public rate limits in this spec. Treat the API as bound by reasonable platform-engineering throughput; cache `/v1/addon-types` responses and avoid polling `/v1/projects/{projectId}/services` more than once per 30 seconds in monitoring loops.

### How do I provision a managed Postgres addon through Jentic?

Install with pip install jentic, then search 'create a Northflank addon', load POST `/v1/projects/{projectId}/addons`, and execute with the addon type set to a Postgres variant from `/v1/addon-types.` The response includes the addon ID for backups and connection-string lookups.

### Does the Northflank API support managed addon backups?

Yes. GET `/v1/projects/{projectId}/addons/{addonId}/backups` lists existing backups and POST on the same path triggers a new backup. Use this for scheduled disaster-recovery drills as well as ad-hoc snapshots before risky migrations.

### Can I limit what my agent is allowed to do with the Northflank API?

Yes. Because you run Jentic One yourself, your own rules decide which Northflank operations and which stored bearer token the agent may use. Since Northflank puts the project and service IDs in the URL path, such as `/v1/projects/{projectId}/services/{serviceId}`, you can pin the agent to a single project and grant only safe calls like POST `/v1/projects/{projectId}/services` or POST `/v1/projects/{projectId}/services/{serviceId}/builds.` A destructive call such as DELETE `/v1/projects/{projectId}/services/{serviceId}` stays out of reach unless you explicitly allow it.