API quickstart

Make your first request, create a project and launch a container.

Use the REST API at https://api.kinesis.network/v1. You need a Kinesis account and an API key from Account settings.

Open the API keys section in Account settings, create a key and copy its token when shown. Complete the two-factor setup or verification prompt if requested.

1

Check your connection

The examples below use a POSIX shell. Set KINESIS_API_KEY in your shell or secret manager, then inspect the identity and permissions attached to it:

curl --fail-with-body https://api.kinesis.network/v1/me \
  -H "Authorization: Bearer $KINESIS_API_KEY"

Inspect apiKey.scopes, apiKey.projectIds and limitedToOrgs, then list reachable organizations:

curl --fail-with-body https://api.kinesis.network/v1/orgs \
  -H "Authorization: Bearer $KINESIS_API_KEY"

Choose the returned organization slug and set KINESIS_ORG to it. Your role there must be Admin or Developer to create a project.

2

Create a project

Requires projects:write. A key restricted to specific projects cannot create a new project; use an unrestricted key or an existing permitted project.

curl --fail-with-body "https://api.kinesis.network/v1/projects?org=$KINESIS_ORG" \
  -H "Authorization: Bearer $KINESIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-project-001' \
  -d '{"name":"API quickstart","visibility":"private"}'

Copy the returned id into PROJECT_ID. Use a new idempotency key for a different project; reuse this key and the same body only when retrying this request.

3

Launch a container

Requires apps:write and compute:spend. Creating an app attempts to start it and can consume the organization’s credits. The project identifies the organization; no org parameter is needed for this resource call. This example uses serverless capacity: a Developer needs it enabled, or must add an accessible grid under config.grids.ids.

curl --fail-with-body "https://api.kinesis.network/v1/projects/$PROJECT_ID/apps" \
  -H "Authorization: Bearer $KINESIS_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-app-001' \
  -d '{
    "name":"hello-kinesis",
    "config":{
      "image":"nginx:stable",
      "ports":[{"port":80,"protocol":"http80_load_balancer"}],
      "instances":{"min":1,"max":1}
    }
  }'

Copy the app's id into APP_ID. Inspect start.state: requested, deferred, building or failed. A created app is not necessarily ready to serve traffic.

4

Follow the deployment

Requires apps:read. Poll status and use the addresses returned in endpoints:

curl --fail-with-body \
  "https://api.kinesis.network/v1/projects/$PROJECT_ID/apps/$APP_ID/status" \
  -H "Authorization: Bearer $KINESIS_API_KEY"

Read state, targetState, nodes and errors. An endpoint with a null address is not wired yet. For a repository deployment, poll the returned buildId first.

5

Stop when you are finished

curl --fail-with-body -X POST \
  "https://api.kinesis.network/v1/projects/$PROJECT_ID/apps/$APP_ID/stop" \
  -H "Authorization: Bearer $KINESIS_API_KEY"

Poll status until stopped. App and project deletion require their apps to be stopped first. Dedicated-server billing is managed through the server lifecycle; stopping an app does not by itself prove that a dedicated server is hibernated.

Next: Authentication and scopes, request conventions, or the Apps reference.