API v1 · Documentation

From first request to production, documented clearly.

Nimbus gives you a cloud API with concise guides for authentication, endpoints, and integration — so you spend time building, not searching.

Start Buildingcurl api.nimbus.dev/v1/status
  • Clear auth
  • Fast endpoint lookup
  • Developer-first structure
nimbus / request-flow
Abstract diagram of an API request flow from client through authentication gateway to endpoint services
auth
Bearer
base
/v1
format
JSON
Request lifecycle: client → auth → endpoint → response.

01 / Overview

What Nimbus is

A REST API for provisioning, storing, and querying cloud resources — authenticate once, then call versioned endpoints over HTTPS.

What it enables

capabilities
  • Create and manage projects, keys, and resources
  • Store and query JSON objects at scale
  • Subscribe to events via webhooks

Who it's for

audience
  • Backend developers integrating services
  • Platform teams automating infrastructure
  • Product builders shipping data-backed features

How the docs are organized

structure
Authentication
API keys, bearer tokens, scopes
Endpoints
Methods, params, responses
FAQ
Limits, errors, versioning
Request flow
  1. client
  2. Authorization: Bearer
  3. /v1/{resource}
  4. 200 · JSON

02 · Authentication

Authentication

Every Nimbus request is authenticated with a short-lived bearer token issued in exchange for a project API key. The flow takes four steps and one header.

  1. Create an API key

    Open Dashboard → Settings → API keys and generate a key for your project. Test keys start with nb_test_, live keys with nb_live_.

  2. Exchange the key for an access token

    Send a server-side POST /v1/auth/token request with your key and the scopes you need. The response returns an access_token valid for 3600 seconds.

  3. Send the token on every request

    Attach the token in the Authorization: Bearer <token> header. All routes in the endpoint reference expect this header.

  4. Refresh before expiry

    Request a new token shortly before expires_in elapses. If a call returns 401 token_expired, repeat step 02 and retry once.

03 / Endpoints

How the API is organized

Every resource lives under a versioned base URL and follows the same REST conventions: predictable paths, JSON bodies, and consistent error objects.

Base URL
api.nimbus.dev/v1
Format
application/json

  • Projects

    4 ops

    Create and manage the workspaces that scope keys, usage, and resources.

    /v1/projects

  • Deployments

    5 ops

    Ship container images to a region and track rollout status.

    /v1/projects/:id/deployments

  • Storage

    6 ops

    Upload, list, and version objects in project-scoped buckets.

    /v1/buckets

  • Webhooks

    3 ops

    Subscribe to events and receive signed payloads at your endpoint.

    /v1/webhooks
POST/v1/projects/:id/deployments
Example: create a deployment

Request

curl -X POST \
  https://api.nimbus.dev/v1/projects/prj_42/deployments \
  -H "Authorization: Bearer $NIMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "eu-west-1",
    "image": "app:1.4.2"
  }'

Response 201 Created

{
  "id": "dep_8f3a21",
  "object": "deployment",
  "status": "queued",
  "region": "eu-west-1",
  "image": "app:1.4.2",
  "created_at": "2026-09-25T10:14:03Z"
}
Auth: Bearer tokenIdempotency: Idempotency-KeySet up authentication →

FAQ

Frequently asked questions

Quick answers to the questions teams ask most while moving from first request to production.

How long does it take to make a first API call?

Most teams send an authenticated request in under ten minutes. Create a project, generate a key, and run the GET /v1/status quickstart call.

Which credentials do I need, and where do they go?

Use a secret API key for server-side calls, sent as Authorization: Bearer <key>. Keep keys out of client code; use scoped tokens for browsers and mobile apps. See Authentication.

What are the rate limits?

Default projects allow 100 requests per second per key. Every response includes X-RateLimit-Remaining; on 429, back off using the Retry-After header.

How is the API versioned?

Major versions live in the path, such as /v1. Additive changes ship without notice; breaking changes arrive only in a new major version, with at least 12 months of support for the previous one.

What should I include when contacting support?

Share the X-Request-Id from the response, the endpoint, a timestamp, and the error body. Never send secret keys. With that context, most tickets are resolved in a single reply.

Still have a question? Your first request is the fastest answer.

Start Building