Public API

Public API

Die YourCloud Public API ermöglicht es dir, Deployments, Volumes, IPs und Accounts programmatisch zu steuern. Diese Seite bietet eine Übersicht über Authentifizierung, Endpoints, Beispiele und Best Practices.

Kurzüberblick

Basis-URL: https://core.yourcloudfire.com/api/v1
Antworten sind JSON-formatiert. Alle Endpoints unterliegen Auth- und Rate-Limits (siehe unten).

Authentifizierung

Nutze API-Keys (Bearer token). Erzeuge Tokens im Dashboard → Profil → API Tokens.

Header Beispiel: 
Authorization: Bearer <YOUR_API_TOKEN>

Scopes

  • read – Lesezugriff auf Ressourcen
  • write – Erstellen / Ändern von Ressourcen
  • admin – Admin-Operationen (nur Enterprise / Admin-Accounts)

Rate Limits

Standard-Limit: 120 requests / Minute pro API-Key. Überschreiten führt zu HTTP 429.

Header, die Limit-Informationen liefern:

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Wichtige Endpoints

User

GET  /users/me
Response:
{
  "id": "user_abc123",
  "email": "you@example.com",
  "plan": "pro",
  "credits": 20
}

Deployments

POST /deployments
Body:
{
  "name": "my-app",
  "template": "ubuntu-22.04",
  "cpu": 2,
  "ram_mb": 2048,
  "volume_gb": 20
}

GET  /deployments
GET  /deployments/{id}
DELETE /deployments/{id}

Volumes

POST /volumes
Body:
{
  "name": "db-storage",
  "size_gb": 50
}

GET /volumes
POST /volumes/{id}/attach
POST /volumes/{id}/resize
DELETE /volumes/{id}

Networking / IPs

POST /ips/reserve
POST /ips/{id}/assign
GET  /ips
DELETE /ips/{id}

Webhooks

Webhooks können für Events wie deployment.created, deployment.failed oder billing.charge registriert werden. 

POST /webhooks
Body:
{
  "url": "https://hooks.example.com/your-endpoint",
  "events": ["deployment.created","deployment.finished"]
}

Security: Signiere deine Endpoints mit dem secret, das im Response zurückgegeben wird.

Pagination & Filtering

Listen-Endpoints unterstützen Cursor- oder Offset-Pagination: 

GET /deployments?limit=25&cursor=eyJ...&filter[status]=running
Response contains: "next_cursor"

Filter sind über das Query-String Schema filter[FIELD]=VALUE möglich.

Fehler & Statuscodes

  • 200 – OK
  • 201 – Created
  • 400 – Bad Request (Validation Error)
  • 401 – Unauthorized (Token fehlt/ungültig)
  • 403 – Forbidden (Scope fehlt)
  • 404 – Not Found
  • 429 – Rate Limit Exceeded
  • 500 – Server Error

SDKs & Beispiele

Beispiel: Node.js (fetch)

// Node.js example
const res = await fetch('https://core.yourcloudfire.com/api/v1/deployments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'my-app', template: 'ubuntu-22.04' })
});
const data = await res.json();
console.log(data);

Weitere SDKs: Python client, Go client (coming soon).

Changelog & Versioning

Wir verwenden semantische Versionierung für die API: v1, v2, … Änderungen werden im Changelog angekündigt.

  • Breaking changes: Major release (v2) mit ausführlicher Migration-Guide
  • Feature additions: Minor releases
  • Bugfixes: Patch releases

Weiterführende Links