API Reference

Create, inspect, and tear down NapStack environments programmatically. One API key, four endpoints.

Quickstart

Spin up a full web app environment in a single request.

Generate an API key in Settings. You'll get a key starting with nsk_

Create an environment:

Create an environment

curl -X POST https://napstack.io/api/v1/environments \
  -H "X-API-Key: nsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-staging",
    "blueprint": "web-app"
  }'

Poll until it's live:

Check status

curl https://napstack.io/api/v1/environments/{id} \
  -H "X-API-Key: nsk_your_key_here"

# Repeat until status is "live"

Tear it down when you're done:

Delete environment

curl -X DELETE https://napstack.io/api/v1/environments/{id} \
  -H "X-API-Key: nsk_your_key_here"

Authentication

All API requests require an API key passed via the X-API-Key header.

Example request header

curl https://napstack.io/api/v1/environments \
  -H "X-API-Key: nsk_your_key_here"

Key management

Generate or regenerate your key in Settings. Keys start with nsk_.
The full key is shown only once at creation. Store it securely.
One key per account. Regenerating invalidates the previous key immediately.
Revoke your key at any time from Settings.

Keep your key secret. Do not commit it to version control. Use environment variables or a secrets manager in CI/CD pipelines.

Base URL

https://napstack.io/api/v1

All endpoints below are relative to this base URL. Responses are JSON with Content-Type: application/json.

Endpoints

Four endpoints. That's the entire API.

POST/environmentsCreate environment GET/environmentsList environments GET/environments/{id}Get environment DELETE/environments/{id}Delete environment

POST/environments

Create and deploy an environment in one call. Returns immediately with status "deploying" — poll the GET endpoint until status is "live".

Request body

Parameter	Type	Default	Description
`name`required	`string`	—	Display name for the environment. Letters, numbers, spaces, hyphens.
`blueprint`	`string`	—	Shorthand: "web-app" or "ai-gpu". Sets sensible defaults for resources, budget, and lifecycle.
`resources`	`ResourceSpec[]`	—	Full resource array for power users. Required if no blueprint is set.
`region`	`string`	`us-east-1`	AWS region. Defaults to your AWS account's region.
`budget`	`number`	`25–500`	Monthly AWS budget cap in dollars ($1–$10,000). Default depends on blueprint.
`lifecycle`	`string`	`"auto-sleep"`	"always-on", "auto-sleep", or "scheduled".
`ttlDays`	`number \| null`	`null`	Auto-delete after N days. null = no expiry.
`autoSleepMinutes`	`number`	`30`	Idle timeout in minutes before auto-sleep. Only applies when lifecycle is "auto-sleep".

Example — using a blueprint

Request

curl -X POST https://napstack.io/api/v1/environments \
  -H "X-API-Key: nsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pr-review-42",
    "blueprint": "web-app",
    "ttlDays": 7,
    "budget": 30
  }'

Response 201 Created

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "pr-review-42",
  "status": "deploying",
  "region": "us-east-1",
  "blueprint": "web-app",
  "resources": [
    { "type": "ec2", "size": "S", "label": "Server", "computeId": "c0", "software": ["docker", "nodejs"] },
    { "type": "postgres", "size": "S" }
  ],
  "budget": 30,
  "lifecycle": "auto-sleep",
  "createdAt": "2026-02-27T14:30:00.000Z"
}

Example — custom resources

Request

curl -X POST https://napstack.io/api/v1/environments \
  -H "X-API-Key: nsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ml-training",
    "resources": [
      { "type": "gpu", "size": "M", "label": "GPU", "computeId": "c0", "software": ["pytorch", "jupyter"] },
      { "type": "s3", "size": "S" }
    ],
    "budget": 600,
    "lifecycle": "auto-sleep",
    "autoSleepMinutes": 15
  }'

GET/environments

List all environments for your account, sorted by creation date (newest first).

Example

Request

curl https://napstack.io/api/v1/environments \
  -H "X-API-Key: nsk_your_key_here"

Response 200 OK

{
  "environments": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "name": "pr-review-42",
      "status": "live",
      "region": "us-east-1",
      "resources": [
        { "type": "ec2", "size": "S", "label": "Server", "computeId": "c0" },
        { "type": "postgres", "size": "S" }
      ],
      "budget": 30,
      "lifecycle": "auto-sleep",
      "appUrl": "https://d1234abcdef.cloudfront.net",
      "createdAt": "2026-02-27T14:30:00.000Z",
      "updatedAt": "2026-02-27T14:32:15.000Z"
    }
  ]
}

GET/environments/{id}

Get a single environment with connection details. Use this to poll for deployment completion or to retrieve connection strings.

Path parameters

Parameter	Type	Default	Description
`id`required	`string`	—	Environment ID (UUID).

Example

Request

curl https://napstack.io/api/v1/environments/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "X-API-Key: nsk_your_key_here"

Response 200 OK

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "name": "pr-review-42",
  "status": "live",
  "region": "us-east-1",
  "resources": [
    { "type": "ec2", "size": "S", "label": "Server", "computeId": "c0" },
    { "type": "postgres", "size": "S" }
  ],
  "budget": 30,
  "lifecycle": "auto-sleep",
  "appUrl": "https://d1234abcdef.cloudfront.net",
  "createdAt": "2026-02-27T14:30:00.000Z",
  "updatedAt": "2026-02-27T14:32:15.000Z",
  "outputs": {
    "appUrl": "https://d1234abcdef.cloudfront.net",
    "serverIps": [
      { "label": "c0", "ip": "54.123.45.67" }
    ],
    "database": {
      "url": "postgresql://napstack-pr-review-42.abc123.us-east-1.rds.amazonaws.com:5432"
    },
    "redis": null,
    "s3Bucket": null,
    "sqsQueueUrl": null,
    "dynamodbTable": null,
    "snsTopicArn": null,
    "opensearchEndpoint": null,
    "logGroup": "/napstack/pr-review-42"
  }
}

DELETE/environments/{id}

Delete an environment and tear down all AWS resources. Returns immediately — the actual teardown runs in the background.

Path parameters

Parameter	Type	Default	Description
`id`required	`string`	—	Environment ID (UUID).

Example

Request

curl -X DELETE https://napstack.io/api/v1/environments/d290f1ee-6c54-4b01-90e6-d701748f0851 \
  -H "X-API-Key: nsk_your_key_here"

Response 200 OK

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "status": "deleting"
}

Blueprints

Blueprints are shorthand presets that configure resources, lifecycle, and budget for common use cases. Pass a blueprint instead of specifying individual resources.

"web-app"Most common

EC2 server (ARM64) + PostgreSQL database. Auto-sleep after 30 minutes idle, 30-day expiry.

Resources	ec2 (S) + postgres (S)
Lifecycle	auto-sleep (30 min)
Budget	$25/mo
TTL	30 days
Software	Docker, Node.js

"ai-gpu"

GPU server (NVIDIA A10G) with PyTorch and Jupyter pre-installed. Auto-sleep after 15 minutes idle, no expiry.

Resources	gpu (S)
Lifecycle	auto-sleep (15 min)
Budget	$500/mo
TTL	No expiry
Software	PyTorch, Jupyter, CUDA

All blueprint defaults can be overridden. For example, you can use the web-app blueprint but set a higher budget or change the lifecycle to always-on.

Resource types

When using the resources array instead of a blueprint, each resource needs a type and size. Compute resources (ec2, gpu) also need label and computeId.

Type	Label	Sizes
`ec2`compute	Server	S (t4g.micro), M (t4g.small), L (t4g.medium)
`gpu`compute	GPU Server	S (g5.xlarge), M (g5.2xlarge), L (g5.4xlarge)
`postgres`	PostgreSQL	S (db.t4g.micro), M (db.t4g.small), L (db.t4g.medium)
`mysql`	MySQL	S (db.t4g.micro), M (db.t4g.small), L (db.t4g.medium)
`redis`	Redis	S (cache.t4g.micro), M (cache.t4g.small), L (cache.t4g.medium)
`opensearch`	OpenSearch	S (t3.small), M (t3.medium), L (m6g.large)
`s3`	File Storage	S / M / L (capacity tiers)
`sqs`	Message Queue	S/M (standard), L (FIFO)
`dynamodb`	DynamoDB	S / M / L (on-demand)
`sns`	SNS Topics	S/M (standard), L (FIFO)
`logs`	CloudWatch Logs	S (7d), M (30d), L (90d)

Compute resource shape

{
  "type": "ec2",       // or "gpu"
  "size": "S",         // "S", "M", or "L"
  "label": "API",      // Display name
  "computeId": "c0",   // Unique ID — "c0", "c1", etc.
  "software": ["docker", "nodejs"]  // Optional pre-installed software
}

// EC2 software:  "docker", "nodejs", "python3", "nginx"
// GPU software:  "pytorch", "tensorflow", "jupyter", "ollama"

Non-compute resource shape

{ "type": "postgres", "size": "S" }
{ "type": "redis", "size": "M" }
{ "type": "s3", "size": "S" }

Environment statuses

The status field on every environment response follows this lifecycle:

pendingCreated, not yet deploying

synthesizingGenerating CloudFormation template

deployingStack creation in progress

liveDeployed and running

failedDeployment or operation failed

deletingTeardown in progress

expiredTTL reached, resources removed

disconnectedNapStack lost access to AWS account

Polling pattern: After creating an environment, poll GET /environments/{id} every 5–10 seconds until status transitions from deploying to live or failed. Typical deploy time is ~2 minutes.

Errors

All errors return a JSON object with an error field containing a human-readable message.

Error response shape

{
  "error": "name is required"
}

Status	Description
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — missing or invalid API key
`404`	Not found — environment doesn't exist or isn't yours
`500`	Internal server error
`502`	AWS connection failed — check your cross-account role

CI/CD examples

Common patterns for using the API in automation.

GitHub Actions — preview environment per PR

.github/workflows/preview.yml

name: Preview environment
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Create environment
        id: create
        run: |
          RESPONSE=$(curl -s -X POST https://napstack.io/api/v1/environments \
            -H "X-API-Key: ${{ secrets.NAPSTACK_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "name": "pr-${{ github.event.number }}",
              "blueprint": "web-app",
              "ttlDays": 7
            }')
          echo "env_id=$(echo $RESPONSE | jq -r '.id')" >> $GITHUB_OUTPUT

      - name: Wait for deploy
        run: |
          for i in $(seq 1 60); do
            STATUS=$(curl -s https://napstack.io/api/v1/environments/${{ steps.create.outputs.env_id }} \
              -H "X-API-Key: ${{ secrets.NAPSTACK_API_KEY }}" | jq -r '.status')
            if [ "$STATUS" = "live" ]; then
              echo "Environment is live!"
              exit 0
            elif [ "$STATUS" = "failed" ]; then
              echo "Deploy failed"
              exit 1
            fi
            sleep 10
          done

Cleanup — delete on PR close

.github/workflows/cleanup.yml

name: Cleanup preview
on:
  pull_request:
    types: [closed]

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Find and delete environment
        run: |
          ENV_ID=$(curl -s https://napstack.io/api/v1/environments \
            -H "X-API-Key: ${{ secrets.NAPSTACK_API_KEY }}" \
            | jq -r '.environments[] | select(.name == "pr-${{ github.event.number }}") | .id')

          if [ -n "$ENV_ID" ]; then
            curl -s -X DELETE https://napstack.io/api/v1/environments/$ENV_ID \
              -H "X-API-Key: ${{ secrets.NAPSTACK_API_KEY }}"
            echo "Deleted environment $ENV_ID"
          fi

Shell script — create and wait

deploy.sh

#!/bin/bash
set -euo pipefail

API_KEY="$NAPSTACK_API_KEY"
BASE="https://napstack.io/api/v1"

# Create
ENV=$(curl -sf -X POST "$BASE/environments" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging", "blueprint": "web-app"}')

ENV_ID=$(echo "$ENV" | jq -r '.id')
echo "Created environment: $ENV_ID"

# Poll until live
while true; do
  STATUS=$(curl -sf "$BASE/environments/$ENV_ID" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "live" ] && break
  [ "$STATUS" = "failed" ] && { echo "Failed!"; exit 1; }
  sleep 10
done

# Get connection details
curl -sf "$BASE/environments/$ENV_ID" \
  -H "X-API-Key: $API_KEY" | jq '.outputs'