DokumentationProdukteShellBaseServer-APIServer-API V1
Server anlegen
In API Explorer austestenÖffnet den Explorer mit Methode und Pfad dieses Requests.
Trägt einen Server ins Inventar ein.
authValue — Passwort oder privater Schlüssel — wird verschlüsselt gespeichert und niemals zurückgegeben. Das Kontingent des Zugangs gilt: ist es erschöpft, endet die Anfrage mit 400.
POST https://servers.api.shellbase.artim-industries.com/v1/servers
| Methode | POST |
| Basis | servers.api.shellbase.artim-industries.com/v1 |
| Scope | sb.servers:write |
| Antwort | 201 |
| Zugang | Developer Mitgliedschaft |
| Auth | Authorization: Bearer sbapi_… |
Parameter
Dieser Endpunkt nimmt keine Parameter.
Anfragekörper
| Feld | Typ | Bedeutung |
|---|---|---|
name | string | Anzeigename. Pflicht. |
host | string | Adresse oder Hostname. Pflicht. |
username | string | Benutzer für die Verbindung. Pflicht. |
authType | string | ssh-key oder password. Pflicht. |
authValue | string | Der private Schlüssel bzw. das Passwort. |
port | integer | SSH-Port, Standard 22. |
tags | array | Marken. |
os | string | Betriebssystem, falls bekannt. |
relayId | string | Relay, über das er erreicht wird. |
Felder, die der Vertrag nicht nennt, werden verworfen — ein Client kann keine eigenen Felder unterschieben.
{
"name": "api-01",
"host": "10.0.4.21",
"port": 22,
"username": "deploy",
"authType": "ssh-key",
"authValue": "-----BEGIN OPENSSH PRIVATE KEY-----
…",
"tags": ["api", "prod"]
}
Anfrage
curl -X POST "https://servers.api.shellbase.artim-industries.com/v1/servers" \
-H "Authorization: Bearer sbapi_…" \
-H "Content-Type: application/json" \
-d '{ "name": "api-01", "host": "10.0.4.21", "port": 22, "username": "deploy", "authType": "ssh-key", "authValue": "-----BEGIN OPENSSH PRIVATE KEY----- …", "tags": ["api", "prod"] }'
Antwort
| Feld | Typ | Bedeutung |
|---|---|---|
id | string | Kennung des neuen Servers. |
name | string | Anzeigename. |
status | string | offline, bis der erste Abgleich lief. |
tags | array | Marken. |
{ "id": "…", "name": "api-01", "host": "10.0.4.21", "port": 22, "status": "offline", "tags": ["api", "prod"] }
Fehler
| Status | code | Wann |
|---|---|---|
400 | invalid_request | Ein Pflichtfeld fehlt, ein Typ passt nicht, oder ein Verweis zeigt auf etwas, das es hier nicht gibt. |
401 | invalid_token | Bearer fehlt, ist unbekannt oder abgelaufen. |
403 | missing_scope | Das Token trägt den Scope dieses Endpunkts nicht. |
404 | not_found | Der Eintrag gehört nicht zum freigegebenen Team — oder die Anfrage kam auf der falschen Subdomain an. |
409 | conflict | Der Zustand verbietet die Änderung — der Fehlerkörper nennt den Grund. |
429 | rate_limited | Kontingent erschöpft, siehe Retry-After. |
Jede Fehlerantwort trägt dieselbe Hülle: error.code benennt den Fehler, error.message sagt in einem Satz, was fehlt.
Rate Limits
Das Limit gilt pro Team, nicht pro Token.
| Zugang | Produktion | Sandbox |
|---|---|---|
| Hobby | 60 Anfragen/Minute | ohne Limit |
| Developer Mitgliedschaft | 10.000 Anfragen/Minute | ohne Limit |
Bei 429 sagt der Retry-After-Header, wie lange du warten sollst.