API

Merk

pigeon.as beta:

Kun tilgjengelig for beta-testere. Send epost til info@pigeon.as for mer info.

API-nøkler

API-nøkler er knyttet til én organisasjon.

Maskiner

POST   /v1/machines
GET    /v1/machines
GET    /v1/machines/{id}
PUT    /v1/machines/{id}
DELETE /v1/machines/{id}

POST   /v1/machines/{id}/start
POST   /v1/machines/{id}/stop
POST   /v1/machines/{id}/suspend
POST   /v1/machines/{id}/exec
POST   /v1/machines/{id}/fork
GET    /v1/machines/{id}/logs

GET    /v1/machines/{id}/snapshots
POST   /v1/machines/{id}/snapshots
DELETE /v1/machines/{id}/snapshots/{snapshot_id}

Eksempel: web-app

{
  "name": "web",
  "image": "ghcr.io/example/web:latest",
  "scaling": {
    "min": 0,
    "max": 2
  },
  "ports": [
    {
      "port": 8080,
      "protocol": "http",
      "concurrency": {
        "type": "requests",
        "target": 20
      }
    }
  ],
  "auto_stop": {
    "action": "suspend"
  }
}

Eksempel: agent

{
  "name": "agent",
  "image": "ghcr.io/example/agent:latest",
  "max_cpu": 8,
  "max_memory": "16GB",
  "secrets": {
    "ANTHROPIC_API_KEY": "anthropic-api-key"
  },
  "auto_stop": {
    "action": "suspend"
  }
}

Parametere

Felt	Type	Påkrevd	Beskrivelse
name	string	ja	Navn på maskinen
image	string	ja	OCI-image
scaling	object	nei	Minste og største antall kjørende instanser
constraints	object	nei	Begrensninger for hvor maskinen kan kjøre
max_cpu	number	nei	Maks antall CPU-kjerner
max_memory	string	nei	Maks minne, for eksempel 512MB eller 16GB
max_storage	string	nei	Maks innebygd lagring. Standard er 100GB
cpu_type	string	nei	shared eller dedicated
command	string[]	nei	Kommando som kjøres i stedet for imagets standardkommando
env	object	nei	Miljøvariabler
secrets	object	nei	Kobler hemmeligheter til miljøvariabler
ports	object[]	nei	Nettverksporter
domains	string[]	nei	Egendefinerte domener
volumes	object[]	nei	Ekstra volumer
auto_start	boolean	nei	Start maskinen automatisk ved trafikk. Standard er true
auto_stop	object	nei	Automatisk stopp ved inaktivitet
restart	object	nei	Regler for automatisk restart
deploy	object	nei	Regler for utrulling

Instansene vises i instances.

{
  "name": "web",
  "scaling": {
    "min": 0,
    "max": 3
  },
  "instances": [
    {
      "id": "web1",
      "state": "running"
    },
    {
      "id": "web2",
      "state": "running"
    },
    {
      "id": "web3",
      "state": "suspended"
    }
  ]
}

Maskiner har 100 GB innebygd lagring som standard. Lagring faktureres etter faktisk bruk.

Skalering

{
  "scaling": {
    "min": 0,
    "max": 20
  }
}

Felt	Type	Påkrevd	Beskrivelse
min	number	ja	Minste antall kjørende instanser
max	number	ja	Største antall kjørende instanser

Lik min og max gir et fast antall. Med min: 0 kan alle instanser stoppe eller gå i dvale.

concurrency.target avgjør når kapasiteten skal økes eller reduseres.

Constraints

{
  "regions": ["eu-west"]
}

Felt	Type	Påkrevd	Beskrivelse
regions	string[]	nei	Tillatte regioner
locations	string[]	nei	Tillatte lokasjoner

Automatisk stopp

{
  "action": "suspend"
}

Felt	Type	Påkrevd	Beskrivelse
after	string	nei	Tid uten aktivitet før handlingen utføres, for eksempel 5m
action	string	ja	stop eller suspend

HTTP-trafikk, aktive forbindelser og kjørende exec regnes som aktivitet.

Restart

{
  "policy": "on-failure"
}

Felt	Type	Påkrevd	Beskrivelse
policy	string	nei	never, on-failure eller always. Standard er on-failure

Utrulling

Utrulling uten nedetid er standard når maskinkonfigurasjonen oppdateres.

{
  "strategy": "rolling"
}

Felt	Type	Påkrevd	Beskrivelse
strategy	string	nei	rolling, canary eller bluegreen. Standard er rolling

Nye maskiner må være friske før trafikk flyttes fra den gamle versjonen.

Porter

Felt	Type	Påkrevd	Beskrivelse
port	number	ja	Port på maskinen
protocol	string	ja	http, tcp eller udp
external_port	number	nei	Offentlig port når den avviker fra maskinens port
concurrency	object	nei	Kapasitet for ruting og automatisk oppstart
health_check	object	nei	Helsesjekk for porten

Helsesjekk

{
  "path": "/health"
}

Felt	Type	Påkrevd	Beskrivelse
path	string	ja	HTTP-path som må svare før maskinen regnes som klar

Uten health_check brukes en automatisk sjekk av porten.

Concurrency

{
  "type": "requests",
  "target": 20
}

Felt	Type	Påkrevd	Beskrivelse
type	string	nei	requests eller connections
target	number	ja	Ønsket samtidig belastning før annen kapasitet foretrekkes eller startes

For HTTP brukes requests som standard. For TCP brukes connections.

target er en kapasitetsverdi for ruting og automatisk oppstart, ikke en hard grense for trafikk.

Volumer

Felt	Type	Påkrevd	Beskrivelse
id	string	ja	Volum-ID
path	string	ja	Monteringspunkt i maskinen

Hemmeligheter

{
  "DATABASE_URL": "database-url",
  "STRIPE_API_KEY": "stripe-key"
}

Hemmeligheter kobles til miljøvariabler som MILJØVARIABEL: secret-navn.

Secret-verdier lagres i Vault, ikke i maskinkonfigurasjonen.

Exec

{
  "command": ["uptime"]
}

Kommandoen kjøres på alle instansene. Velg én eller flere med instances:

{
  "command": ["uptime"],
  "instances": ["web1", "web2"]
}

Felt	Type	Påkrevd	Beskrivelse
command	string[]	ja	Kommando som skal kjøres
instances	string[]	nei	Instanser som skal kjøre kommandoen. Standard er alle

Fork

{
  "name": "experiment"
}

Oppretter en ny, uavhengig maskin fra den eksisterende maskinens tilstand.

Felt	Type	Påkrevd	Beskrivelse
name	string	ja	Navn på den nye maskinen
instance	string	nei	Fork én bestemt instans

Domener

{
  "domains": [
    "example.com",
    "www.example.com"
  ]
}

Pigeon håndterer TLS og sertifikatfornyelse automatisk.

Volumer

POST   /v1/volumes
GET    /v1/volumes
GET    /v1/volumes/{id}
PUT    /v1/volumes/{id}
DELETE /v1/volumes/{id}

GET    /v1/volumes/{id}/snapshots
POST   /v1/volumes/{id}/snapshots
DELETE /v1/volumes/{id}/snapshots/{snapshot_id}

Eksempel:

{
  "name": "data",
  "size": "10GB",
  "constraints": {
    "regions": ["eu-west"]
  }
}

Parametere

Felt	Type	Påkrevd	Beskrivelse
name	string	ja	Navn på volumet
size	string	ja	Størrelse, for eksempel 10GB eller 500GB
constraints	object	nei	Begrensninger for hvor volumet kan brukes
snapshot_id	string	nei	Opprett volumet fra et snapshot

Volumer kobles til maskiner gjennom maskinkonfigurasjonen.

Hemmeligheter

POST   /v1/secrets
GET    /v1/secrets
DELETE /v1/secrets/{name}

Eksempel:

{
  "name": "database-url",
  "value": "postgres://..."
}

Parametere

Felt	Type	Påkrevd	Beskrivelse
name	string	ja	Navn på hemmeligheten
value	string	ja	Verdi

Verdien vises ikke igjen etter at hemmeligheten er opprettet.

Regioner

GET /v1/regions

Tilgjengelige regioner og tilhørende lokasjoner.

Forbruk

GET /v1/usage
GET /v1/machines/{id}/usage

Målt forbruk (CPU, minne, lagring og nettverk).